Conciliación
La superficie de conciliación le permite verificar lo que llegó a Waafir usando sus propios ID de llamante en lugar de los UUID asignados por la plataforma. Es intencionadamente mínima — dos rutas —, pero es la columna vertebral operativa de una integración robusta: toda ingesta diaria saludable termina con una llamada de conciliación.
Por qué conciliar por ID de llamante
Cuando envía un préstamo con externalId: "L-001", su sistema ya conoce la fila por ese nombre. Preguntar a la plataforma «¿tienes L-001?» es el paso siguiente natural — y no tener que traducirlo antes a un UUID de la plataforma significa que su lógica de conciliación puede funcionar con los mismos identificadores que usa su contabilidad.
La plataforma garantiza que un externalId es único dentro de una cartera entre las filas activas, y eso es lo que convierte la búsqueda por externalId en una lectura de una sola fila.
Rutas
| Método | Ruta | Propósito |
|---|---|---|
GET | /api/v1/monitoring/loan/loans/{externalId}?portfolioId=<UUID> | Leer un único préstamo por ID de llamante. |
GET | /api/v1/monitoring/loan/counts | Leer los totales de filas por entidad, opcionalmente acotados por cartera, fecha o entidad. |
GET /api/v1/monitoring/loan/loans/{externalId}
Lee un único préstamo por el externalId que envió. Excluye las filas canceladas (con borrado lógico).
Solicitud
| Parámetro | Posición | Obligatorio | Restricción |
|---|---|---|---|
externalId | ruta | sí | 1-255 caracteres; codifique con porcentajes cualquier carácter no seguro para URL. |
portfolioId | consulta | sí | UUID de la cartera propietaria del préstamo. |
El portfolioId es obligatorio porque externalId no es único entre carteras — solo es único dentro de una cartera.
Respuesta — 200 OK
{
"loan": {
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"borrowerId": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "L-001",
"predecessorLoanId": null,
"principalAmount": "10000.0000",
"currencyCode": "USD",
"interestRateApr": "0.180000",
"disbursementDate": "2026-01-15",
"termMonths": 12,
"repaymentFrequency": "monthly",
"productType": "Term loan",
"status": "active",
"metadata": {},
"createdAt": "2026-01-15T08:00:00Z",
"updatedAt": "2026-01-15T08:00:00Z"
},
"borrower": {
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "B-001",
"name": "J***",
"email": "j***@example.com",
"phone": "***-***-1234",
"nationalIdLast4": "1234",
"countryCode": "KE",
"dob": "1985-03-20",
"gender": "female",
"incomeBand": null,
"employmentStatus": null
}
}La respuesta incrusta el prestatario del préstamo con la PII enmascarada. Es la vista con ámbito de inversor — el mismo enmascaramiento que se aplica al endpoint GET de prestatario. El enmascaramiento le permite confirmar que «este préstamo está vinculado al prestatario correcto» sin exponer PII al sistema que realiza la llamada. Los administradores que necesitan la PII en bruto utilizan la superficie de prestatario por UUID con ?unmask=true y registro en el registro de auditoría.
Los campos de importe aparecen con toda la precisión almacenada (cuatro dígitos fraccionarios para los importes monetarios; seis para interestRateApr); su cliente debe tratarlos como cadenas decimales opacas en lugar de convertirlos a números de coma flotante.
Códigos de estado
| Estado | Desencadenante |
|---|---|
200 OK | Préstamo encontrado en su organización. |
400 Bad Request | Falta portfolioId o está mal formado, o externalId contiene una codificación porcentual mal formada. |
404 Not Found | El préstamo no existe como fila activa en la cartera indicada, o la cartera pertenece a otra organización. |
cURL
curl https://app.waafir.io/api/v1/monitoring/loan/loans/L-001?portfolioId=ddf63d12-1234-5678-9abc-def012345678 \
-H "Authorization: Bearer $WAAFIR_PAT"GET /api/v1/monitoring/loan/counts
Lee los recuentos de filas por entidad, opcionalmente acotados por cartera, por fecha o a una sola entidad. Se excluyen las filas con borrado lógico.
Solicitud
| Parámetro | Posición | Obligatorio | Restricción |
|---|---|---|---|
portfolioId | consulta | no | UUID; acota a una sola cartera. Omítalo para obtener un agregado de toda la organización. |
date | consulta | no | YYYY-MM-DD; si se indica, la respuesta incluye un recuento onDate por entidad. |
entity | consulta | no | Uno de borrowers, loans, scheduled_repayments, actual_payments, collateral, collateral_valuations (sin distinción de mayúsculas). Si se indica, solo se devuelve esa entidad. |
Respuesta — 200 OK
Agregado predeterminado, las seis entidades:
{
"counts": {
"borrowers": { "total": 1200 },
"loans": { "total": 3450 },
"scheduled_repayments": { "total": 41400 },
"actual_payments": { "total": 32118 },
"collateral": { "total": 600 },
"collateral_valuations": { "total": 1840 }
},
"date": null,
"portfolioId": null
}Con ?date=2026-05-22, cada entidad obtiene un recuento onDate de las filas creadas en la fecha indicada:
{
"counts": {
"borrowers": { "total": 1200, "onDate": 0 },
"loans": { "total": 3450, "onDate": 12 },
"scheduled_repayments": { "total": 41400, "onDate": 144 },
"actual_payments": { "total": 32118, "onDate": 1207 },
"collateral": { "total": 600, "onDate": 0 },
"collateral_valuations": { "total": 1840, "onDate": 0 }
},
"date": "2026-05-22",
"portfolioId": null
}Con ?entity=loans, solo aparece la entrada loans.
Códigos de estado
| Estado | Desencadenante |
|---|---|
200 OK | Consulta analizada; recuentos devueltos. |
400 Bad Request | portfolioId, date o entity mal formados. |
Un portfolioId que no existe o pertenece a otra organización no devuelve 404; devuelve 200 con ceros en todos los valores. Esto es intencionado — la superficie de recuentos es una lectura de sus propios datos, y una cartera desconocida es funcionalmente indistinguible de una cartera sin filas.
cURL
# Full daily reconciliation for one portfolio:
curl "https://app.waafir.io/api/v1/monitoring/loan/counts?portfolioId=ddf63d12-1234-5678-9abc-def012345678&date=2026-05-22" \
-H "Authorization: Bearer $WAAFIR_PAT"Una conciliación diaria típica
Una vez completados los envíos del día, el flujo canónico de conciliación es:
- Llame a
GET /counts?date=<today>con su cartera. Compare el recuentoonDatede cada entidad con lo que envió hoy. Si los recuentos coinciden con lo enviado, su lote se registró correctamente. - Para cualquier discrepancia, busque las filas concretas con
GET /loans/{externalId}. Las búsquedas son baratas — un solo recorrido de índice cada una — y devuelven el estado canónico de la fila, incluido el UUID asignado por la plataforma, que luego puede usar para investigar más a fondo. - Para la investigación a nivel de fila, los endpoints GET de registro único y el endpoint de errores paginados de importaciones asíncronas son las superficies que exponen el detalle de los fallos por fila.
La superficie de conciliación es intencionadamente de solo lectura y económica — es el latido de la integración, no una superficie de carga. Llámela una o dos veces al día por cartera; no tiene un límite de frecuencia específico, pero le rogamos que no la consulte en un bucle cerrado.