Descripción general
Todos los endpoints del dominio de préstamos comparten el contrato descrito en esta página. Léala primero; las páginas de cada superficie hacen referencia a ella en lugar de repetirla.
URL base y control de versiones
Todas las rutas del dominio de préstamos se montan bajo /api/v1/monitoring/loan/. El entero que sigue a v es la versión mayor: un cambio de versión mayor es un cambio incompatible y solo se produce con un aviso explícito de obsolescencia. La evolución menor dentro de una versión mayor es solo aditiva — nuevos campos opcionales, nuevos endpoints, nuevos valores de enumeración — y nunca rompe una integración que ignore los campos que no entiende.
El host de producción es https://app.waafir.io. Para obtener una URL completa, anteponga el host a cualquier ruta de este sitio de referencia, por ejemplo https://app.waafir.io/api/v1/monitoring/loan/borrowers.
Autenticación
Cada solicitud lleva un encabezado Authorization con un token Bearer:
Authorization: Bearer <PAT><PAT> es un token de acceso personal emitido desde el plano de control de Waafir para una única organización. La organización del token determina el ámbito de inquilino de cada lectura y cada escritura — no existe ningún parámetro de organización en ninguna URL ni cuerpo, porque el token ya la fija.
Las solicitudes entre organizaciones devuelven 404 Not Found, no 403 Forbidden. Devolver 403 revelaría la existencia del recurso de otro inquilino por su id; la postura de 404 trata por igual los id desconocidos y los id de otro inquilino.
Una solicitud sin encabezado Authorization, con un token desconocido o con un token revocado devuelve 401 Unauthorized.
Garantías de integración
Cada ruta de modificación respeta las garantías siguientes. Cada una es algo en lo que el código de su cliente puede confiar; leerlas una vez aquí le permite implementar una integración robusta de una sola pasada.
ID proporcionados por el llamante
Cada entidad tiene un campo id en el cuerpo de su solicitud que usted proporciona como UUID. La plataforma nunca inventa ID por usted. Esta es la base de todos los demás contratos de esta lista: la idempotencia, la conciliación y la reproducción dependen de que usted pueda direccionar una fila mediante un identificador que eligió.
Si vuelve a enviar por POST una fila con el mismo id, recibe 409 ID_CONFLICT y una entrada de fieldErrors que apunta a id. Elija sus ID con cuidado — se recomiendan UUIDv4 generados, pero cualquier UUID bien formado funciona.
Además de id, cada entidad lleva también un externalId — una cadena de formato libre de hasta 255 caracteres que usted utiliza para direccionar la fila desde su propio sistema. Un externalId es único dentro de una cartera entre las filas activas, y eso es lo que hace posible la conciliación por ID de llamante.
Encabezado Idempotency-Key
Cada ruta de modificación lee un encabezado HTTP opcional Idempotency-Key. Cuando está presente, la plataforma deduplica frente a un archivo interno: una segunda solicitud con la misma clave devuelve la misma respuesta que la primera, aunque el cuerpo difiera ligeramente. Así es como los clientes sobreviven a cortes de red que los dejan sin saber si una solicitud llegó.
El encabezado no distingue mayúsculas de minúsculas en la transmisión (Idempotency-Key, idempotency-key, IDEMPOTENCY-KEY funcionan todos). El valor se trata como opaco — elija cualquier valor estable por operación lógica, normalmente un UUIDv4 más un discriminador de ruta.
?dryRun=true
Cada ruta de modificación acepta un parámetro de consulta ?dryRun=true. Una solicitud de prueba ejecuta la validación y las comprobaciones de inquilino y devuelve la entrada validada, pero no registra nada ni almacena ninguna fila. Úselo para confirmar que un cuerpo se analiza correctamente antes de realizar una escritura real.
La forma de la respuesta en una ejecución de prueba correcta es { "dryRun": true, "validatedInput": <body> } con un 200 OK. Los fallos de validación durante una ejecución de prueba devuelven la misma forma 400 que una escritura real; solo difieren los efectos secundarios.
Sobre de validación fieldErrors
Los fallos de validación devuelven 400 Bad Request con un sobre estructurado:
{
"error": "Validation failed",
"fieldErrors": [
{ "path": "interestRateApr", "message": "interestRateApr must be >= 0" },
{ "path": "termMonths", "message": "termMonths must be > 0" }
]
}path es la ruta con puntos del campo problemático; message es una explicación legible por humanos. El sobre es uniforme en todas las rutas, de modo que un único manejador en el cliente puede presentar todos los fallos de validación de forma coherente.
Enumeraciones sin distinción de mayúsculas con sugerencias «did you mean»
Las enumeraciones del dominio (estado del préstamo, método de pago, frecuencia de reembolso, código de moneda, etc.) aceptan cualquier combinación de mayúsculas y minúsculas en la transmisión. La plataforma normaliza a la forma canónica en minúsculas antes de persistir.
Un valor no reconocido devuelve 400 con una entrada de fieldErrors que nombra el valor problemático y sugiere el valor aceptado más cercano:
{
"error": "Validation failed",
"fieldErrors": [
{
"path": "status",
"message": "got 'restruktured', did you mean 'restructured'?"
}
]
}La sugerencia se calcula con una pequeña métrica de distancia de edición, por lo que las transposiciones y los errores tipográficos de un carácter se detectan de forma fiable.
Transferencia directa de metadata JSONB
Cada entidad acepta un campo opcional metadata de tipo objeto. La plataforma persiste el objeto tal cual — no se eliminan claves ni se convierten valores. Úselo para adjuntar contexto del lado del cliente que la propia plataforma no necesita entender: su ID interno, el sistema de origen, una marca de tiempo de extracción, un código de campaña.
Dos superficies no admiten metadata: la transición de estado del préstamo y las rutas de cancelación de pagos. El motivo se documenta en esas mismas rutas.
Conciliación por ID de llamante
Cada entidad es direccionable por el externalId que usted envió, dentro del ámbito de una cartera. La superficie de conciliación — GET /loans/{externalId} y GET /counts — lo utiliza para que pueda verificar las escrituras sin necesitar nunca el UUID asignado por la plataforma. Consulte la página de conciliación para ver las formas exactas.
Representación de importes
Los valores monetarios se transmiten como cadenas de dígitos decimales, con hasta cuatro dígitos fraccionarios. El number de JavaScript se rechaza porque los números binarios de coma flotante IEEE-754 no pueden representar los céntimos decimales con exactitud:
{ "amount": "100.50", "currencyCode": "USD" }Un decimal con más de cuatro dígitos fraccionarios, o un valor que contenga caracteres distintos de dígitos, un signo menos inicial y un único punto, devuelve 400 con una entrada de fieldErrors. Las cadenas vacías se rechazan.
Los códigos de moneda son códigos ISO-4217 de tres letras. La plataforma reconoce explícitamente el conjunto habitual; los códigos desconocidos que respetan la forma de tres letras mayúsculas se aceptan y se persisten tal cual, de modo que no se bloquean los códigos de mercados exóticos.
Formato de fecha
Las fechas se transmiten como cadenas de fecha de calendario ISO-8601 con la forma YYYY-MM-DD:
{ "disbursementDate": "2026-01-15" }No hay componente de zona horaria. Las fechas son fechas de calendario según la interpretación de la cartera; la plataforma no las convierte.
Semántica de cancelación
Las llamadas a la API nunca borran una fila. Una cancelación u otra reversión marca la fila como cancelada. Las implicaciones:
- Una cancelación no libera el
externalId. UnexternalIdes único dentro de una cartera solo entre las filas activas. Una fila cancelada ya no está activa, por lo que puede reutilizar suexternalIdpara un reenvío corregido. - Las lecturas de conciliación no devuelven filas canceladas por defecto. Las superficies
GET /loans/{externalId}yGET /countsexcluyen de su respuesta predeterminada las filas con borrado lógico. - Los registros de envío se conservan en cualquier caso. Incluso cuando una fila se cancela, el registro del envío que la creó permanece intacto para la auditoría.
Cada envío queda registrado
Cada modificación correcta registra el cuerpo bruto de la solicitud antes de escribir la fila. Las implicaciones para su integración:
- Un
200/201significa que su envío ha quedado registrado de forma duradera, aunque un procesamiento posterior lo marque después. Su pista de auditoría comienza en el momento en que la plataforma acusa recibo de la solicitud. - Un
409 ID_CONFLICTtambién se archiva. El registro de envío contiene tanto el conflicto como el envío intentado, de modo que puede investigar más tarde sin ambigüedad sobre lo que se envió. - Las importaciones asíncronas se registran en el momento de la confirmación. El archivo NDJSON cargado y la propia importación constituyen el registro; no hay un registro separado por fila para una importación asíncrona.
El registro de envío no puede modificarse. Nunca lo lee directamente a través de la API pública, pero es la razón por la que la superficie de conciliación es fidedigna — cada fila visible allí tiene una entrada de archivo correspondiente detrás.
Cómo se organiza el resto de esta referencia
Cada página siguiente de este sitio de referencia documenta una modalidad de ingesta o la superficie de conciliación. Cada página de ruta sigue la misma estructura: un propósito en una frase, la forma de la solicitud (encabezados, consulta, cuerpo), la forma de la respuesta por código de estado y una invocación mínima de cURL. Las restricciones campo por campo se recogen en tablas fáciles de recorrer; los ejemplos detallados y los fragmentos de código en tres lenguajes están en el Recetario.
La página de errores y códigos de estado es la referencia consolidada de los sobres de respuesta que utiliza cada ruta de este sitio. Léala una vez antes de integrar; vuelva a ella cada vez que un estado distinto de 200 le sorprenda.