{ "openapi": "3.1.0", "info": { "title": "M.A.T.I.A.S. Credit Decision Engine API", "version": "1.0.0", "description": "API REST de M.A.T.I.A.S., la IA de crédito de Akaike Credit Risk Solutions. Su sistema envía la solicitud de crédito y recibe la decisión (aprobado, revisión o rechazo) con tasa, monto, plazo, garantías y documentos, explicada y auditada.\n\n**Flujo típico:** 1) `PUT /v1/data/mapping` una vez por ambiente · 2) `POST /v1/data/ingest` con el JSON de su solicitud tal cual · 3) `POST /v1/decision` · 4) si la decisión queda en `review` pendiente, el resultado final llega a su webhook `decision.updated` o con `GET /v1/decision/{analysis_id}`.\n\nTodas las peticiones (salvo `/health`) llevan `X-API-Key`. **El ambiente lo define la llave**: `mts_sbx_…` solo en sandbox y `mts_prod_…` solo en producción. Límite por llave: 120 peticiones por minuto (`429` con `Retry-After: 60`).", "contact": { "name": "Akaike Credit Risk Solutions", "url": "https://www.akaike.lat", "email": "info@akaike.co" }, "termsOfService": "https://www.akaike.lat" }, "servers": [ { "url": "https://sandbox-api.matias-score.ai", "description": "Sandbox (pruebas, datos sintéticos, burós simulados)" }, { "url": "https://prod-api.matias-score.ai", "description": "Producción" } ], "security": [ { "ApiKey": [] } ], "tags": [ { "name": "Estado" }, { "name": "Diccionario de datos" }, { "name": "Solicitudes" }, { "name": "Buró" }, { "name": "Score" }, { "name": "Decisión" }, { "name": "Solicitantes" }, { "name": "Webhooks" } ], "paths": { "/health": { "get": { "summary": "Estado del servicio", "description": "Sin llave. Útil para monitoreo.", "tags": [ "Estado" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "status": "ok", "service": "M.A.T.I.A.S. Credit Decision Engine", "version": "1.0.0", "db": "up" } } } } }, "security": [] } }, "/v1/providers": { "get": { "summary": "Proveedores de buró disponibles", "description": "Proveedores habilitados para su cuenta y ambiente (en sandbox, solo el simulador).", "tags": [ "Buró" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "timestamp": "2026-10-02T13:05:11.204118", "total_providers": 4, "registered_providers": [ "mock", "datacredito", "datacredito_hcpn", "datacredito_hcpj" ], "providers": [ { "name": "mock", "type": "mock", "configured": true, "available": true }, { "name": "datacredito", "type": "datacredito", "configured": false, "available": false }, { "name": "datacredito_hcpn", "type": "datacredito", "configured": false, "available": false }, { "name": "datacredito_hcpj", "type": "datacredito", "configured": false, "available": false } ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Invalid or missing API key" } } } } } } } }, "/v1/data/mapping": { "get": { "summary": "Ver el diccionario vigente", "description": "Cómo se traducen los nombres de campo de su sistema a los campos de M.A.T.I.A.S.", "tags": [ "Diccionario de datos" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "version": 1, "fields": { "doc_number": { "aliases": [ "documento", "numero_documento", "documento.numeroDocumento" ], "type": "string" }, "loan_amount": { "aliases": [ "monto", "solicitud.simulacion.monto" ], "type": "number" } } } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Invalid or missing API key" } } } } } } }, "put": { "summary": "Publicar una versión del diccionario", "description": "Reemplazo completo. Un alias con puntos es una ruta dentro de su JSON (`documento.numeroDocumento`). `version` debe ser mayor que todas las anteriores. Al publicar, los registros anteriores se reprocesan.", "tags": [ "Diccionario de datos" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "version": 2, "records_scanned": 1240, "records_updated": 1240, "promotion_failures": 0, "message": "Mapping updated successfully" } } } }, "400": { "description": "Invalid mapping", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Invalid mapping" } } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Invalid or missing API key" } } } } }, "409": { "description": "version must be greater than every saved version (current version: 1)", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "version must be greater than every saved version (current version: 1)" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "version": 2, "fields": { "doc_type": { "aliases": [ "tipo_doc", "documento.tipoDocumento" ], "type": "string" }, "doc_number": { "aliases": [ "documento", "documento.numeroDocumento" ], "type": "string" }, "full_name": { "aliases": [ "nombre", "documento.nombreCompleto" ], "type": "string" }, "fecha_nacimiento": { "aliases": [ "fecha_nacimiento", "documento.fechaNacimiento" ], "type": "date" }, "loan_amount": { "aliases": [ "monto", "solicitud.simulacion.monto" ], "type": "number" }, "loan_term": { "aliases": [ "plazo", "solicitud.simulacion.plazoMeses" ], "type": "integer" }, "edad": { "aliases": [], "type": "integer", "derive": { "op": "age_years", "from": "fecha_nacimiento" } }, "desprendible_pdf": { "aliases": [ "desprendible" ], "type": "file" } } } } } } } }, "/v1/data/ingest": { "post": { "summary": "Enviar una solicitud", "description": "Envíe el JSON de su sistema **tal cual**: M.A.T.I.A.S. lo traduce con el diccionario. También acepta `multipart/form-data` (campo `payload` + un archivo por cada campo `file`: PDF, JPEG, PNG o TIFF de hasta 4 MB, máximo 10). Cada envío crea un registro; la decisión usa el último del solicitante.", "tags": [ "Solicitudes" ], "responses": { "201": { "description": "OK", "content": { "application/json": { "example": { "record_id": "9fdca1e525104808e42e03ab4a4ce52e", "dictionary_version": 1, "mapped_fields": [ "doc_number", "doc_type", "fecha_nacimiento", "first_lastname", "full_name", "loan_amount", "loan_term", "referencia" ], "extra_fields": [ "documento", "solicitud" ], "applicant_id": 107, "message": "Record ingested successfully" } } } }, "400": { "description": "doc_type and doc_number are required (check your data mapping aliases)", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "doc_type and doc_number are required (check your data mapping aliases)" } } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Invalid or missing API key" } } } } }, "403": { "description": "Tenant attachment storage quota exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Tenant attachment storage quota exceeded" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Rate limit exceeded" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "referencia": "b25e417e-200f-5a3a-8a97-185d3ecdd12d", "documento": { "tipoDocumento": "CC", "numeroDocumento": "900003121", "nombreCompleto": "MARTA LUCIA FICTICIA SINTETICA", "primerApellido": "FICTICIA", "fechaNacimiento": "1958-03-14" }, "solicitud": { "simulacion": { "monto": 25000000, "plazoMeses": 48 } } } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "payload": { "type": "string", "description": "El JSON de la solicitud" } }, "additionalProperties": { "type": "string", "format": "binary" } } } } } } }, "/v1/data/ingest/{record_id}/attachments": { "get": { "summary": "Listar documentos de un registro", "description": "URLs de descarga firmadas que vencen a los 15 minutos.", "tags": [ "Solicitudes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": [ { "attachment_id": "bee943fb00d0a0c3f6b6d5cf2b0a6032", "field_name": "cedula_foto", "filename": "cedula.jpg", "content_type": "image/jpeg", "size_bytes": 182340, "uploaded_at": "2026-10-02T00:42:30Z", "download_url": "https://sandbox-api.matias-score.ai/v1/data/attachments/download/eyJrIjoi…" } ] } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Invalid or missing API key" } } } } }, "404": { "description": "Record not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Record not found" } } } } } }, "parameters": [ { "name": "record_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identificador del registro" } ] } }, "/v1/data/ingest/{record_id}/attachments/{field}": { "put": { "summary": "Subir o reemplazar un documento", "description": "Cuerpo = el archivo en binario, con `Content-Type` y `X-Filename`.", "tags": [ "Solicitudes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "attachment_id": "bee943fb00d0a0c3f6b6d5cf2b0a6032", "field_name": "cedula_foto", "filename": "cedula.jpg", "content_type": "image/jpeg", "size_bytes": 182340, "uploaded_at": "2026-10-02T00:42:30Z", "download_url": "https://sandbox-api.matias-score.ai/v1/data/attachments/download/eyJrIjoi…" } } } }, "400": { "description": "Attachment content type not allowed: …", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Attachment content type not allowed: …" } } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Invalid or missing API key" } } } } }, "404": { "description": "Record not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Record not found" } } } } } }, "requestBody": { "required": true, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "parameters": [ { "name": "record_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identificador del registro" }, { "name": "field", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Campo `file` del diccionario" } ] } }, "/v1/data/ingest/{record_id}/attachments/{attachment_id}": { "delete": { "summary": "Borrar un documento", "description": "Borra el archivo y su referencia en el registro.", "tags": [ "Solicitudes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "Attachment deleted" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Invalid or missing API key" } } } } }, "404": { "description": "Record or attachment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Record or attachment not found" } } } } } }, "parameters": [ { "name": "record_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identificador del registro" }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identificador del documento" } ] } }, "/v1/bureau/report": { "post": { "summary": "Cargar un reporte de buró", "description": "Si su sistema ya consultó DataCrédito (HDC+ JSON), envíelo y M.A.T.I.A.S. lo usa sin volver a consultar (vigencia de 72 h).", "tags": [ "Buró" ], "responses": { "201": { "description": "OK", "content": { "application/json": { "example": { "report_id": "4c0d7e9a-1b2f-4e8a-9c3d-5f6a7b8c9d0e", "applicant_id": 107, "provider": "datacredito", "score": 776, "risk_level": "low", "expires_at": "2026-10-05T00:42:30Z", "message": "Report ingested successfully" } } } }, "400": { "description": "Could not parse the bureau report: …", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Could not parse the bureau report: …" } } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Invalid or missing API key" } } } } }, "422": { "description": "provider, doc_type, doc_number and report are required", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "provider, doc_type, doc_number and report are required" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "provider": "datacredito", "doc_type": "CC", "doc_number": "900003121", "report": { "…": "HDC+ JSON de DataCrédito" } } } } } } }, "/v1/scorecard": { "post": { "summary": "Calcular el score M.A.T.I.A.S.", "description": "Score 0–1000 con el modelo de su entidad y su perfil de riesgo (PR-1 a PR-5). Nunca falla por datos faltantes: los reporta en `missing_optional_inputs`.", "tags": [ "Score" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "result_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "config_version": 3, "score": 817, "risk_profile": "PR-1", "strategy": "Bajo Riesgo", "bureau_data_available": true, "bureau_report_id": "4c0d7e9a-1b2f-4e8a-9c3d-5f6a7b8c9d0e", "ingested_record_id": "132ec2c1c2387b0f24a2723f073d1f09", "missing_optional_inputs": {} } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Invalid or missing API key" } } } } }, "409": { "description": "No scorecard is published for this tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "No scorecard is published for this tenant" } } } } }, "422": { "description": "doc_type and doc_number are required", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "doc_type and doc_number are required" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "doc_type": "CC", "doc_number": "900003121", "data": { "ingresos_mensuales_cop": 4200000 } } } } } } }, "/v1/decision": { "post": { "summary": "Pedir la decisión de crédito", "description": "Ejecuta la política de crédito de su entidad (configurada en Matías Flows) sobre el último registro del solicitante: identidad, buró, score, capacidad de pago, listas, condiciones por perfil y aprobaciones humanas. Configure un tiempo de espera de 30 s.", "tags": [ "Decisión" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "decision": "approved", "suggested_rate": "1.29% MV", "suggested_amount": "25000000", "suggested_term": "48", "suggested_guarantees": {}, "suggested_docs": {}, "reasons": { "risk_profile": "PR-1", "strategy": "Bajo Riesgo", "score": 817, "bureau_score": 817, "policy_reason": "risk_profile_PR-1" }, "analysis_id": "d622eb31-8ba9-430e-9ffd-abace28c54b6", "bureau_info": { "status": "ok", "error_code": null, "provider": "datacredito", "provider_type": "hdc-acierta", "timestamp": "2026-10-02T00:42:30", "mock": true, "risk_level": "low", "currency": "COP", "credit_details": { "total_balance": 6131000, "total_balance_in_mora": 0, "balance_90d_late": null, "max_mora_days": 0, "quotas_in_mora": 0, "active_credits": 1, "closed_credits": 2, "negative_credits": 0, "has_negative_history_12m": false, "inquiries_last_6m": 0, "oldest_account_date": "2013-03-02" } }, "scorecard": { "score": 817, "risk_profile": "PR-1", "strategy": "Bajo Riesgo", "bureau_data_available": true } } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Invalid or missing API key" } } } } }, "409": { "description": "No decision flow is linked to this API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "No decision flow is linked to this API key" } } } } }, "422": { "description": "id_number is required", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "id_number is required" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Rate limit exceeded" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id_number" ], "properties": { "applicant_name": { "type": "string" }, "id_type": { "type": "string", "description": "CC (por omisión), CE, PAS, PPT o su código numérico" }, "id_number": { "type": "string" }, "first_lastname": { "type": "string" }, "loan_amount": { "type": "number" }, "loan_term": { "type": "integer" } } }, "example": { "applicant_name": "MARTA LUCIA FICTICIA SINTETICA", "id_type": "CC", "id_number": "900003121", "first_lastname": "FICTICIA", "loan_amount": 25000000, "loan_term": 48 } } } }, "x-examples": { "approved": { "decision": "approved", "suggested_rate": "1.29% MV", "suggested_amount": "25000000", "suggested_term": "48", "suggested_guarantees": {}, "suggested_docs": {}, "reasons": { "risk_profile": "PR-1", "strategy": "Bajo Riesgo", "score": 817, "bureau_score": 817, "policy_reason": "risk_profile_PR-1" }, "analysis_id": "d622eb31-8ba9-430e-9ffd-abace28c54b6", "bureau_info": { "status": "ok", "error_code": null, "provider": "datacredito", "provider_type": "hdc-acierta", "timestamp": "2026-10-02T00:42:30", "mock": true, "risk_level": "low", "currency": "COP", "credit_details": { "total_balance": 6131000, "total_balance_in_mora": 0, "balance_90d_late": null, "max_mora_days": 0, "quotas_in_mora": 0, "active_credits": 1, "closed_credits": 2, "negative_credits": 0, "has_negative_history_12m": false, "inquiries_last_6m": 0, "oldest_account_date": "2013-03-02" } }, "scorecard": { "score": 817, "risk_profile": "PR-1", "strategy": "Bajo Riesgo", "bureau_data_available": true } }, "review": { "decision": "review", "suggested_rate": null, "suggested_amount": "25000000", "suggested_term": "48", "suggested_guarantees": {}, "suggested_docs": {}, "reasons": { "policy_reason": "pending_external_validation", "pending_source": "decrim", "bureau_score": null }, "analysis_id": "895f2151-89f8-4dfc-b074-f5e417299219", "bureau_info": { "status": "not_configured", "error_code": null, "provider": null, "provider_type": null, "timestamp": null, "mock": false, "risk_level": null, "currency": "COP", "credit_details": null }, "scorecard": null }, "denied": { "decision": "denied", "suggested_rate": null, "suggested_amount": null, "suggested_term": null, "suggested_guarantees": {}, "suggested_docs": {}, "reasons": { "risk_profile": "PR-5", "strategy": "Rechazo", "score": 431, "bureau_score": 431, "policy_reason": "risk_profile_PR-5" }, "analysis_id": "3b7c9e21-4f0a-4c1d-9a55-0d6e8f1b2a77", "bureau_info": { "status": "ok", "error_code": null, "provider": "datacredito", "provider_type": "hdc-acierta", "timestamp": "2026-10-02T00:42:30", "mock": true, "risk_level": "low", "currency": "COP", "credit_details": { "total_balance": 6131000, "total_balance_in_mora": 0, "balance_90d_late": null, "max_mora_days": 0, "quotas_in_mora": 0, "active_credits": 1, "closed_credits": 2, "negative_credits": 0, "has_negative_history_12m": false, "inquiries_last_6m": 0, "oldest_account_date": "2013-03-02" } }, "scorecard": { "score": 431, "risk_profile": "PR-5", "strategy": "Rechazo", "bureau_data_available": true } } } } }, "/v1/decision/{analysis_id}": { "get": { "summary": "Consultar una decisión", "description": "La decisión registrada. Si quedó en `review` pendiente, aquí aparece la final cuando se cierra.", "tags": [ "Decisión" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "decision": "approved", "suggested_rate": "1.29% MV", "suggested_amount": "25000000", "suggested_term": "48", "suggested_guarantees": {}, "suggested_docs": {}, "reasons": { "risk_profile": "PR-1", "strategy": "Bajo Riesgo", "score": 817, "bureau_score": 817, "policy_reason": "risk_profile_PR-1" }, "analysis_id": "d622eb31-8ba9-430e-9ffd-abace28c54b6", "bureau_info": { "status": "ok", "error_code": null, "provider": "datacredito", "provider_type": "hdc-acierta", "timestamp": "2026-10-02T00:42:30", "mock": true, "risk_level": "low", "currency": "COP", "credit_details": { "total_balance": 6131000, "total_balance_in_mora": 0, "balance_90d_late": null, "max_mora_days": 0, "quotas_in_mora": 0, "active_credits": 1, "closed_credits": 2, "negative_credits": 0, "has_negative_history_12m": false, "inquiries_last_6m": 0, "oldest_account_date": "2013-03-02" } }, "scorecard": { "score": 817, "risk_profile": "PR-1", "strategy": "Bajo Riesgo", "bureau_data_available": true } } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Invalid or missing API key" } } } } }, "404": { "description": "Analysis not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Analysis not found" } } } } } }, "parameters": [ { "name": "analysis_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "El `analysis_id` de la decisión" } ] } }, "/v1/applicant": { "get": { "summary": "Listar solicitantes", "description": "Paginado, de la actividad más reciente a la más antigua.", "tags": [ "Solicitantes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "total": 1, "page": 1, "page_size": 50, "applicants": [ { "applicant_id": 107, "doc_type": "CC", "doc_number": "900003121", "full_name": "MARTA LUCIA FICTICIA SINTETICA", "city": null, "department": null, "record_count": 2, "last_ingested_at": "2026-10-02T00:42:30Z" } ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Invalid or missing API key" } } } } }, "422": { "description": "date_from and date_to must be ISO dates or datetimes", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "date_from and date_to must be ISO dates or datetimes" } } } } } }, "parameters": [ { "name": "doc_type", "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "page_size", "in": "query", "schema": { "type": "integer" } } ] } }, "/v1/applicant/{doc_type}/{doc_number}": { "get": { "summary": "Ver un solicitante", "description": "Registros, reportes de buró y scores del solicitante en este ambiente.", "tags": [ "Solicitantes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "applicant": { "id": 107, "doc_type": "CC", "doc_number": "900003121", "full_name": "MARTA LUCIA FICTICIA SINTETICA" }, "ingested_records": [ "…" ], "bureau_reports": [ "…" ], "score_results": [ "…" ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Invalid or missing API key" } } } } }, "404": { "description": "Applicant not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "example": { "detail": "Applicant not found" } } } } } }, "parameters": [ { "name": "doc_type", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tipo de documento" }, { "name": "doc_number", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Número de documento" } ] } } }, "webhooks": { "decision.updated": { "post": { "summary": "Resultado final de una decisión", "tags": [ "Webhooks" ], "description": "Cuando una decisión que quedó en `review` se cierra, M.A.T.I.A.S. envía a su URL el cuerpo de `GET /v1/decision/{analysis_id}`, con los encabezados `X-Matias-Event: decision.updated` y `X-Matias-Delivery` (id único del envío, úselo para no procesar dos veces) y la autenticación que usted defina (API key, bearer o basic). Responda 2xx. Ante 408, 425, 429, 5xx o falla de red se reintenta a los 10 s, 30 s, 1, 2 y 5 min.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "decision", "analysis_id" ], "properties": { "decision": { "type": "string", "enum": [ "approved", "review", "denied" ] }, "suggested_rate": { "type": [ "string", "null" ], "description": "Tasa sugerida, p. ej. «1.29% MV» o «18.5% EA». Solo si `approved`." }, "suggested_amount": { "type": [ "string", "null" ], "description": "Monto sugerido en COP." }, "suggested_term": { "type": [ "string", "null" ], "description": "Plazo sugerido en meses." }, "suggested_guarantees": { "type": "object", "description": "Garantías requeridas por el perfil de riesgo." }, "suggested_docs": { "type": "object", "description": "Documentos requeridos por el perfil de riesgo." }, "reasons": { "type": "object", "description": "Motivo de la decisión: `policy_reason` (`policy`, `risk_profile_PR-1`…`risk_profile_PR-5`, el código de rechazo de su política, `pending_human_approval`, `pending_external_validation`, `bureau_data_unavailable`, `no_decision_node`, `flow_error`), `risk_profile`, `strategy`, `score`, `bureau_score`, `approval_reference` (aprobación humana) y `pending_source` (validación externa).", "additionalProperties": true }, "analysis_id": { "type": "string", "format": "uuid", "description": "Identificador de la decisión. Guárdelo: con él se consulta el resultado final." }, "bureau_info": { "type": "object", "description": "Resumen del buró: estado (`ok`, `no_data`, `error`, `not_configured`), proveedor, nivel de riesgo y 11 indicadores en `credit_details`.", "additionalProperties": true }, "scorecard": { "type": [ "object", "null" ], "description": "Score M.A.T.I.A.S. (0–1000), perfil PR-1…PR-5 y estrategia.", "additionalProperties": true } } }, "example": { "decision": "approved", "suggested_rate": "1.29% MV", "suggested_amount": "25000000", "suggested_term": "48", "suggested_guarantees": {}, "suggested_docs": {}, "reasons": { "risk_profile": "PR-1", "strategy": "Bajo Riesgo", "score": 817, "bureau_score": 817, "policy_reason": "risk_profile_PR-1" }, "analysis_id": "d622eb31-8ba9-430e-9ffd-abace28c54b6", "bureau_info": { "status": "ok", "error_code": null, "provider": "datacredito", "provider_type": "hdc-acierta", "timestamp": "2026-10-02T00:42:30", "mock": true, "risk_level": "low", "currency": "COP", "credit_details": { "total_balance": 6131000, "total_balance_in_mora": 0, "balance_90d_late": null, "max_mora_days": 0, "quotas_in_mora": 0, "active_credits": 1, "closed_credits": 2, "negative_credits": 0, "has_negative_history_12m": false, "inquiries_last_6m": 0, "oldest_account_date": "2013-03-02" } }, "scorecard": { "score": 817, "risk_profile": "PR-1", "strategy": "Bajo Riesgo", "bureau_data_available": true } } } } }, "responses": { "200": { "description": "Recibido" } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "`mts_sbx_…` (sandbox) o `mts_prod_…` (producción). Se entrega por canal seguro y se muestra una sola vez." } }, "schemas": { "Decision": { "type": "object", "required": [ "decision", "analysis_id" ], "properties": { "decision": { "type": "string", "enum": [ "approved", "review", "denied" ] }, "suggested_rate": { "type": [ "string", "null" ], "description": "Tasa sugerida, p. ej. «1.29% MV» o «18.5% EA». Solo si `approved`." }, "suggested_amount": { "type": [ "string", "null" ], "description": "Monto sugerido en COP." }, "suggested_term": { "type": [ "string", "null" ], "description": "Plazo sugerido en meses." }, "suggested_guarantees": { "type": "object", "description": "Garantías requeridas por el perfil de riesgo." }, "suggested_docs": { "type": "object", "description": "Documentos requeridos por el perfil de riesgo." }, "reasons": { "type": "object", "description": "Motivo de la decisión: `policy_reason` (`policy`, `risk_profile_PR-1`…`risk_profile_PR-5`, el código de rechazo de su política, `pending_human_approval`, `pending_external_validation`, `bureau_data_unavailable`, `no_decision_node`, `flow_error`), `risk_profile`, `strategy`, `score`, `bureau_score`, `approval_reference` (aprobación humana) y `pending_source` (validación externa).", "additionalProperties": true }, "analysis_id": { "type": "string", "format": "uuid", "description": "Identificador de la decisión. Guárdelo: con él se consulta el resultado final." }, "bureau_info": { "type": "object", "description": "Resumen del buró: estado (`ok`, `no_data`, `error`, `not_configured`), proveedor, nivel de riesgo y 11 indicadores en `credit_details`.", "additionalProperties": true }, "scorecard": { "type": [ "object", "null" ], "description": "Score M.A.T.I.A.S. (0–1000), perfil PR-1…PR-5 y estrategia.", "additionalProperties": true } } } } } }