Integrador del core

Audiencia: Tecnología e integración. Puede ser el equipo de sistemas del banco o el de un aliado (un ERP, una fintech, un conciliador).

Quién eres

Conectas otros sistemas con el core sin entrar a su consola: lees el plan de cuentas y los asientos, contabilizas desde afuera, te enteras de cada evento y mantienes la parametría contable bajo control de versiones. Trabajas con credenciales de mínimo privilegio y nunca pruebas contra producción.

Lo que vas a lograr

• Pedir un token y llamar a la API con la cabecera correcta en cada caso.
• Contabilizar desde un sistema externo sin duplicar un asiento aunque se caiga la red.
• Recibir los avisos del core y descartar los falsos y los repetidos.
• Consumir los eventos en orden y retomar donde quedaste.
• Cambiar una credencial sin cortar el servicio.

Conceptos previos

• El gateway de API del core: credenciales, alcances, instituciones, sandbox, idempotencia, paginación y errores.
• Webhooks firmados del core: el aviso, la firma, los reintentos y el circuit breaker.
• Partida doble garantizada por la base de datos: por qué el core rechaza un asiento descuadrado aunque tu sistema lo mande.

Lo que haces con FINORA Core

• Conectas la taquilla, el ERP y los canales con el core como único sistema de registro.
• Consultas el plan de cuentas, sus saldos y el balance de comprobación.
• Contabilizas asientos manuales con clave de idempotencia y los corriges por reverso.
• Escuchas los eventos del core por webhook o por streaming.
• Versionas la configuración contable como código.
• Rotas tus credenciales antes de que alguien tenga que pedírtelo.

Tu ruta

En este orden.

1. 1

   El gateway de API del core15 min

   La puerta pública: qué revisa en cada petición y por qué.

2. 2

   Integrar los sistemas satélite del banco con FINORA Core35 min

   Taquilla, ERP y canales con el core como sistema de registro: cuentas, pagos, cheques, créditos, apply-concept, el mayor, avisos y licencias.

3. 3

   Tu primera llamada a la API del core25 min

   Token, plan de cuentas, un asiento de tres piernas, búsqueda y reverso en el sandbox.

4. 4

   API contable del coreConsulta

   Rutas, campos, criterios de búsqueda, reportes asíncronos y errores.

5. 5

   Códigos de error del gateway de APIConsulta

   Cada código, su estado y qué reintentar.

6. 6

   Webhooks firmados del core12 min

   El aviso, la firma HMAC, los reintentos y el circuit breaker.

7. 7

   Recibir y verificar los webhooks del core20 min

   Alta, verificación en Java o Node, entregas y reenvío.

8. 8

   Consumir el streaming de eventos del core20 min

   Lectura por cursor y suscripciones con cursor confirmado.

9. 9

   Configuración contable como código15 min

   Exportar, ensayar con dryRun y aplicar sin borrados accidentales.

10. 10

    Rotar una credencial de API con periodo de gracia10 min

    El secreto ante el gateway y la API key ante el core.

11. 11

    Webhooks de seguridad del gateway—Hoja de ruta

    Avisos de credencial bloqueada, dirección bloqueada o secreto anterior en uso, hacia el SIEM del banco.

Note

Los webhooks de seguridad del propio gateway están diseñados pero no implementados: por ahora esos hechos quedan en el log del gateway y en sus métricas.

Tu lista de cada día, semana y mes

Cada día

• Revisa las entregas de webhook en DEAD y reenvía las que correspondan.
• Revisa que tu consumidor de eventos confirmó cursor en las últimas horas.

Cada semana

• Busca en tus logs respuestas con X-Finora-Secret-Expires: alguien sigue usando un secreto por vencer.
• Revisa los 429 LIMITE_EXCEDIDO y ajusta tu ritmo antes de pedir más límite.

Cada mes

• Exporta la configuración contable y compárala con tu repositorio: no debería haber diferencias.
• Revisa los alcances de tus credenciales y quita los que ya no usas.

Lo que se mide de tu trabajo

Indicador	Qué dice	Buena señal
Asientos duplicados por reintentos	Si usas bien la Idempotency-Key	Ninguno
Entregas de webhook en DEAD	Si tu receptor responde y verifica bien	Casi ninguna, y reenviadas el mismo día
Retraso del consumidor de eventos	Distancia entre el último evento y tu cursor confirmado	Minutos, no horas
Credenciales sin rotar	Secretos con más tiempo del que fija la política del banco	Ninguna

Errores frecuentes

Lo que pasa	Por qué	Qué hacer
Un asiento aparece dos veces	Reintentaste con una Idempotency-Key nueva	Genera la clave una vez por operación y reúsala en los reintentos
422 IDEMPOTENCIA_CUERPO_DISTINTO	Reusaste la clave para otra operación	Una operación nueva lleva una clave nueva
La firma del webhook falla con avisos reales	Verificas el JSON ya interpretado, no el cuerpo crudo	Lee los bytes originales en esa ruta
Procesas dos veces el mismo evento	Tu consumidor cayó antes de confirmar el cursor	Deduplica por eid o por X-Finora-Webhook-Id
403 TENANT_CRUZADO o ENTORNO_CRUZADO	Credencial de una institución o entorno contra otro	Usa la credencial del sandbox en el sandbox
El asiento de hoy no sale en el balance de comprobación	El balance solo cuenta lo ya contabilizado por el cierre	Consulta el saldo de la cuenta o espera el cierre

Tu rol en el sistema

No tienes usuario en la consola del core: tienes una credencial de API con alcances (gl:read, gl:write, webhooks:read, events:read, config:read…) atada a una institución y a un entorno. La da quien opera el gateway, y detrás de ella el administrador del core decide qué puede hacer la credencial del gateway ante el core. Las pantallas de Administración → Webhooks, Entregas de webhook y Suscripciones de eventos las usa el administrador del core.