FINORA Core · Ruta por rol

Integrador del core

Implementado

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.

El gateway de API del core15 min
La puerta pública: qué revisa en cada petición y por qué.
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.
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.
API contable del coreConsulta
Rutas, campos, criterios de búsqueda, reportes asíncronos y errores.
Códigos de error del gateway de APIConsulta
Cada código, su estado y qué reintentar.
Webhooks firmados del core12 min
El aviso, la firma HMAC, los reintentos y el circuit breaker.
Recibir y verificar los webhooks del core20 min
Alta, verificación en Java o Node, entregas y reenvío.
Consumir el streaming de eventos del core20 min
Lectura por cursor y suscripciones con cursor confirmado.
Configuración contable como código15 min
Exportar, ensayar con dryRun y aplicar sin borrados accidentales.
Rotar una credencial de API con periodo de gracia10 min
El secreto ante el gateway y la API key ante el core.
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.

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.