Waafir
Diese Seite ist eine maschinelle Übersetzung, die noch auf eine menschliche Prüfung wartet. Sie kann Fehler enthalten.

Ein Loan Tape per asynchronem NDJSON-Import im Ganzen importieren

Dieses Rezept zeigt den grundlegenden Erfassungsablauf für ein Waafir-Kreditportfolio: Übermitteln Sie eine NDJSON-Datei (Newline-Delimited JSON) mit einer Zeile pro Loan-Tape-Entität an den Endpunkt für asynchrone Importe und fragen Sie dann den Status des Imports ab, bis der Worker fertig ist.

Wann Sie diesen Ablauf verwenden

Der asynchrone NDJSON-Importablauf ist der maßgebliche Erfassungsweg für jede nicht triviale Menge an Zeilen. Er skaliert auf historische Nachlieferungen von Millionen Zeilen und ist derselbe Ablauf, der für inkrementelle tägliche Übermittlungen verwendet wird. Das Cookbook verwendet in den folgenden Beispielen einen loan-Import; derselbe Ablauf akzeptiert die Arten borrower, scheduled_repayment, actual_payment, collateral und collateral_valuation – ändern Sie das Feld kind und den Aufbau der Zeilen, alles andere ist identisch.

Der Aufbau des Ablaufs

Ihr Code muss drei Schritte ausführen, und dazwischen erledigt Ihre Datei einen Schritt:

  1. POST /api/v1/monitoring/loan/imports – geben Sie an, was Sie hochladen werden (Art, Dateiname, Größe). Die Antwort enthält eine Upload-URL und die Import-ID.
  2. PUT des NDJSON-Inhalts an die Upload-URL – Ihre Datei wird unverändert so gespeichert, wie sie übermittelt wurde.
  3. POST /api/v1/monitoring/loan/imports/{id}/commit – teilen Sie Waafir mit, dass der Upload abgeschlossen ist. Der Import wechselt von pending_upload zu queued, und der Worker beginnt mit der Verarbeitung der Batches.
  4. GET /api/v1/monitoring/loan/imports/{id} – fragen Sie ab, bis status einen der Werte succeeded, partial, failed oder cancelled hat.

Das Rezept

# 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)

Was Sie überprüfen sollten

Wenn status den Wert succeeded erreicht, ist jede Zeile Ihrer NDJSON-Datei als aktive Zeile angekommen. Die Antwort enthält außerdem rowCountProcessed, rowCountSucceeded und rowCountFailed; bei einem fehlerfreien Lauf entspricht die Zahl der erfolgreichen Zeilen der Zeilenzahl Ihrer Datei.

Wenn status den Wert partial erreicht, sind einige Zeilen angekommen und andere nicht. Wechseln Sie zum Rezept zur Untersuchung von Teilfehlern, um die zeilenbezogenen Fehler seitenweise durchzugehen und zu entscheiden, ob Sie die fehlerhaften Zeilen korrigieren und erneut übermitteln oder das Teilergebnis akzeptieren.

Der Status failed bedeutet, dass keine einzige Zeile angekommen ist. Das Feld errorSummary.samples enthält die ersten zehn Fehler-Payloads; die übrigen lassen sich über den Endpunkt für seitenweise abgerufene Fehler abfragen, der im Rezept zu Teilfehlern beschrieben ist.