Waafir
Esta página es una traducción automática pendiente de revisión humana. Puede contener errores.

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:

  1. cURL: para copiar y pegar en su shell. Es el menos condicionado; útil para pruebas puntuales y comprobaciones de CI.
  2. TypeScript: basado en fetch sobre los contratos JSON públicos. No requiere instalar ningún SDK.
  3. Python: basado en requests sobre 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 hacer export una vez y reutilizarlas en todas las recetas.
  • Los ejemplos de TypeScript y Python suponen que BASE_URL y PAT se leen del entorno. Adáptelos a su cargador de configuración.
  • La cabecera Idempotency-Key es 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

  1. 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.
  2. 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.
  3. Reintentar de forma segura con una clave de idempotencia: supere fallos de red transitorios sin crear importaciones duplicadas.
  4. 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.
  5. 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.
  6. Conciliar sus datos por ID externo: confirme que una fila se ha registrado, mediante su propio identificador, y verifique los recuentos diarios.