Importer en masse un loan tape via NDJSON asynchrone
Cette recette présente le flux d'ingestion de base d'un portefeuille de prêts Waafir : soumettre à l'endpoint d'import asynchrone un fichier NDJSON (JSON délimité par des sauts de ligne) contenant une ligne par entité du loan tape, puis interroger le statut de l'import jusqu'à ce que le worker ait terminé.
Quand utiliser ce flux
Le flux d'import NDJSON asynchrone est la voie d'ingestion canonique pour tout volume de lignes non négligeable. Il passe à l'échelle des reprises d'historique de plusieurs millions de lignes et c'est le même flux qui sert aux soumissions quotidiennes incrémentales. Les exemples ci-dessous utilisent un import de type loan ; le même flux accepte les types borrower, scheduled_repayment, actual_payment, collateral et collateral_valuation — modifiez le champ kind et la structure des lignes, tout le reste est identique.
Structure du flux
Votre code doit effectuer trois étapes, et votre fichier une étape entre les deux :
POST /api/v1/monitoring/loan/imports— déclarez ce que vous allez téléverser (type, nom de fichier, taille). La réponse contient une URL de téléversement et l'identifiant de l'import.PUTdu corps NDJSON vers l'URL de téléversement — votre fichier est stocké tel que soumis, sans modification.POST /api/v1/monitoring/loan/imports/{id}/commit— indiquez à Waafir que le téléversement est terminé. L'import passe depending_uploadàqueued, et le worker commence à traiter les lots.GET /api/v1/monitoring/loan/imports/{id}— interrogez jusqu'à ce questatusprenne l'une des valeurssucceeded,partial,failedoucancelled.
La recette
# 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)Ce qu'il faut vérifier
Lorsque status atteint succeeded, chaque ligne de votre fichier NDJSON a été enregistrée comme ligne active. La réponse expose également rowCountProcessed, rowCountSucceeded et rowCountFailed ; lors d'une exécution sans erreur, le nombre de lignes réussies est égal au nombre de lignes de votre fichier.
Lorsque status atteint partial, certaines lignes ont été enregistrées et d'autres non. Passez à la recette d'inspection des échecs partiels pour parcourir page par page les erreurs ligne par ligne et décider s'il faut corriger les lignes fautives et les soumettre à nouveau, ou accepter le résultat partiel.
Un statut failed signifie qu'aucune ligne n'a été enregistrée. Le champ errorSummary.samples contient les dix premières erreurs ; les autres peuvent être consultées via l'endpoint d'erreurs paginées décrit dans la recette sur les échecs partiels.