Importar de forma masiva una cinta de préstamos mediante NDJSON asíncrono
Esta receta muestra el flujo de ingesta fundamental para una cartera de préstamos de Waafir: envíe al endpoint de importación asíncrona un archivo JSON delimitado por saltos de línea (NDJSON) que contenga una fila por cada entidad de la cinta de préstamos y, a continuación, sondee el estado de la importación hasta que el worker termine.
Cuándo usar este flujo
El flujo de importación asíncrona de NDJSON es la vía de ingesta canónica para cualquier volumen de filas no trivial. Escala a cargas históricas de millones de filas y es el mismo flujo que se usa para los envíos diarios incrementales. El recetario utiliza una importación de tipo loan en los ejemplos siguientes; el mismo flujo acepta los tipos borrower, scheduled_repayment, actual_payment, collateral y collateral_valuation: cambie el campo kind y la forma de las filas, y todo lo demás es idéntico.
La estructura del flujo
Su código debe realizar tres pasos, y su archivo realiza uno entre medias:
POST /api/v1/monitoring/loan/imports: declare lo que va a cargar (tipo, nombre de archivo, tamaño). La respuesta incluye una URL de carga y el ID de la importación.PUTdel cuerpo NDJSON a la URL de carga: su archivo se almacena tal como se envió, sin cambios.POST /api/v1/monitoring/loan/imports/{id}/commit: indique a Waafir que la carga ha terminado. La importación pasa depending_uploadaqueued, y el worker empieza a procesar lotes.GET /api/v1/monitoring/loan/imports/{id}: sondee hasta questatussea uno desucceeded,partial,failedocancelled.
La receta
# curl — bulk import flow (loan kind)
set -euo pipefail
PAT="${WAAFIR_PAT}"
BASE_URL="${WAAFIR_BASE_URL:-https://app.waafir.io}"
NDJSON_FILE="loans-2026-05-22.ndjson"
# Step 1 — start the import and capture the upload URL + import ID.
START=$(curl -fsS -X POST "${BASE_URL}/api/v1/monitoring/loan/imports" \
-H "Authorization: Bearer ${PAT}" \
-H "Content-Type: application/json" \
-d "$(cat <<JSON
{
"kind": "loan",
"filename": "${NDJSON_FILE}",
"sizeBytes": $(stat -c%s "${NDJSON_FILE}")
}
JSON
)")
IMPORT_ID=$(echo "$START" | jq -r .importId)
UPLOAD_URL=$(echo "$START" | jq -r .uploadUrl)
# Step 2 — PUT the NDJSON body to the upload URL. The `headers` field
# on the start response carries the headers the upload URL was signed
# with — apply them all, or the upload is rejected with a signature
# mismatch. At minimum `Content-Type: application/x-ndjson`.
HEADER_ARGS=$(echo "$START" | jq -r '.headers | to_entries[] | "-H \"\(.key): \(.value)\""')
eval curl -fsS -X PUT --data-binary @"\"${NDJSON_FILE}\"" $HEADER_ARGS "\"${UPLOAD_URL}\""
# Step 3 — commit so the worker enqueues the import.
curl -fsS -X POST "${BASE_URL}/api/v1/monitoring/loan/imports/${IMPORT_ID}/commit" \
-H "Authorization: Bearer ${PAT}"
# Step 4 — poll status until it reaches a terminal value.
while :; do
STATUS=$(curl -fsS "${BASE_URL}/api/v1/monitoring/loan/imports/${IMPORT_ID}" \
-H "Authorization: Bearer ${PAT}" | jq -r .status)
echo "import ${IMPORT_ID}: ${STATUS}"
case "${STATUS}" in
succeeded|partial|failed|cancelled) break ;;
esac
sleep 5
done// TypeScript — bulk import flow (loan kind)
import { readFileSync, statSync } from "node:fs";
const PAT = process.env.WAAFIR_PAT!;
const BASE_URL = process.env.WAAFIR_BASE_URL ?? "https://app.waafir.io";
const NDJSON_FILE = "loans-2026-05-22.ndjson";
const headers = { Authorization: `Bearer ${PAT}`, "Content-Type": "application/json" };
// Step 1 — start the import.
const startRes = await fetch(`${BASE_URL}/api/v1/monitoring/loan/imports`, {
method: "POST",
headers,
body: JSON.stringify({
kind: "loan",
filename: NDJSON_FILE,
sizeBytes: statSync(NDJSON_FILE).size,
}),
});
if (!startRes.ok) throw new Error(`start failed: ${startRes.status} ${await startRes.text()}`);
const { importId, uploadUrl, headers: uploadHeaders } = (await startRes.json()) as {
importId: string;
uploadUrl: string;
headers: Record<string, string>;
};
// Step 2 — PUT the NDJSON body to the upload URL with the headers
// the URL was signed against. Skipping them gets the upload
// rejected with a signature mismatch.
const putRes = await fetch(uploadUrl, {
method: "PUT",
headers: uploadHeaders,
body: readFileSync(NDJSON_FILE),
});
if (!putRes.ok) throw new Error(`upload failed: ${putRes.status}`);
// Step 3 — commit.
const commitRes = await fetch(`${BASE_URL}/api/v1/monitoring/loan/imports/${importId}/commit`, {
method: "POST",
headers: { Authorization: `Bearer ${PAT}` },
});
if (!commitRes.ok) throw new Error(`commit failed: ${commitRes.status} ${await commitRes.text()}`);
// Step 4 — poll.
const TERMINAL = new Set(["succeeded", "partial", "failed", "cancelled"]);
while (true) {
const statusRes = await fetch(`${BASE_URL}/api/v1/monitoring/loan/imports/${importId}`, {
headers: { Authorization: `Bearer ${PAT}` },
});
const body = (await statusRes.json()) as { status: string };
console.log(`import ${importId}: ${body.status}`);
if (TERMINAL.has(body.status)) break;
await new Promise((r) => setTimeout(r, 5_000));
}# python — bulk import flow (loan kind)
import os
import time
import requests
from pathlib import Path
PAT = os.environ["WAAFIR_PAT"]
BASE_URL = os.environ.get("WAAFIR_BASE_URL", "https://app.waafir.io")
NDJSON_FILE = Path("loans-2026-05-22.ndjson")
headers = {"Authorization": f"Bearer {PAT}", "Content-Type": "application/json"}
# Step 1 — start the import.
start = requests.post(
f"{BASE_URL}/api/v1/monitoring/loan/imports",
headers=headers,
json={
"kind": "loan",
"filename": NDJSON_FILE.name,
"sizeBytes": NDJSON_FILE.stat().st_size,
},
timeout=30,
)
start.raise_for_status()
payload = start.json()
import_id = payload["importId"]
upload_url = payload["uploadUrl"]
upload_headers = payload["headers"] # signed-into the URL; must be sent on PUT
# Step 2 — PUT the NDJSON body to the upload URL with the headers
# the URL was signed against. Skipping them gets the upload
# rejected with a signature mismatch.
with NDJSON_FILE.open("rb") as fh:
put = requests.put(upload_url, data=fh, headers=upload_headers, timeout=300)
put.raise_for_status()
# Step 3 — commit.
commit = requests.post(
f"{BASE_URL}/api/v1/monitoring/loan/imports/{import_id}/commit",
headers={"Authorization": f"Bearer {PAT}"},
timeout=30,
)
commit.raise_for_status()
# Step 4 — poll.
terminal = {"succeeded", "partial", "failed", "cancelled"}
while True:
status = requests.get(
f"{BASE_URL}/api/v1/monitoring/loan/imports/{import_id}",
headers={"Authorization": f"Bearer {PAT}"},
timeout=30,
).json()
print(f"import {import_id}: {status['status']}")
if status["status"] in terminal:
break
time.sleep(5)Qué verificar
Cuando status llega a succeeded, todas las filas de su archivo NDJSON se han registrado como filas activas. La respuesta también muestra rowCountProcessed, rowCountSucceeded y rowCountFailed; en una ejecución limpia, el recuento de filas correctas es igual al número de filas de su archivo.
Cuando status llega a partial, algunas filas se registraron y otras no. Pase a la receta de inspección de fallos parciales para recorrer página a página los errores por fila y decidir si corrige las filas problemáticas y vuelve a enviarlas o acepta el resultado parcial.
Un estado failed significa que no se registró ninguna fila. El campo errorSummary.samples contiene las diez primeras cargas de error; el resto se puede consultar mediante el endpoint de errores paginados descrito en la receta de fallos parciales.