CRUD de registro único
La superficie CRUD de registro único es la vía de bajo volumen: una llamada HTTP por fila. Úsela para escrituras operativas — un único préstamo nuevo, un único pago que no llegó en el lote diario, una transición de estado — y para lecturas por UUID de la plataforma. Para lotes de cierre de jornada use NDJSON masivo; para cargas históricas use importaciones asíncronas.
Cada ruta de esta página respeta el contrato documentado en la descripción general: autenticación con token bearer, las garantías de integración, el sobre fieldErrors, la semántica de cancelación y cómo se registra cada envío. La documentación ruta por ruta que sigue solo nombra las formas específicas de cada ruta; consulte la descripción general para el comportamiento transversal.
Rutas de un vistazo
| Método | Ruta | Propósito |
|---|---|---|
POST | /api/v1/monitoring/loan/borrowers | Crear un prestatario |
GET | /api/v1/monitoring/loan/borrowers/{id} | Leer un prestatario por UUID con enmascaramiento de PII |
POST | /api/v1/monitoring/loan/loans | Crear un préstamo |
POST | /api/v1/monitoring/loan/payments | Crear un pago efectivo |
GET | /api/v1/monitoring/loan/payments/{id} | Leer un pago efectivo por UUID |
PATCH | /api/v1/monitoring/loan/loans/{loanRef}/status | Cambiar un préstamo a un nuevo estado |
POST | /api/v1/monitoring/loan/payments/{id}/cancel | Aplicar borrado lógico a un pago |
Todas las rutas de modificación aceptan el encabezado Idempotency-Key y el parámetro de consulta ?dryRun=true, y devuelven el sobre estructurado fieldErrors cuando falla la validación.
POST /api/v1/monitoring/loan/borrowers
Crea un prestatario en la cartera identificada por portfolioId.
Solicitud
POST /api/v1/monitoring/loan/borrowers HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json
Idempotency-Key: <opaque-key>Cuerpo:
| Campo | Tipo | Obligatorio | Restricción |
|---|---|---|---|
id | cadena UUID | sí | Identificador de plataforma proporcionado por el llamante. |
portfolioId | cadena UUID | sí | La cartera propietaria; debe existir en su organización. |
externalId | cadena | sí | 1-255 caracteres; único por (portfolio, externalId) entre las filas activas. |
name | cadena | null | no | Nombre completo del prestatario. Se persiste en bruto; las lecturas para inversores lo enmascaran. |
email | cadena | null | no | Correo electrónico RFC 5322; se persiste en bruto; las lecturas para inversores lo enmascaran. |
phone | cadena | null | no | Teléfono de formato libre; se persiste en bruto; las lecturas para inversores lo enmascaran. |
nationalIdLast4 | cadena | null | no | Exactamente cuatro dígitos; nunca devuelve los dígitos iniciales. |
countryCode | cadena | null | no | Código ISO-3166 de dos letras (en mayúsculas). |
dob | cadena de fecha | null | no | YYYY-MM-DD. |
gender | enum | null | no | male | female | non_binary | other | undisclosed (sin distinción de mayúsculas). |
incomeBand | cadena | null | no | Formato libre. |
employmentStatus | cadena | null | no | Formato libre. |
metadata | objeto | null | no | Transferencia directa tal cual. |
Respuestas
201 Created en una escritura nueva, 200 OK en una reproducción idempotente:
{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "BORROWER-001",
"bronzeSubmissionId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789",
"reused": false
}| Estado | Sobre | Desencadenante |
|---|---|---|
200 OK | { id, externalId, bronzeSubmissionId, reused: true } | Idempotency-Key coincidió con una solicitud anterior; no hay escritura nueva. |
201 Created | { id, externalId, bronzeSubmissionId, reused: false } | Fila nueva insertada. |
400 Bad Request | fieldErrors | Fallo de validación en cualquier campo del cuerpo. |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | portfolioId no existe o pertenece a otra organización. |
409 Conflict | { error, code: "ID_CONFLICT", fieldErrors: [...] } | Ya existe un prestatario activo con el mismo id. |
cURL
curl -X POST https://app.waafir.io/api/v1/monitoring/loan/borrowers \
-H "Authorization: Bearer $WAAFIR_PAT" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e" \
-d '{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"externalId": "BORROWER-001",
"gender": "female",
"countryCode": "KE"
}'GET /api/v1/monitoring/loan/borrowers/{id}
Lee un prestatario por UUID de la plataforma. Los campos de PII se enmascaran por defecto; los administradores pueden solicitar la PII en bruto con ?unmask=true, lo que escribe una entrada en el registro de auditoría.
Solicitud
| Parámetro | Posición | Obligatorio | Restricción |
|---|---|---|---|
id | ruta | sí | El UUID de plataforma del prestatario. |
unmask | consulta | no | true devuelve la PII en bruto; solo para administradores. Por defecto se enmascara. |
Respuestas
200 OK con el registro del prestatario enmascarado:
{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"externalId": "BORROWER-001",
"name": "J***",
"email": "j***@example.com",
"phone": "***-***-1234",
"nationalIdLast4": "1234",
"countryCode": "KE",
"dob": "1985-03-20",
"gender": "female",
"incomeBand": null,
"employmentStatus": null,
"metadata": {}
}| Estado | Desencadenante |
|---|---|
200 OK | La fila existe en su organización. La PII se devuelve en bruto si el llamante es administrador Y pasa ?unmask=true; en caso contrario, la PII se enmascara. |
400 Bad Request | id no es un UUID bien formado. |
404 Not Found | La fila no existe, está cancelada o pertenece a otra organización. |
El enmascaramiento de PII se aplica a name, email, phone y nationalIdLast4. El campo nationalIdLast4 ya solo almacena los cuatro últimos dígitos en el momento de la escritura; aun así, el enmascaramiento en la lectura los oculta en las lecturas de usuarios no administradores.
Un llamante no administrador que pasa ?unmask=true no recibe un 403 — la respuesta sigue siendo 200 con la forma enmascarada, y se escribe una entrada en el registro de auditoría del intento de desenmascaramiento denegado. La plataforma no expone la comprobación de rol como un error porque la forma enmascarada es el valor predeterminado seguro; la pista de auditoría es lo que hace visible el intento para el equipo de seguridad.
Un llamante administrador que pasa ?unmask=true recibe la PII en bruto y la solicitud escribe una entrada separada en el registro de auditoría que deja constancia del desenmascaramiento. La respuesta lleva Cache-Control: private, no-store para impedir que los intermediarios almacenen en caché la carga útil con PII en bruto.
POST /api/v1/monitoring/loan/loans
Crea un préstamo vinculado a un prestatario existente en la misma cartera.
Solicitud
| Campo | Tipo | Obligatorio | Restricción |
|---|---|---|---|
id | cadena UUID | sí | Identificador de plataforma proporcionado por el llamante. |
portfolioId | cadena UUID | sí | La cartera propietaria. |
borrowerId | cadena UUID | sí | Un prestatario activo en la misma cartera. |
externalId | cadena | sí | 1-255 caracteres; único por cartera entre las filas activas. |
predecessorLoanId | cadena UUID | null | no | Se establece en una reestructuración; apunta al préstamo que se sustituye. |
principalAmount | cadena decimal | sí | Hasta cuatro dígitos fraccionarios. |
currencyCode | cadena | sí | ISO-4217 de tres letras; sin distinción de mayúsculas. |
interestRateApr | cadena decimal | sí | Hasta seis dígitos fraccionarios; debe ser >= 0. |
disbursementDate | cadena de fecha | sí | YYYY-MM-DD. |
termMonths | entero | sí | Debe ser > 0. |
repaymentFrequency | enum | sí | monthly | weekly | biweekly | quarterly | bullet (sin distinción de mayúsculas). |
productType | cadena | null | no | Formato libre, p. ej. "Term loan", "Overdraft". |
status | enum | sí | pending | active | paid_off | restructured | written_off | defaulted (sin distinción de mayúsculas). |
metadata | objeto | null | no | Transferencia directa tal cual. |
Respuestas
201 Created (o 200 OK en una reproducción idempotente) con { id, externalId, bronzeSubmissionId, reused }.
| Estado | Sobre | Desencadenante |
|---|---|---|
200 OK | { ..., reused: true } | Reproducción idempotente. |
201 Created | { ..., reused: false } | Préstamo nuevo insertado. |
400 Bad Request | fieldErrors | Fallo de validación (p. ej., interestRateApr negativo, currencyCode mal formado). |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | Cartera inexistente o de otra organización. |
409 Conflict | { error, code: "ID_CONFLICT" } | Ya existe un préstamo activo con el mismo id. |
422 Unprocessable Entity | { error, code: "REFERENCED_ENTITY_NOT_FOUND", fieldErrors: [{ path: "borrowerId", ... }] } | borrowerId no corresponde a un prestatario activo en la misma cartera. |
cURL
curl -X POST https://app.waafir.io/api/v1/monitoring/loan/loans \
-H "Authorization: Bearer $WAAFIR_PAT" \
-H "Content-Type: application/json" \
-d '{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"borrowerId": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "LOAN-001",
"principalAmount": "10000.00",
"currencyCode": "USD",
"interestRateApr": "0.18",
"disbursementDate": "2026-01-15",
"termMonths": 12,
"repaymentFrequency": "monthly",
"status": "active"
}'POST /api/v1/monitoring/loan/payments
Registra un pago efectivo vinculado a un préstamo existente. Úselo para pagos recibidos, pagos parciales y castigos. Las reestructuraciones se modelan como un préstamo nuevo con predecessorLoanId establecido, no como un pago.
Solicitud
| Campo | Tipo | Obligatorio | Restricción |
|---|---|---|---|
id | cadena UUID | sí | Identificador de plataforma proporcionado por el llamante. |
portfolioId | cadena UUID | sí | La cartera propietaria. |
loanId | cadena UUID | sí | Un préstamo activo en la misma cartera. |
externalId | cadena | sí | 1-255 caracteres; único por cartera entre las filas activas. |
paymentDate | cadena de fecha | sí | YYYY-MM-DD. |
amount | cadena decimal | sí | El total del pago recibido. |
currencyCode | cadena | sí | ISO-4217. |
principalPaid | cadena decimal | no | Valor predeterminado "0". |
interestPaid | cadena decimal | no | Valor predeterminado "0". |
feesPaid | cadena decimal | no | Valor predeterminado "0". |
writeOffAmount | cadena decimal | no | Valor predeterminado "0". Consulte la regla de condonación más abajo. |
paymentNotes | cadena | null | no | Debe ser "Forgiven" (sin distinción de mayúsculas) cuando writeOffAmount > 0. |
paymentMethod | enum | null | no | cash | bank_transfer | card | mobile_money | check | other. |
metadata | objeto | null | no | Transferencia directa tal cual. |
Regla de condonación. Si writeOffAmount > 0, paymentNotes debe ser igual a "Forgiven" sin distinción de mayúsculas. La plataforma rechaza la solicitud en el límite de la API, de modo que un pago incorrecto se rechaza antes de que se registre nada.
Respuestas
201 Created (o 200 OK en una reproducción idempotente) con { id, externalId, bronzeSubmissionId, reused }.
| Estado | Sobre | Desencadenante |
|---|---|---|
200 OK | { ..., reused: true } | Reproducción idempotente. |
201 Created | { ..., reused: false } | Pago nuevo insertado. |
400 Bad Request | fieldErrors | Fallo de validación (importes mal formados, valor de enumeración no reconocido, falta un campo obligatorio). |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | Cartera inexistente o de otra organización. |
409 Conflict | { error, code: "ID_CONFLICT" } | Ya existe un pago activo con el mismo id. |
422 Unprocessable Entity | { error, code: "REFERENCED_ENTITY_NOT_FOUND", fieldErrors: [{ path: "loanId", ... }] } | loanId no corresponde a un préstamo activo en la misma cartera. |
400 Bad Request | { error, code: "CHECK_VIOLATION", fieldErrors: [...] } | La regla de condonación se rechazó al almacenar el pago (poco frecuente; la validación rechaza antes la misma forma). |
GET /api/v1/monitoring/loan/payments/{id}
Lee un pago efectivo por UUID de la plataforma, incluidas las filas canceladas (con borrado lógico). Úselo para verificar una escritura o inspeccionar un registro cancelado.
Solicitud
| Parámetro | Posición | Obligatorio | Restricción |
|---|---|---|---|
id | ruta | sí | El UUID de plataforma del pago. |
Respuestas
200 OK con el registro completo del pago. Las filas canceladas aparecen con deletedAt informado; las filas activas tienen deletedAt: null. 404 Not Found si el UUID es de otra organización o desconocido. 400 Bad Request si id no es un UUID bien formado.
PATCH /api/v1/monitoring/loan/loans/{loanRef}/status
Cambia un préstamo a un nuevo estado. El segmento de ruta {loanRef} acepta o bien el UUID de plataforma del préstamo o bien su externalId. Cuando pasa un externalId, también debe indicar ?portfolioId=<UUID>, porque los ID externos no son únicos entre carteras.
Solicitud
PATCH /api/v1/monitoring/loan/loans/LOAN-001/status?portfolioId=ddf63d12-1234-5678-9abc-def012345678 HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json
Idempotency-Key: <opaque-key>Cuerpo:
| Campo | Tipo | Obligatorio | Restricción |
|---|---|---|---|
status | enum | sí | Uno de active | paid_off | defaulted | written_off | restructured (sin distinción de mayúsculas). |
effectiveDate | cadena de fecha | sí | YYYY-MM-DD. |
reason | cadena | null | no | 1-500 caracteres; se registra en el registro de auditoría. |
Matriz de transiciones de estado
La plataforma aplica una matriz de transiciones; una transición no válida devuelve 422 INVALID_STATUS_TRANSITION con fieldErrors que nombran los estados de origen y destino.
| Desde | Destinos permitidos |
|---|---|
pending | active |
active | paid_off, defaulted, written_off, restructured |
paid_off | (terminal) |
defaulted | written_off, restructured |
written_off | (terminal) |
restructured | (terminal) |
Cuando cambia un préstamo a restructured, el paso siguiente natural es un POST /loans para el préstamo sustituto con predecessorLoanId establecido. Las dos escrituras no son atómicas de forma intencionada — si el POST del sustituto falla, el predecesor permanece en restructured y la superficie de conciliación mostrará la desviación la próxima vez que consulte.
Respuestas
200 OK si se completa correctamente:
{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"externalId": "LOAN-001",
"status": "restructured",
"bronzeSubmissionId": "9d8c7b6a-5432-1098-7654-321098765432",
"reused": false
}| Estado | Sobre | Desencadenante |
|---|---|---|
200 OK | { id, externalId, status, bronzeSubmissionId, reused } | Transición aplicada (o reproducción idempotente con reused: true). |
400 Bad Request | fieldErrors | Fallo de validación del cuerpo, falta portfolioId al buscar por externalId, enumeración mal formada. |
404 Not Found | { error, code: "NOT_FOUND" } | Préstamo no encontrado por UUID, o (portfolioId, externalId) no se resuelve. |
422 Unprocessable Entity | { error, code: "INVALID_STATUS_TRANSITION", fieldErrors: [...] } | El par origen/destino no está en la matriz de transiciones; fieldErrors[].message enumera los destinos permitidos. |
409 Conflict | { error, code: "IDEMPOTENCY_CONFLICT" } | La Idempotency-Key ya se usó para una transición distinta. La escritura anterior se mantiene; envíe la nueva transición con una clave nueva. |
La effectiveDate que indica se registra con el envío y en el registro de auditoría; no aparece en el cuerpo de la respuesta. metadata no se acepta en esta ruta de forma intencionada — la propia transición es el evento de auditoría, y el campo opcional reason aporta el contexto legible por humanos.
POST /api/v1/monitoring/loan/payments/{id}/cancel
Aplica un borrado lógico a un pago registrado previamente. El endpoint de cancelación es la única superficie de reversión del dominio de préstamos — no existe PATCH /loans/{id}/adjust y no existirá.
Solicitud
POST /api/v1/monitoring/loan/payments/7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f/cancel HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/jsonCuerpo (opcional):
| Campo | Tipo | Obligatorio | Restricción |
|---|---|---|---|
reason | cadena | null | no | 1-500 caracteres; se registra en el evento de auditoría de la cancelación. |
Se acepta un cuerpo vacío; puede omitir por completo el encabezado Content-Type.
Respuestas
200 OK si se completa correctamente:
{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"deletedAt": "2026-03-15T11:02:33Z",
"bronzeSubmissionId": "9d8c7b6a-5432-1098-7654-321098765432",
"reused": false,
"alreadyCancelled": false
}En una segunda llamada sobre el mismo pago, la forma de la respuesta es idéntica salvo que alreadyCancelled: true y deletedAt es la marca de tiempo de la cancelación original. El indicador reused refleja el estado de idempotencia, mientras que alreadyCancelled indica si esta llamada modificó la fila.
| Estado | Sobre | Desencadenante |
|---|---|---|
200 OK | { id, deletedAt, bronzeSubmissionId, reused, alreadyCancelled } | Primera cancelación o posteriores. |
400 Bad Request | fieldErrors | id no es un UUID bien formado, o reason supera los 500 caracteres. |
404 Not Found | { error, code: "NOT_FOUND" } | El pago no existe o pertenece a otra organización. |
Se escribe un registro de envío en cada cancelación — incluida la segunda — para que la auditoría sea completa. La fila solo se modifica en la primera llamada.
Borrado lógico y reutilización de externalId
Un pago cancelado deja su externalId disponible para reutilizarlo en una escritura futura, porque la restricción de unicidad solo se aplica a las filas activas. Para corregir un envío erróneo, la vía canónica es:
POST /api/v1/monitoring/loan/payments/{id}/cancelsobre la fila original.POST /api/v1/monitoring/loan/paymentspara una fila nueva con los campos corregidos. Puede reutilizar el mismoexternalId; debe indicar uniddiferente.
Esto es intencionado: las cancelaciones no son destructivas (la fila original se conserva para la auditoría), y la reutilización de externalId mantiene denso el espacio operativo de ID de llamante a efectos de conciliación.