Bulk-NDJSON
Die Bulk-NDJSON-Schnittstelle nimmt bis zu zehntausend Zeilen in einem einzigen synchronen HTTP-Request an, validiert jede Zeile gegen dieselben Schemas, die die Einzeldatensatz-Routen verwenden, und liefert einen Fehlerbericht auf Zeilenebene. Nutzen Sie sie für Tagesend-Batches, die bequem in einen HTTP-Request passen; für historische Ladevorgänge oder größere Batches verwenden Sie asynchrone Importe.
Das Übertragungsformat ist zeilengetrenntes JSON (newline-delimited JSON): ein gültiges JSON-Objekt pro Zeile, kein abschließendes Komma, kein umschließendes Array, kein öffnendes oder schließendes Envelope. Leerzeilen zwischen Objekten werden akzeptiert und übersprungen.
Routen
Es gibt eine Route pro Entität. Das pro Zeile angewendete Schema entspricht der Entität in der URL.
| Methode | Pfad | Entität |
|---|---|---|
POST | /api/v1/monitoring/loan/bulk/borrowers | borrower |
POST | /api/v1/monitoring/loan/bulk/loans | loan |
POST | /api/v1/monitoring/loan/bulk/scheduled-repayments | scheduled_repayment |
POST | /api/v1/monitoring/loan/bulk/actual-payments | actual_payment |
POST | /api/v1/monitoring/loan/bulk/collateral | collateral |
POST | /api/v1/monitoring/loan/bulk/collateral-valuations | collateral_valuation |
Jede Zeile im Request-Body muss ein gültiges JSON-Objekt sein, das dem Schema der Entität entspricht, wie es auf der Einzeldatensatz-Seite dokumentiert ist. Die Schemas sind identisch; nur das Übertragungs-Envelope unterscheidet sich.
Request
POST /api/v1/monitoring/loan/bulk/loans HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/x-ndjson
Idempotency-Key: <opaque-key>Header und Query-Parameter:
| Name | Position | Pflicht | Hinweise |
|---|---|---|---|
Authorization | Header | ja | Bearer-PAT. |
Content-Type | Header | nein | application/x-ndjson empfohlen; application/json wird akzeptiert. |
Idempotency-Key | Header | nein | Für Produktions-Batches dringend empfohlen. |
?dryRun=true | Query | nein | Führt die Validierung aus, überspringt Schreibvorgänge. |
?portfolioId=<UUID> | Query | ja | Der Mandantenanker für den Batch; fehlt er oder ist er fehlerhaft, wird 400 portfolio_id_required zurückgegeben. |
Die Bulk-Schnittstelle liest portfolioId ausschließlich aus dem Query-String; das gleichnamige Feld im Body jeder Zeile wird auf der Ebene des Batch-Wrappers ignoriert. Jede Zeile im Body muss auf dasselbe Portfolio verweisen.
Der Body ist die NDJSON-Nutzlast selbst – UTF-8-kodiert und mit einem einzelnen Zeilenumbruch abgeschlossen. Mehr als zehntausend Zeilen oder Bodys über zehn Megabyte werden abgelehnt – siehe Größenlimits.
Vertrag pro Zeile
Jede Zeile wird unabhängig gegen das Entitätsschema validiert. Pro Zeile gelten dieselben Regeln wie bei einem Einzeldatensatz-Schreibvorgang:
- Jede Zeile muss ihre eigene
id-UUID undportfolioIdenthalten. Vom Aufrufer vergebene IDs sind der Deduplizierungsschlüssel pro Zeile. - Der gesamte Batch teilt sich den
Idempotency-Keyauf Request-Ebene. Siehe Idempotenz weiter unten. metadatagilt pro Zeile. Eine Zeile kann eigene durchgereichte Metadaten enthalten; die Plattform speichert sie unverändert.- Regeln für Währungen, Datumsangaben, Enums und Geldbeträge sind identisch mit denen für Einzeldatensätze. Eine Zeile, die die Validierung nicht besteht, erscheint als Eintrag im Fehlerbericht pro Zeile mit
code: "validation_failed".
Eine Zeile, die die Validierung nicht besteht, bricht den Batch nicht ab – der Fehler erscheint als Eintrag in errors[], und die übrigen Zeilen werden weiterverarbeitet.
Response
200 OK wird für jeden Batch zurückgegeben, dessen Request selbst geparst werden konnte – unabhängig davon, wie viele einzelne Zeilen erfolgreich waren oder fehlgeschlagen sind. Der Response-Body enthält den vollständigen Bericht pro Zeile:
{
"totalRows": 4,
"succeeded": 3,
"failed": 1,
"bronzeSubmissionId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789",
"reused": false,
"errors": [
{
"rowNumber": 2,
"code": "fk_violation",
"message": "borrowerId references a borrower that does not exist in this portfolio"
}
]
}| Feld | Typ | Beschreibung |
|---|---|---|
totalRows | integer | Die Anzahl der nicht leeren Zeilen im Body. |
succeeded | integer | Die Anzahl der gespeicherten Zeilen. |
failed | integer | totalRows - succeeded. |
bronzeSubmissionId | UUID | Die ID des einen Übermittlungsdatensatzes für den gesamten NDJSON-Body. Fehlt bei einer ?dryRun=true-Response. |
reused | boolean | Nur vorhanden und true, wenn ein Idempotency-Key einem früheren Batch entsprach und die Response rekonstruiert wurde; andernfalls nicht vorhanden. |
dryRun | boolean | Nur bei einer ?dryRun=true-Response vorhanden und true; andernfalls nicht vorhanden. |
errors[].rowNumber | integer | 1-basierter Zeilenindex im Request-Body. |
errors[].code | enum | validation_failed | unique_violation | fk_violation | check_violation | db_error. |
errors[].message | string | Für Menschen lesbare Zusammenfassung; bei validation_failed werden die Validierungsfehler zu einem einzigen Satz zusammengefasst. |
Die Fehlerform pro Zeile enthält nur rowNumber, code und message. Es gibt kein fieldErrors-Array pro Zeile und kein rawRow pro Zeile – das ursprüngliche NDJSON bleibt unverändert im Übermittlungsdatensatz erhalten, statt in der Response zurückgegeben zu werden.
Ein succeeded von 0 ist keine Fehler-Response – der Batch wurde geparst und die Plattform hat jede Zeile verarbeitet; der Bericht teilt Ihnen mit, dass nichts angekommen ist. Ein tatsächlich fehlgeschlagener Batch (fehlerhaftes NDJSON im gesamten Body, zu großer Body, unbekanntes Portfolio) liefert 4xx gemäß der folgenden Tabelle.
Statuscodes
Die Fehler-Envelopes auf oberster Ebene dieser Schnittstelle verwenden code-Werte in Kleinschreibung, im Unterschied zu den Codes in Großschreibung der Einzeldatensatz-Routen. Die beiden Code-Räume sind bewusst getrennt.
| Status | Envelope | Auslöser |
|---|---|---|
200 OK | Bericht pro Zeile | Batch verarbeitet; Ergebnisse pro Zeile in errors[]. |
400 Bad Request | { error, code: "invalid_body", errors: [...] } | Der Request-Body konnte nicht als Text gelesen werden. |
400 Bad Request | { error, code: "portfolio_id_required", fieldErrors: [...] } | ?portfolioId=<UUID> fehlt oder ist keine gültige UUID. |
400 Bad Request | { error, code: "invalid_json" } | Erscheint zeilenweise im Bericht pro Zeile – eine Zeile, die kein gültiges JSON ist, erhält einen Eintrag code: "invalid_json" in errors[]. Der Batch als Ganzes liefert weiterhin 200. |
404 Not Found | { error, code: "portfolio_not_found", fieldErrors: [...] } | Die ?portfolioId= existiert in Ihrer Organisation nicht als aktives Portfolio. |
413 Payload Too Large | { error, code: "batch_too_large", fieldErrors: [...] } | Siehe Größenlimits. |
Größenlimits
Die Bulk-Schnittstelle begrenzt Nutzlasten auf den kleineren der folgenden Werte:
- Zehntausend nicht leere Zeilen. Darüber hinausgehende Zeilen werden vor Beginn der Verarbeitung abgelehnt.
- Zehn Megabyte Request-Body.
Ein Request, der eines der Limits überschreitet, erhält 413 Payload Too Large:
{
"error": "batch payload exceeds 10485760 bytes; use the async import endpoint at /api/v1/monitoring/loan/imports",
"code": "batch_too_large",
"fieldErrors": [{ "path": "(body)", "message": "max 10485760 bytes" }]
}Das Envelope für das Byte-Limit und das für das Zeilenlimit verwenden beide code: "batch_too_large"; error und fieldErrors[].message unterscheiden den Auslöser. Der kanonische Ausweg ist, dieselbe Nutzlast auf den Ablauf der asynchronen Importe umzustellen, der die Datei direkt hochlädt und sie ohne Zeilenlimit asynchron verarbeitet.
Idempotenz
Die Bulk-Schnittstelle dedupliziert anhand des Idempotency-Key auf Ebene des Batch-Envelopes. Die Funktionsweise:
- Erster Aufruf mit Schlüssel
K. Der Body wird als eine einzige Übermittlung aufgezeichnet, jede Zeile wird verarbeitet, und der Bericht pro Zeile wird mit der Übermittlung gespeichert. - Zweiter Aufruf mit Schlüssel
K, gleicher Body. Kein zweiter Datensatz, kein erneutes Einfügen. Die Plattform liefert den ursprünglichen Bericht mitreused: true. - Zweiter Aufruf mit Schlüssel
K, anderer Body. Die Plattform liefert trotzdem den ursprünglichen Bericht – die ursprüngliche Übermittlung ist maßgeblich. Ein erneuter POST mit korrigiertem Body muss einen anderen Schlüssel verwenden.
Ein Client, der nach einem Netzwerkaussetzer einen erneuten Versuch unternimmt, ist also auch dann sicher, wenn der Body des zweiten Requests unterwegs abgeschnitten oder verändert wurde – die Plattform liefert die Ergebnisse auf Zeilenebene aus der ersten erfolgreichen Verarbeitung.
Übermittlungsdatensatz
Jeder Bulk-Request wird als eine Übermittlung aufgezeichnet, die den gesamten NDJSON-Body enthält, nicht als eine pro Zeile. Eine erneut gesendete Zeile wird nie doppelt gespeichert, weil eine externalId innerhalb eines Portfolios unter den aktiven Zeilen eindeutig ist.
Die bronzeSubmissionId in der Response ist die ID des Übermittlungsdatensatzes; speichern Sie sie zusammen mit Ihrem lokalen Übermittlungsdatensatz für Prüfung und Abgleich.
cURL-Beispiel
cat <<'EOF' > batch.ndjson
{"id":"a1...","portfolioId":"ddf63d12-1234-5678-9abc-def012345678","borrowerId":"b1...","externalId":"L-001","principalAmount":"5000","currencyCode":"USD","interestRateApr":"0.18","disbursementDate":"2026-01-15","termMonths":12,"repaymentFrequency":"monthly","status":"active"}
{"id":"a2...","portfolioId":"ddf63d12-1234-5678-9abc-def012345678","borrowerId":"b2...","externalId":"L-002","principalAmount":"3000","currencyCode":"USD","interestRateApr":"0.20","disbursementDate":"2026-01-15","termMonths":24,"repaymentFrequency":"monthly","status":"active"}
{"id":"a3...","portfolioId":"ddf63d12-1234-5678-9abc-def012345678","borrowerId":"b3...","externalId":"L-003","principalAmount":"7500","currencyCode":"USD","interestRateApr":"0.22","disbursementDate":"2026-01-15","termMonths":18,"repaymentFrequency":"monthly","status":"active"}
EOF
curl -X POST "https://app.waafir.io/api/v1/monitoring/loan/bulk/loans?portfolioId=ddf63d12-1234-5678-9abc-def012345678" \
-H "Authorization: Bearer $WAAFIR_PAT" \
-H "Content-Type: application/x-ndjson" \
-H "Idempotency-Key: nightly-2026-01-15-loans" \
--data-binary @batch.ndjsonWann Bulk-NDJSON und wann asynchrone Importe
Wählen Sie Bulk-NDJSON, wenn:
- Ihr Batch in zehntausend Zeilen und zehn Megabyte passt.
- Sie einen sofortigen Bericht pro Zeile in der HTTP-Response möchten.
- Sie einen lang laufenden HTTP-Request tolerieren können – Bulk-Batches sind in der Regel in wenigen Sekunden abgeschlossen, aber ein großer Batch mit vielen Fremdschlüssel-Lookups in der Datenbank kann länger dauern.
Wählen Sie asynchrone Importe, wenn:
- Ihr Batch eines der beiden Größenlimits überschreitet.
- Sie ein historisches Archiv von Zahlungen, planmäßigen Rückzahlungen oder Kreditnehmern laden – typische historische Ladevorgänge umfassen Millionen von Zeilen.
- Sie sich die Möglichkeit offenhalten wollen, einen laufenden Ladevorgang abzubrechen.