Asynchrone Importe
Die Schnittstelle für asynchrone Importe ist der Weg für historische Ladevorgänge und jeden Batch oberhalb des Bulk-NDJSON-Limits von zehntausend Zeilen bzw. zehn Megabyte. Der Ablauf ist zweiphasig: Sie beschreiben, was Sie hochladen wollen, erhalten eine zeitlich begrenzte Upload-URL, laden die Datei per PUT direkt dorthin hoch und bitten dann die Plattform, sie zu committen. Danach liest ein Worker die Datei Zeile für Zeile ein, erfasst Fehler pro Zeile und meldet den Fortschritt über einen Status-Endpunkt.
Die hier gezeigten Routen sind die Einstiegspunkte des Kreditbereichs in den Importablauf.
Lebenszyklus
Der Lebenszyklus hat sieben Zustände. Die meisten Produktions-Ladevorgänge durchlaufen pending_upload → queued → processing → succeeded; die übrigen bilden Fehlerfälle ab.
| Zustand | Bedeutung |
|---|---|
pending_upload | Importzeile existiert; die zeitlich begrenzte Upload-URL ist aktiv; die Plattform hat die Datei noch nicht gesehen. |
queued | Commit erfolgreich; der Worker hat die Datei noch nicht übernommen. |
processing | Der Worker liest die Datei Zeile für Zeile ein. |
succeeded | Jede Zeile wurde gespeichert. |
partial | Die Datei wurde vollständig verarbeitet, aber mindestens eine Zeile ist fehlgeschlagen. |
failed | Ein schwerwiegender Fehler hat die Verarbeitung vor dem Abschluss gestoppt (z. B. fehlerhaftes gzip, fehlende hochgeladene Datei, interner Worker-Fehler). |
cancelled | Der Aufrufer hat den Import abgebrochen; der Worker hat an der nächsten Chunk-Grenze angehalten. |
Eine Zeile, die pending_upload nie verlässt, steht für eine Upload-URL, die ausgestellt, aber nie committet wurde; solche Zeilen werden nach Ablauf der TTL der URL routinemäßig bereinigt.
Routen im Überblick
| Methode | Pfad | Zweck |
|---|---|---|
POST | /api/v1/monitoring/loan/imports | Neuen Import starten; zeitlich begrenzte Upload-URL erhalten. |
POST | /api/v1/monitoring/loan/imports/{id}/commit | Upload abschließen, Worker in die Warteschlange stellen. |
GET | /api/v1/monitoring/loan/imports/{id} | Status, Zähler und Fehlerzusammenfassung lesen. |
GET | /api/v1/monitoring/loan/imports/{id}?errors=true | Seitenweise durch die Fehler pro Zeile blättern. |
GET | /api/v1/monitoring/loan/imports | Kreditimporte des Aufrufers auflisten. |
DELETE | /api/v1/monitoring/loan/imports/{id} | Laufenden Import abbrechen. |
POST /api/v1/monitoring/loan/imports
Startet einen neuen Import. Liefert die Import-ID, eine zeitlich begrenzte Upload-URL und die Upload-Header, die Ihr Client beim PUT der Datei mitsenden muss.
Request-Body
| Feld | Typ | Pflicht | Einschränkung |
|---|---|---|---|
kind | enum | ja | Eine der sechs Arten. |
filename | string | ja | 1–255 Zeichen; nur zur Anzeige. |
sizeBytes | integer | ja | Positive Ganzzahl; entspricht der Größe der Datei, die Sie hochladen wollen. |
portfolioId | UUID-String | null | nein | Optionale Überschreibung; die Zeilen im Body tragen weiterhin ihre eigene. |
idempotencyKey | string | null | nein | Der Header wird bevorzugt; das Body-Feld ist ein Fallback. |
dryRun | boolean | nein | true führt die Validierung aus, ohne in die Warteschlange zu stellen. |
metadata | object | null | nein | Unveränderte Durchreichung. |
rowCountDeclared | integer | null | nein | Unverbindlich – verbessert die Fortschrittsanzeige. |
Der HTTP-Header Idempotency-Key hat Vorrang vor dem Body-Feld, wenn beide angegeben sind.
Response – 202 Accepted
{
"importId": "1234abcd-5678-90ef-1234-567890abcdef",
"uploadUrl": "https://<upload-host>/...?<signature>",
"headers": { "<header-name>": "<header-value>" },
"s3Key": "imports/abc.../...",
"reused": false,
"statusUrl": "/api/v1/monitoring/loan/imports/1234abcd-5678-90ef-1234-567890abcdef",
"commitUrl": "/api/v1/monitoring/loan/imports/1234abcd-5678-90ef-1234-567890abcdef/commit"
}| Feld | Hinweise |
|---|---|
importId | Die Plattformkennung, auf die Sie sich in jedem weiteren Aufruf beziehen. |
uploadUrl | Zeitlich begrenzte URL für den PUT-Upload. |
headers | Eine Map von HTTP-Headern, die Ihr PUT enthalten muss. |
s3Key | Der Speicherschlüssel, unter dem die Datei abgelegt wird. |
reused | true, wenn die Response das Deduplizierungsergebnis eines früheren Idempotency-Key ist. |
statusUrl / commitUrl | Komfort-URLs für den nachfolgenden Lebenszyklus. |
Statuscodes
| Status | Envelope | Auslöser |
|---|---|---|
202 Accepted | wie oben | Importzeile angelegt. |
400 Bad Request | errors[] (path/message) | Validierungsfehler im Body. |
400 Bad Request | { error, code: "UNKNOWN_KIND", allowed: [...] } | kind ist keine der sechs Kreditarten. |
409 Conflict | { error, code: "IDEMPOTENCY_KEY_REUSED", importId, mismatchedFields } | Der Idempotency-Key wurde bereits für einen Import mit anderen Parametern verwendet. |
Die Datei hochladen
Sobald Sie eine uploadUrl haben, laden Sie die Datei per PUT direkt dorthin hoch. Senden Sie jeden Header aus der headers-Map der Response mit; die Signatur der URL deckt sie ab, andernfalls wird der Upload abgelehnt.
curl -X PUT "$UPLOAD_URL" \
-H "<header-name>: <header-value>" \
--data-binary @your-file.ndjsonDer Upload geht direkt in den Speicher; er läuft nicht über die API. Das Dateiformat ist dasselbe NDJSON-Übertragungsformat, das auf der Bulk-NDJSON-Seite dokumentiert ist, ohne Zeilenlimit.
POST /api/v1/monitoring/loan/imports/{id}/commit
Rufen Sie nach Abschluss des PUT den Commit auf, um der Plattform mitzuteilen, dass der Upload vollständig ist. Die Plattform bestätigt, dass die Datei existiert, setzt die Importzeile von pending_upload auf queued und stellt den Worker in die Warteschlange.
Request
Kein Body. Idempotency-Key ist implizit – ein zweiter Commit für eine Zeile, die nicht mehr in pending_upload ist, bewirkt nichts und liefert den aktuellen Zustand.
Responses
200 OK:
{ "importId": "1234abcd-...", "status": "queued" }| Status | Envelope | Auslöser |
|---|---|---|
200 OK | { importId, status } | Commit erfolgreich, oder die Zeile war bereits über pending_upload hinaus (idempotent). |
404 Not Found | Standard | Import existiert nicht oder gehört zu einer anderen Organisation. |
409 Conflict | { error, code: "COMMIT_FAILED" } | Die Plattform konnte die hochgeladene Datei nicht finden – typischerweise hat der Upload nie stattgefunden oder ist noch nicht abgeschlossen. Wiederholen Sie den Commit nach Abschluss des Uploads. |
GET /api/v1/monitoring/loan/imports/{id}
Liest den aktuellen Status, die Zähler und die Fehlerzusammenfassung eines Imports. Dies ist der Polling-Endpunkt, den Ihr Client aufruft, um den Fortschritt zu überwachen.
Request
| Parameter | Position | Pflicht | Hinweise |
|---|---|---|---|
id | Pfad | ja | Die Plattform-UUID des Imports. |
errors | Query | nein | true wechselt in den Modus für seitenweise abgerufene Fehler (siehe unten). |
Response – Standardmodus
{
"importId": "1234abcd-...",
"kind": "actual_payment",
"domain": "loan",
"status": "succeeded",
"filename": "payments-2025-full-year.ndjson",
"sizeBytes": 524288000,
"portfolioId": "ddf63d12-...",
"rowCountDeclared": 1500000,
"rowCountProcessed": 1500000,
"rowCountSucceeded": 1499987,
"rowCountFailed": 13,
"createdAt": "2026-05-20T10:00:00Z",
"startedAt": "2026-05-20T10:00:15Z",
"completedAt": "2026-05-20T10:18:42Z",
"dryRun": false,
"errorSummary": {
"totals": { "validation_error": 9, "fk_violation": 4 },
"samples": [
{ "rowNumber": 12, "errorCode": "validation_error", "errorMessage": "..." },
{ "rowNumber": 1041, "errorCode": "fk_violation", "errorMessage": "..." }
]
}
}errorSummary ist eine kleine eingebettete Zusammenfassung – Summen pro Fehlercode und bis zu zehn Beispielzeilen. Für die vollständige Liste pro Zeile wechseln Sie in den Modus für seitenweise abgerufene Fehler.
Response – ?errors=true&limit=&offset=
{
"items": [
{
"rowNumber": 12,
"errorCode": "validation_error",
"errorMessage": "interestRateApr must be >= 0",
"rawRow": "{\"id\":\"...\",\"interestRateApr\":\"-0.05\",...}",
"createdAt": "2026-05-20T10:01:14Z"
}
],
"limit": 20,
"offset": 0
}| Feld | Hinweise |
|---|---|
rowNumber | 1-basierter Zeilenindex im hochgeladenen NDJSON. |
errorCode | Häufige Werte sind parse_error (die Zeile war kein gültiges JSON), validation_error (das Schema hat die Zeile abgelehnt), portfolio_mismatch (die portfolioId der Zeile entspricht nicht dem Anker des Imports) und processor_error (ein unerwarteter Fehler im Handler). Die konsolidierte Liste finden Sie unter Fehler und Statuscodes. |
errorMessage | Für Menschen lesbare Fehlerzusammenfassung. |
rawRow | Die ursprüngliche NDJSON-Zeile, zur Fehlersuche unverändert aufbewahrt. |
limit ist standardmäßig 20, maximal 100. offset ist standardmäßig 0. Die Paginierung durchläuft die gespeicherte Fehlerliste in rowNumber-Reihenfolge, daher ist offset += limit ein stabiler Cursor.
Statuscodes
| Status | Auslöser |
|---|---|
200 OK | Zeile existiert in Ihrer Organisation. |
400 Bad Request | limit oder offset fehlerhaft bei ?errors=true. |
404 Not Found | Zeile nicht gefunden oder gehört zu einer anderen Organisation. |
GET /api/v1/monitoring/loan/imports
Listet die Kreditimporte des Aufrufers auf, die neuesten zuerst.
Request
| Parameter | Position | Pflicht | Einschränkung |
|---|---|---|---|
status | Query | nein | Einer der sieben Lebenszykluszustände. |
kind | Query | nein | Eine der sechs Kreditarten. |
limit | Query | nein | 1–100; Standard 20. |
offset | Query | nein | Nicht negativ; Standard 0. |
Response
{
"items": [
{
"importId": "...",
"kind": "actual_payment",
"status": "succeeded",
"filename": "...",
"createdAt": "...",
"completedAt": "...",
"rowCountSucceeded": 1499987,
"rowCountFailed": 13
}
],
"limit": 20,
"offset": 0
}DELETE /api/v1/monitoring/loan/imports/{id}
Bricht einen laufenden Import ab. Der Worker hält an der nächsten Chunk-Grenze an; bereits gespeicherte Zeilen bleiben erhalten. Das Abbrechen einer Zeile in einem Endzustand (succeeded, partial, failed oder cancelled) bewirkt nichts und liefert den bestehenden Zustand.
Responses
200 OK:
{ "importId": "1234abcd-...", "status": "cancelled" }| Status | Auslöser |
|---|---|
200 OK | Abbruch angewendet, oder die Zeile war bereits in einem Endzustand. |
404 Not Found | Zeile nicht gefunden oder gehört zu einer anderen Organisation. |
Arten
Das Feld kind im Start-Request bestimmt, gegen welches Schema jede Zeile validiert wird und welche Entität die Zeilen aufnimmt. Die sechs Arten entsprechen eins zu eins den Entitäten:
| Art | Entität | Schema |
|---|---|---|
borrower | borrowers | Wie POST /borrowers. |
loan | loans | Wie POST /loans. |
scheduled_repayment | scheduled_repayments | Schema für planmäßige Rückzahlungen. |
actual_payment | actual_payments | Wie POST /payments. |
collateral | collateral | Schema für Sicherheiten. |
collateral_valuation | collateral_valuations | Schema für Sicherheitenbewertungen. |
Ein kind, das nicht in dieser Liste steht, liefert 400 UNKNOWN_KIND mit den zulässigen Werten in der Response, sodass sich ein Tippfehler ohne Ausprobieren beheben lässt.
Wann Sie diese Schnittstelle nutzen
Nutzen Sie asynchrone Importe, wenn:
- Sie ein historisches Archiv laden – typische historische Ladevorgänge umfassen Millionen von Zeilen.
- Ihr Batch eines der beiden Bulk-NDJSON-Limits überschreitet (10 000 Zeilen oder 10 MB).
- Sie die Möglichkeit haben wollen, mitten im Ladevorgang abzubrechen – Bulk-NDJSON hat keine Abbruchschnittstelle, weil der Request selbst der Ladevorgang ist.
- Ihr Client Polling toleriert – es gibt keine Push-Benachrichtigung, wenn ein Import abgeschlossen ist.
Für kleine operative Batches, die in einen einzigen synchronen Request passen, ist Bulk-NDJSON der einfachere Weg.