API externa del core

Estado: Producción

Disponible en las instalaciones del core FINORA para los canales del banco y sus aliados. Para sistemas de terceros, usa preferentemente el Core Gateway, que expone esta misma lógica con una superficie /v1 estable y multiinquilino.

La API externa del core FINORA atiende a los canales del banco (banca por internet y móvil, oficinas, aliados) y a integradores de ERP y contabilidad. Cada instalación la publica en la URL que defina el banco; en esta documentación usamos https://api.banco.example como ejemplo.

Qué puedes hacer

Dominio	Rutas	Guía
Clientes	/api/v1/ext/customers	Cuentas de captación (alta del titular)
Cuentas	/api/v1/ext/account-products, /api/v1/ext/accounts/**	Cuentas de captación
Créditos	/api/v1/ext/credit-products, /api/v1/ext/credits/**	Ciclo de vida de un crédito
Pagos	/api/v1/payments/{transfer,deposit,withdrawal}	Transferencias, depósitos y retiros
Eventos y webhooks	/api/v1/ext/events, /api/v1/ext/event-subscriptions/**, /api/v1/ext/webhooks/**	Eventos y webhooks
Interbancario	/api/v1/interbank/{credits,debits,regularizations}, /api/v1/interbank/instructions/{ref}	Referencia
Cheques	/api/v1/checks/{validate,pay} y chequeras bajo /api/v1/ext/accounts/{id}/checkbooks	Referencia
Divisas	/api/v1/ext/fx/{quote,execute}, /api/v1/ext/fx/{id}/settle	Referencia
Contabilidad	/api/v1/ext/gl/** (cuentas, canales, asientos, balance de comprobación, reportes, revaluación)	Referencia

Convenciones

• Autenticación: clave API en X-Api-Key con alcances por permiso, u OAuth 2.0 client credentials. Ver Autenticación y permisos.
• Idempotencia: toda escritura exige la cabecera Idempotency-Key. Repetir la misma clave con la misma petición devuelve el resultado original (200) sin volver a ejecutar; con otra petición responde 409.
• Errores: application/problem+json (RFC 7807). El campo type es el contrato estable.
• Montos: números decimales en la moneda de la cuenta (código ISO 4217).
• Fechas: ISO 8601 con desplazamiento horario; los filtros por día usan la fecha local de la instalación.

Limitaciones conocidas

precaución

• Usa siempre GET /api/v1/ext/accounts/{accountId}/balance para el saldo. La ruta antigua GET /api/v1/accounts/{id}/balance no descuenta los egresos y no debe usarse para decidir.
• Las operaciones de /api/v1/payments/* sobre una cuenta bloqueada o cerrada responden hoy 404 en lugar de un error de estado. Trata ese 404 como «la cuenta no admite el movimiento» y consulta la cuenta antes de reintentar.
• Un pago mayor que la cuota adelanta las cuotas siguientes en orden; no reduce el plazo ni recalcula el plan.

Próximamente

• El catálogo publicable de tipos de evento (especificación AsyncAPI).
• La referencia interactiva de esta API: la especificación se genera con el servicio en ejecución y se publicará en cuanto se exporte con el filtro de rutas para terceros.
• Credenciales de prueba de autoservicio: hoy las entrega el banco durante la incorporación.

Referencia

Consulta la referencia de la API.