Construida para equipos técnicos que no quieren sorpresas.
Un modelo de API para todo movimiento de dinero, eventos firmados para cada cambio de estado y ambientes separados. Lo que sigue es cómo funciona, sin adornos.
APIs
REST sobre HTTPS con JSON. Recursos claros: dispersiones, órdenes, transferencias, recaudos, cuentas y movimientos. Los mismos verbos, los mismos estados y los mismos identificadores en toda la plataforma.
| Protocolo | HTTPS · JSON · UTF-8. Errores con código, mensaje y detalle por campo. |
|---|---|
| Autenticación | Claves de API por ambiente con permisos por alcance (lectura, escritura, administración). |
| Idempotencia | Cabecera Idempotency-Key en toda operación que mueva dinero. Reintentar es seguro. |
| Paginación | Por cursor, con filtros por fecha, estado y tipo. |
| Versionado | Versión en la ruta (/v1). Cambios incompatibles solo en versiones nuevas, con periodo de convivencia. |
| Estados | recibida → validada → en_proceso → dispersada | rechazada. Los mismos para dispersiones y transferencias. |
| Ambientes | Pruebas y producción con las mismas rutas y credenciales independientes. |
POST /v1/dispersiones
Authorization: Bearer sk_live_••••••••
Idempotency-Key: 8f2c1a5e-nomina-2026-09
{
"referencia": "NOMINA-CONTRATISTAS-2026-09",
"moneda": "COP",
"ordenes": [
{
"beneficiario": { "tipo_documento": "CC", "documento": "1020304050", "nombre": "Laura Gómez" },
"cuenta": { "entidad": "007", "tipo": "ahorros", "numero": "4581••••••" },
"monto": 1850000,
"concepto": "Servicios septiembre"
}
// … hasta miles de órdenes por lote
]
}{
"id": "dsp_01JC9X4M2K7Q",
"estado": "recibida",
"ordenes": { "total": 1240, "validadas": 0, "rechazadas": 0 },
"monto_total": 2287450000,
"creada_en": "2026-09-30T15:02:11-05:00"
}Webhooks
Cada cambio de estado relevante se entrega a tu sistema como un evento firmado. Tu plataforma reacciona; no necesita consultar en bucle.
| Firma | Cabecera X-Dispersa-Signature con marca de tiempo y HMAC sobre el cuerpo. Verifica antes de procesar. |
|---|---|
| Entrega | Reintentos con espera creciente ante respuestas distintas de 2xx. Registro de cada intento consultable. |
| Orden | Los eventos llevan identificador único y marca de tiempo; diseña tu consumidor de forma idempotente. |
| Reenvío | Cualquier evento puede reenviarse desde el panel o por API. |
Eventos
orden.recibida | La orden entró al sistema y tiene identificador. |
|---|---|
orden.validada | Pasó validación de estructura, cuenta y cumplimiento. |
orden.rechazada | No pasó una validación; incluye la causa. |
orden.dispersada | La transferencia fue confirmada por la red financiera. |
recaudo.identificado | Entró dinero asociado a una referencia. |
transferencia.confirmada | Una transferencia saliente fue acreditada. |
conciliacion.cerrada | Un periodo quedó conciliado y disponible para reporte. |
POST https://tu-plataforma.com/webhooks/dispersa
X-Dispersa-Signature: t=1790000000,v1=5a3f…c9e1
{
"evento": "orden.dispersada",
"id": "evt_01JC9XB7R3ZP",
"orden_id": "ord_01JC9X8T6M4V",
"dispersion_id": "dsp_01JC9X4M2K7Q",
"monto": 1850000,
"estado": "dispersada",
"confirmada_en": "2026-09-30T16:42:10-05:00"
}Integraciones
Tres formas de conectarse, según el equipo y la etapa. Todas llegan al mismo motor y a la misma conciliación.
API directa
Para plataformas que inician pagos y recaudos desde su propio software, por evento o por lote. Control total y confirmación por webhook.
Lotes por archivo
Para tesorerías y ERP que ya generan archivos de pago. Carga segura, validación por orden y resultado por beneficiario.
Panel de operación
Para operar, aprobar y consultar sin escribir código: estados, reportes, reenvío de eventos y gestión de credenciales.
Ruta de integración
El orden habitual. Un especialista técnico acompaña cada etapa.
Alcance y vinculación
Definimos los módulos, los flujos y la vinculación de tu empresa como cliente, incluida la debida diligencia.
Credenciales de pruebas
Acceso al ambiente de pruebas y a la documentación para tu equipo.
Integración y certificación
Construyes contra pruebas; validamos juntos los flujos, los eventos y la conciliación.
Producción
Credenciales de producción, primer lote acompañado y monitoreo desde el día uno.
Seguridad
Principios y controles con los que está construida y operada la plataforma. Sin certificaciones que no tengamos ni cifras que no podamos sostener.
Cifrado en tránsito
TLS en todas las conexiones con tu plataforma y con las redes financieras.
Claves y alcances
Credenciales por ambiente y por integración, con permisos mínimos y rotación sin interrupción.
Eventos firmados
Cada webhook firmado con HMAC y marca de tiempo para evitar suplantación y repetición.
Control de acceso
Permisos por rol para operar, aprobar y consultar; segregación de funciones en el panel.
Auditoría
Registro inmutable de cada acción sobre instrucciones, credenciales y configuración.
Cumplimiento
Controles de prevención de lavado de activos y financiación del terrorismo por instrucción, antes de ejecutar.
Escalabilidad
La misma integración soporta el primer lote y el crecimiento posterior. La arquitectura procesa por lotes y por evento, con colas que absorben picos y validación por orden para que un error no detenga el resto.
- Validación por orden, no por lote. Un rechazo se aísla; las demás órdenes siguen.
- Procesamiento asíncrono. La API responde de inmediato; la ejecución y la confirmación llegan por evento.
- Consultas eficientes. Paginación por cursor y filtros para reconciliar grandes volúmenes sin descargar todo.
- Crecimiento acompañado. Límites y ventanas operativas se ajustan con tu operación, con el equipo de Dispersa Tech.
GET /v1/movimientos?desde=2026-09-01&hasta=2026-09-30&estado=conciliado
{
"datos": [
{ "id": "mov_01JC…", "tipo": "recaudo", "referencia": "DT-77291-04", "monto": 350000, "conciliado": true },
{ "id": "mov_01JC…", "tipo": "dispersion", "referencia": "ord_01JC9X8T6M4V", "monto": -1850000, "conciliado": true }
],
"siguiente": "cursor_8sd7f…"
}Documentación
La referencia de la API, las guías de integración y las colecciones de pruebas están disponibles para los equipos en proceso de integración.
Qué incluye
- Referencia completa de endpoints, campos y códigos de error.
- Guías por flujo: dispersión, recaudo, transferencias, conciliación.
- Verificación de firmas de webhooks con ejemplos en varios lenguajes.
- Colección para pruebas y datos de ejemplo del ambiente de pruebas.
- Lista de cambios por versión.
¿Tu equipo quiere ver la API de cerca?
Solicita acceso a la documentación o agenda una sesión técnica con nuestro equipo.