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

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.

ZustandBedeutung
pending_uploadImportzeile existiert; die zeitlich begrenzte Upload-URL ist aktiv; die Plattform hat die Datei noch nicht gesehen.
queuedCommit erfolgreich; der Worker hat die Datei noch nicht übernommen.
processingDer Worker liest die Datei Zeile für Zeile ein.
succeededJede Zeile wurde gespeichert.
partialDie Datei wurde vollständig verarbeitet, aber mindestens eine Zeile ist fehlgeschlagen.
failedEin schwerwiegender Fehler hat die Verarbeitung vor dem Abschluss gestoppt (z. B. fehlerhaftes gzip, fehlende hochgeladene Datei, interner Worker-Fehler).
cancelledDer 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

MethodePfadZweck
POST/api/v1/monitoring/loan/importsNeuen Import starten; zeitlich begrenzte Upload-URL erhalten.
POST/api/v1/monitoring/loan/imports/{id}/commitUpload 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=trueSeitenweise durch die Fehler pro Zeile blättern.
GET/api/v1/monitoring/loan/importsKreditimporte 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

FeldTypPflichtEinschränkung
kindenumjaEine der sechs Arten.
filenamestringja1–255 Zeichen; nur zur Anzeige.
sizeBytesintegerjaPositive Ganzzahl; entspricht der Größe der Datei, die Sie hochladen wollen.
portfolioIdUUID-String | nullneinOptionale Überschreibung; die Zeilen im Body tragen weiterhin ihre eigene.
idempotencyKeystring | nullneinDer Header wird bevorzugt; das Body-Feld ist ein Fallback.
dryRunbooleanneintrue führt die Validierung aus, ohne in die Warteschlange zu stellen.
metadataobject | nullneinUnveränderte Durchreichung.
rowCountDeclaredinteger | nullneinUnverbindlich – 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"
}
FeldHinweise
importIdDie Plattformkennung, auf die Sie sich in jedem weiteren Aufruf beziehen.
uploadUrlZeitlich begrenzte URL für den PUT-Upload.
headersEine Map von HTTP-Headern, die Ihr PUT enthalten muss.
s3KeyDer Speicherschlüssel, unter dem die Datei abgelegt wird.
reusedtrue, wenn die Response das Deduplizierungsergebnis eines früheren Idempotency-Key ist.
statusUrl / commitUrlKomfort-URLs für den nachfolgenden Lebenszyklus.

Statuscodes

StatusEnvelopeAuslöser
202 Acceptedwie obenImportzeile angelegt.
400 Bad Requesterrors[] (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.ndjson

Der 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" }
StatusEnvelopeAuslöser
200 OK{ importId, status }Commit erfolgreich, oder die Zeile war bereits über pending_upload hinaus (idempotent).
404 Not FoundStandardImport 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

ParameterPositionPflichtHinweise
idPfadjaDie Plattform-UUID des Imports.
errorsQueryneintrue 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
}
FeldHinweise
rowNumber1-basierter Zeilenindex im hochgeladenen NDJSON.
errorCodeHä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.
errorMessageFür Menschen lesbare Fehlerzusammenfassung.
rawRowDie 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

StatusAuslöser
200 OKZeile existiert in Ihrer Organisation.
400 Bad Requestlimit oder offset fehlerhaft bei ?errors=true.
404 Not FoundZeile 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

ParameterPositionPflichtEinschränkung
statusQueryneinEiner der sieben Lebenszykluszustände.
kindQueryneinEine der sechs Kreditarten.
limitQuerynein1–100; Standard 20.
offsetQueryneinNicht 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" }
StatusAuslöser
200 OKAbbruch angewendet, oder die Zeile war bereits in einem Endzustand.
404 Not FoundZeile 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:

ArtEntitätSchema
borrowerborrowersWie POST /borrowers.
loanloansWie POST /loans.
scheduled_repaymentscheduled_repaymentsSchema für planmäßige Rückzahlungen.
actual_paymentactual_paymentsWie POST /payments.
collateralcollateralSchema für Sicherheiten.
collateral_valuationcollateral_valuationsSchema 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.