Referencia de la API
Esta sección es el manual de referencia de la API del dominio de préstamos de Waafir — la superficie HTTP que las fintech utilizan para transmitir datos de cartera a Waafir para el monitoreo por parte de los inversores. Documenta cada ruta bajo /api/v1/monitoring/loan/, los esquemas de solicitud y respuesta, cada código de estado, el contrato compartido de experiencia para desarrolladores y los sobres de error que debe esperar.
La referencia es exhaustiva, pero no narrativa. Si se integra por primera vez y desea una receta guiada de principio a fin — con cURL, TypeScript y Python en paralelo — lea el Recetario junto con esta referencia; ambos están pensados para leerse juntos.
Qué cubre la API
La API del dominio de préstamos expone cuatro modalidades de ingesta más una superficie de conciliación:
- CRUD de registro único — una llamada HTTP por fila. Úselo para escrituras operativas de bajo volumen: un único préstamo nuevo, un único pago, una transición de estado.
- NDJSON masivo — hasta diez mil filas en una sola llamada síncrona. Úselo para lotes de cierre de jornada que caben en una sola solicitud HTTP.
- Importaciones asíncronas — una carga directa de archivo seguida de un procesamiento asíncrono. Úselas para cargas históricas o para cualquier lote de más de diez mil filas.
- Conciliación — lectura de las filas enviadas mediante sus propios ID de llamante, y recuentos de filas por entidad. Úsela para verificar que el envío de ayer se registró correctamente antes de enviar el de hoy.
Cada modalidad se trata en su propia página. El orden de las páginas coincide con el orden en que la mayoría de los integradores las recorren: lea la descripción general, después el modo de ingesta que planea usar primero, luego la conciliación y, por último, la referencia de errores.
Las seis entidades del dominio de préstamos
Cada ruta opera sobre una o varias de las siguientes entidades. Sus esquemas completos se documentan por ruta — esta lista es el catálogo:
borrower— la persona física o jurídica que recibe el préstamo, con campos de PII opcionales que se enmascaran en la lectura.loan— el propio contrato de préstamo: principal, moneda, APR, plazo, frecuencia de reembolso, estado.scheduled_repayment— el calendario contractual de reembolsos, una fila por fecha de vencimiento.actual_payment— los pagos efectivamente recibidos, incluidos los castigos y los pagos parciales.collateral— la garantía pignorada en respaldo de un préstamo.collateral_valuation— valoraciones puntuales de una fila de garantía, con soporte para varios métodos.
Cada entidad pertenece a una cartera de su organización. La cartera se indica en cada escritura; la organización proviene de su token de acceso personal y nunca aparece en el cuerpo de una solicitud.
La autenticación en una línea
Cada solicitud lleva Authorization: Bearer <PAT>, donde <PAT> es un token de acceso personal emitido por el plano de control de Waafir. Los tokens están limitados a una organización — un token emitido para la organización A no puede leer ni escribir datos de la organización B, y las lecturas entre organizaciones devuelven 404 Not Found en lugar de 403 Forbidden para no revelar la existencia de recursos de otro inquilino.
El modelo completo de autenticación y autorización se trata en la descripción general.
Cómo usar esta referencia
Lea las páginas en orden o vaya directamente a la superficie que necesite:
- Descripción general — el contrato compartido que respeta cada ruta del dominio de préstamos: autenticación, las garantías de integración (ID proporcionados por el llamante, idempotencia, ejecuciones de prueba), sobres de error, convenciones de importes y fechas, semántica de cancelación y cómo se registra cada envío.
- CRUD de registro único — cada ruta de POST, GET, PATCH y cancelación de una sola fila.
- NDJSON masivo — ingesta masiva síncrona con informe de errores por fila.
- Importaciones asíncronas — el ciclo de vida de carga en dos fases, consulta periódica del estado y paginación de errores.
- Conciliación — lectura por ID de llamante y recuentos de filas por entidad.
- Errores y códigos de estado — el catálogo consolidado de cada código de estado, sobre de error y código de error con nombre que emite la superficie del dominio de préstamos.
Para guías orientadas a tareas — incorporar una cartera de principio a fin, ejecutar una conciliación diaria, recuperarse de una importación parcialmente fallida — consulte el Recetario (publicado junto con esta referencia). El Recetario recorre cada tarea en tres lenguajes; esta referencia es la fuente de verdad de lo que cada ruta acepta y devuelve.
Qué no incluye esta referencia
- Incorporación y tokens — cómo registrar una organización, crear una cartera y emitir un token de acceso personal. Esos flujos se tratan en la documentación de administración de la plataforma y en la receta de primeros pasos del Recetario.
- Analítica para inversores — paquetes de gráficos, la exportación de la cinta y la superficie de descarga de la cinta de préstamos. Se ofrecen mediante rutas separadas y no se tratan aquí.
- Webhooks y entrega programada de la cinta — no se tratan aquí.