1 de octubre de 2026 · 2 min de lectura
externalId: el campo que decide si tu integración puede reintentar
Un timeout hace que el originador reenvíe la petición y aparecen dos desembolsos del mismo crédito. Fineract trae el mecanismo para evitarlo, pero solo funciona si el valor se elige bien.
La red falla una vez cada mil peticiones, y mil peticiones es una semana floja. El escenario es siempre el mismo: tu originador llama a Fineract para crear un crédito, la respuesta no llega por un timeout, el originador reintenta porque está bien programado, y el cliente termina con dos créditos idénticos. El error no se descubre ese día: se descubre cuando el saldo de cartera no cuadra con el mayor.
Fineract trae el mecanismo para evitarlo y casi nadie lo usa: el campo externalId.
Qué hace exactamente
externalId es un identificador que tú eliges y que Fineract guarda junto a la entidad. No es decorativo: la entidad Loan declara una restricción de unicidad sobre esa columna, llamada loan_externalid_UNIQUE. El segundo intento de crear un crédito con el mismo valor no crea nada — choca contra la base de datos.
Y no revienta de cualquier manera. El servicio de creación intercepta esa violación concreta y devuelve un error de negocio legible, error.msg.loan.duplicate.externalId, en lugar de un error 500 genérico. Tu integración puede distinguir “esto ya existía” de “esto falló de verdad”, que es exactamente la distinción que necesita para reintentar sin miedo.
El círculo se cierra con las rutas de consulta por ese identificador: GET /loans/external-id/{loanExternalId} y sus variantes. Ante un duplicado, el originador consulta y recupera el crédito que sí se creó, sin depender de haber recibido la respuesta original.
El detalle que lo arruina
El valor tiene que venir del sistema que origina la operación: el número de solicitud, el identificador del expediente, la referencia del core del que migras.
Si generas un identificador aleatorio en el momento de enviar la petición, cada reintento lleva uno distinto y vuelves al punto de partida — con la molestia añadida de un campo lleno de datos que no sirven para nada. El valor tiene que ser el mismo para el primer intento y para el quinto, porque lo que identifica no es la petición: es el hecho de negocio.
Dos minutos de trabajo
Revisa tus integraciones. Si alguna crea clientes, créditos, cuentas o transacciones en Fineract sin enviar externalId, no puede reintentar con seguridad, y eso significa que algún día va a duplicar algo. Hoy, mientras no falle nada, el cambio cuesta una línea.