Inicio Ejecutivo

Visión del módulo seguro de cobranza para IFI

● Sistema activo
Sin sesión

Módulo seguro de cobranza para múltiples IFI

Canal API para instituciones integradas y pantalla web mínima para las que no se integren por API. Administración altamente protegida, aislamiento por IFI, idempotencia y trazabilidad completa.

Canal principal
APIs seguras por IFI
Canal alterno
Cobrador web simple
Área más protegida
Admin de accesos
IFI activas
3
▲ 2 canales API
Endpoints core
4
▲ Idempotentes
Cobros hoy (mock)
0
▲ En tiempo real
Reversos hoy
0
— Pendientes
Arquitectura funcional
Tres módulos independientes con acceso diferenciado. El estado de la deuda es global para evitar cobro duplicado entre IFI.
🔐 Admin seguro

Crea IFI, genera tokens rotables, define whitelist de IP y gestiona usuarios y permisos. Acceso exclusivo interno con auditoría.

⚡ APIs de cobranza

Canal principal. Token por IFI, validación IP opcional, idempotency key, bloqueo transaccional y auditoría por cada llamada.

💳 Cobrador web

Canal alternativo mínimo para IFI sin integración. Cédula → deuda → cobro exacto → reverso si tiene permiso.

Reglas de negocio clave
Solo cobro exacto

No se permiten pagos parciales ni por valor superior al exigible.

Estado global de deuda

Si una IFI confirma el pago, ninguna otra IFI verá la deuda como pendiente.

Idempotencia

Reintentos con la misma idempotency key no generan doble cobro.

Aislamiento por IFI

Cada IFI solo ve su propia configuración, tokens y logs.

Reverso trazable

Todo reverso se ejecuta en transacción con registro completo y rehabilita la deuda.

Notificación al cliente

Si el cliente tiene correo, recibe notificación de cobro o reverso automáticamente.

🔒Sesión admin activa · Todos los cambios quedan en auditoría
Gestión de IFI
Crea y administra las instituciones financieras, sus credenciales API y restricciones de IP.
Credenciales API
Genera, rota y revoca tokens por IFI.
Los tokens se almacenan hasheados. Una vez mostrado no puede recuperarse — guárdelo.
Whitelist de IP
Restringe el origen de llamadas por IFI.
Registro de accesos admin
HoraUsuarioAcciónIPResultado
19-04-2026 13:50admin.masteradmin.login192.168.1.10Exitoso
Consola API de Cobranza
Simula llamadas reales a los endpoints. Usa el token generado en Admin o uno de los tokens de demo precargados.
Endpoint:
Request
Response
Selecciona un endpoint y ejecuta el mock.
Logs del sistema
Referencia de endpoints
POST /api/v1/debts/query

Consulta deuda por cédula. Requiere token IFI. Responde deuda vigente o mensaje sin deuda.

POST /api/v1/payments/register

Registra cobro exacto con idempotency key. Bloquea transaccionalmente la deuda.

POST /api/v1/payments/reverse

Reversa cobro con permiso y trazabilidad. Rehabilita la deuda al estado cobrable.

GET /api/v1/payments/:externalRef

Consulta estado de transacción por referencia externa para conciliación.

🔒 Cobrador: KVQ-014 · Cooperativa Sierra Norte · IP: 181.39.24.10
→
2. Deuda
→
3. Cobro
→
4. Confirmado
Consulta por cédula
Ingrese la cédula del cliente para consultar deuda vigente.
Datos del cliente
Detalle de deuda
DocumentoConceptoVencimientoMontoEstado
Realice una consulta para ver el detalle
Registrar cobro
Consulte primero la deuda para habilitar el cobro.
Suite de Pruebas Mock
Ejecuta escenarios funcionales, de negocio, seguridad y concurrencia. Todos los tests son mocks en memoria.

Funcionales

Negocio

Seguridad & Concurrencia

Payload de ejemplo — cobro API
REQUEST — POST /api/v1/payments/register
{
  "nationalId": "0101714392",
  "debtNumber": "DB-2026-000702",
  "amount": 10.00,
  "externalReference": "BH-DEP-20260419-00018",
  "cashierCode": "API-BH-01",
  "idempotencyKey": "0fd3fc73-c776-43b4-a60b-b8bd5d2d3301"
}
RESPONSE 200 — Cobro aprobado
{
  "status": "approved",
  "paymentId": "PAY-20260419-00091",
  "debtNumber": "DB-2026-000702",
  "paidAmount": 10.00,
  "currency": "USD",
  "institutionCode": "BH001",
  "paidAt": "2026-04-19T15:28:44Z",
  "notificationSent": true
}
Auditoría y Monitoreo
Cada acceso, consulta, cobro, reverso y error queda registrado por IFI, actor, canal e IP.
Total eventos
0
Cobros
0
Rechazos
0
Errores seguridad
0
Fecha/HoraIFIActorEventoIPResultado
19-04-2026 13:50Internoadmin.masteradmin.login192.168.1.10OK
19-04-2026 14:08Coop Sierra NorteAPI-CSNapi.request190.20.100.5IP rechazada
Estructura del registro de auditoría
audit_log — estructura
{
  "id": "log-20260419-00412",
  "financialInstitutionCode": "BH001",
  "actorType": "collector_web",
  "actorId": "KVQ-014",
  "action": "payment.register",
  "endpoint": "POST /payments",
  "ip": "181.39.24.10",
  "requestPayload": { ... },
  "responsePayload": { ... },
  "httpStatus": 200,
  "createdAt": "2026-04-19T15:28:44Z"
}
Aislamiento por IFI

Cada IFI solo puede consultar sus propios logs vía admin. El superadmin ve todos.

Inmutabilidad

Los registros de auditoría no pueden modificarse. Solo lectura desde el panel.

Cobertura completa

Login, consulta, cobro, reverso, error de IP, token inválido y excepciones de negocio.