Referencia
Referencia del API
Las 115 operaciones del API Gateway v1, generadas desde el contrato OpenAPI que fijan los SDK: verbo, ruta, parámetros, cuerpo, respuestas, idempotencia y el método equivalente en Python, JavaScript/TypeScript, PHP, .NET y Go.
La referencia se genera en cada compilación a partir de data/gateway-v1.json, una copia del
contrato OpenAPI 3.1 que el gateway publica en /v1/openapi.json y que los cinco SDK fijan en sus
pruebas de paridad (gateway develop 9cf78da, 2026-10-27). No se edita a mano: se regenera con
scripts/sync_contract.py (ver el README del repositorio).
El contrato publicado tiene 102 rutas y 115 operaciones (45 escrituras con Idempotency-Key) en 13 tags, y 80 esquemas reutilizables.
| Tag | Página | Operaciones | Qué cubre |
|---|---|---|---|
affiliates | Afiliados | 3 | Cruce e ingesta de la base de afiliados de la entidad: por lotes JSON, por archivo y consulta por documento. |
credits | Créditos | 5 | Originación de crédito: radicar solicitudes en el motor de decisión (BRE), consultarlas, decidirlas y desembolsarlas. |
subsidies | Subsidios | 4 | Radicación y decisión de subsidios de ley (desempleo, vivienda…) y personalizados. |
monetary-allowance | Cuota monetaria | 3 | Generación del período de cuota monetaria, consulta y desembolso. |
wallet | Billetera | 24 | Billetera: saldo, movimientos, P2P, Bre-B, facturas, recargas, cuentas y bolsillos, tarjetas y FX. El titular se identifica con document. |
loans | Cartera | 12 | Vida del crédito desembolsado: plan de pagos, cuotas, recaudos, abonos extraordinarios, pago total y certificados. |
pqrs | PQRS | 6 | Peticiones, quejas, reclamos y sugerencias desde el CRM o el call center de la entidad. |
health | Servicios de salud | 15 | Para IPS: catálogo y agenda, citas en nombre del paciente, facturación de salud (DIAN, RIPS, glosas, recaudo) y carné de vacunación. |
admin | Administrativo | 25 | Módulo ERP: talento humano, nómina, contabilidad y tesorería. Los documentos entran como borrador (DRAFT); las aprobaciones siguen en el panel. |
webhooks | Webhooks | 11 | Autogestión de webhooks por API: catálogo de eventos, endpoints, rotación del secreto, eventos de prueba, entregas y reentregas. |
sandbox | Sandbox | 5 | Simulación determinista para llaves de sandbox: relojes de prueba y avance de ciclos de vida. Las llaves de producción reciben 403. |
transactions | Transacciones | 1 | Estado de una transacción asíncrona del gateway por su transaction_id. |
system | Sistema | 1 | Salud del gateway e introspección de la llave: tenant y scopes. |
Cómo leer cada operación #
- Verbo y ruta. Todas las rutas cuelgan de
/v1/gateway/. La URL base depende del entorno (ver Entornos y llaves); la ruta incluye siempre/v1. - Autenticación. Todas exigen la cabecera
X-API-Keycon una llavecmp_.... La llave identifica al tenant: no se envía ningún id de entidad. Detalle en Autenticación. - Idempotency-Key. Obligatoria en las escrituras que mueven dinero (P2P, Bre-B, facturas,
recargas): sin ella el gateway responde
400. Recomendada en el resto de escrituras: los SDK la generan solos. Las lecturas y losPOSTque solo consultan (resolver, cotizar, consultar una factura, calcular impuestos, simuladores) no la llevan. Ver Idempotencia. - Respuestas. Las lecturas devuelven el cuerpo del motor; las escrituras devuelven el
sobre de transacción
{status, transaction_id, module, data}. Los errores siguen RFC 9457 (application/problem+json): ver Errores. - Ejemplo. Pestañas con el método de cada SDK (derivado de su suite de paridad) y un
curllisto para el sandbox.
Esquemas #
Los 80 esquemas reutilizables (components.schemas) están en
Esquemas. Los montos usan MoneyCOP: texto decimal.