Recetario
Este recetario está dirigido a los ingenieros de fintech que conectan su cartera de préstamos a la API de monitorización de Waafir. Cada receta recorre una tarea de principio a fin con los tres clientes de referencia —cURL, TypeScript y Python—, de modo que el lector no tenga que traducir mentalmente entre lenguajes. Las recetas se centran en los caminos de fallo y casos límite con los que se topa una integración real, no solo en el camino feliz.
A quién va dirigido
El administrador de su organización en Waafir le ha emitido un token de acceso personal (PAT), y usted está escribiendo el código que envía a Waafir sus datos diarios de la cinta de préstamos: prestatarios, préstamos, amortizaciones programadas, pagos efectivos, garantías y valoraciones de garantías. Cada envío se registra tal como se envió y luego se almacena como filas; a partir de ahí alimenta la pestaña de monitorización para inversores de cualquier sala de datos vinculada a la cartera.
Cómo usar estas recetas
Todas las recetas tienen la misma estructura: una breve introducción en prosa, tres bloques de código en un orden fijo y un breve párrafo de verificación. Los bloques de código son:
- cURL: para copiar y pegar en su shell. Es el menos condicionado; útil para pruebas puntuales y comprobaciones de CI.
- TypeScript: basado en
fetchsobre los contratos JSON públicos. No requiere instalar ningún SDK. - Python: basado en
requestssobre los mismos contratos JSON. Basta con la biblioteca estándar; no se necesita ningún paquete específico de Waafir.
Autenticación
Todos los endpoints requieren un PAT en la cabecera Authorization:
Authorization: Bearer <YOUR_PAT>Un PAT está limitado a una única organización de Waafir y transmite la identidad de esa organización en cada solicitud. Trátelo como un secreto; rótelo desde el panel si se filtra. La URL base de la API en todas estas recetas es https://app.waafir.io; sustitúyala por su URL de staging si primero integra contra el tenant de pruebas (sandbox).
Convenciones utilizadas en las recetas
- Todas las variables de shell de los ejemplos de cURL se escriben como
${UPPER_CASE_NAME}para que pueda hacerexportuna vez y reutilizarlas en todas las recetas. - Los ejemplos de TypeScript y Python suponen que
BASE_URLyPATse leen del entorno. Adáptelos a su cargador de configuración. - La cabecera
Idempotency-Keyes la convención de toda la plataforma para reintentos seguros; consulte la receta de reintentos para conocer la semántica precisa. - Todos los endpoints de escritura aceptan sus propios valores de
external_id: los identificadores proporcionados por el cliente siguen siendo la referencia canónica durante la ingesta, la conciliación y las descargas de la cinta. Nunca necesita conocer los UUID internos de Waafir.
Qué no cubre el recetario
El recetario está orientado a tareas. Para las definiciones exhaustivas de los endpoints, los esquemas de solicitud y respuesta y las referencias de códigos de error, consulte la sección de referencia de la API cuando se publique junto al recetario. Para los conceptos del producto, como qué es una cartera y cómo se relaciona con una sala de datos, consulte Salas de datos y la sección de conceptos fundamentales.
Las recetas
- Importar de forma masiva una cinta de préstamos mediante NDJSON asíncrono: el flujo de ingesta fundamental: carga directa, confirmación (commit) y sondeo hasta la finalización.
- Validar una carga con dry-run antes de confirmar los datos: el mismo flujo con
?dryRun=true; sepa qué contiene su archivo antes de que se escriba ninguna fila. - Reintentar de forma segura con una clave de idempotencia: supere fallos de red transitorios sin crear importaciones duplicadas.
- Inspeccionar los errores de fallo parcial tras una importación: recorra página a página los errores por fila cuando una importación termina como
partial. - Cancelar una importación en curso: detenga una importación de larga duración en el siguiente límite de lote sin filas escritas parcialmente.
- Conciliar sus datos por ID externo: confirme que una fila se ha registrado, mediante su propio identificador, y verifique los recuentos diarios.