Stapelimport (asynchron)

Übersicht

Stapelimporte laufen asynchron: Der POST legt einen Import-Job an und antwortet sofort mit 202 und einer jobId. Ihr System fragt anschließend den Job-Status ab (GET /api/v1/import-jobs/{jobId}), bis der Import abgeschlossen ist, und erhält dort das vollständige Ergebnis — inklusive der Gründe für übersprungene oder fehlgeschlagene Zeilen. Der Import nutzt dieselbe Engine wie der CSV-Import in der App: gleiche Validierung, gleicher idempotenter Abgleich, gleiches Ergebnisformat.

Endpunkt	Vorgang	Abgleichschlüssel
`POST /api/v1/articles`	Artikel im Stapel importieren	`internalArticleNr`
`POST /api/v1/suppliers`	Lieferanten im Stapel importieren	`externalSupplierId` bzw. Name
`POST /api/v1/orders`	Bestellungen im Stapel importieren	`orderNumber`
`GET /api/v1/import-jobs/{jobId}`	Job-Status und Ergebnis abfragen	—

Ein POST mit einem einzelnen Objekt (ohne rows-Array) bleibt synchron und antwortet unverändert mit 201. Nur die Stapel-Form (Array bzw. Objekt mit rows) ist asynchron.Dieser Ablauf gilt für die Endpunkte mit 5.000-Zeilen-Limit — die drei oben und POST /api/v1/ppwr/quantities. Die PPWR-Stammdaten-Endpunkte und POST /api/v1/ppwr/tonnage (1.000-Zeilen-Limit; darüber 400, nicht 413) sind synchron: 200 mit dem Ergebnis im Body, es entsteht kein Job. Siehe PPWR.

Ablauf

Stapel senden — POST mit einem Array von Zeilen oder einem Objekt mit rows:
{ "rows": [ { "…": "…" } ] }
Bei Erfolg: 202 mit { "jobId": "…", "status": "queued", "statusUrl": "/api/import-jobs/…" } (auch als Location-Header; statusUrl ist host-relativ — nur an den Ursprung anhängen). Zu diesem Zeitpunkt ist noch nichts importiert. Die Zeilen-Validierung läuft synchron — ein fehlerhafter Stapel wird sofort mit 400 abgelehnt, ohne dass ein Job entsteht. Das erste Element von path in jedem Eintrag von details ist der 0-basierte Index der fehlerhaften Zeile in rows, z. B. [17, "quantity"]. Eine fehlerhafte Zeile lehnt die ganze Anfrage ab, nichts wird angelegt — diese Zeile korrigieren oder entfernen und den Stapel erneut senden.
Status abfragen — GET /api/v1/import-jobs/{jobId} etwa alle 2 Sekunden, bei großen Jobs mit steigendem Abstand (z. B. exponentiell bis ~30 s). completed und failed sind final — danach nicht weiter abfragen.
Ergebnis auswerten — bei status: "completed" enthält result das zusammengeführte Import-Ergebnis (imported, updated, failed, skipped, … je nach Entität). Jeder Eintrag in failed nennt seinen Datensatz (orderNumber, internalArticleNr bzw. name) und trägt error.key — einen stabilen, nicht lokalisierten Schlüssel — und manchmal error.params. Ein failed-Job trägt seinen Grund stattdessen in error (siehe Tabelle unten).

Limits

Maximal 5.000 Zeilen pro Anfrage. Darüber: 413 { "error": "batchTooLarge", "maxBatchSize": 5000 } — es wird nichts angelegt. Größere Abgleiche auf mehrere Anfragen aufteilen.
~4,5 MB pro Anfrage (Plattform-Limit, greift vor unserer Anwendung).
Für einen großen Erstimport Stapel mit etwa 100 bis 500 Bestellungen (jeweils mit allen Zeilen, bis zum 5.000-Zeilen-Limit) senden statt einer Anfrage je Bestellung: Jede Anfrage wird ein Job, die Jobs eines Unternehmens laufen nur zu wenigen gleichzeitig, und weniger Jobs heißt weniger jobIds zum Abfragen.
Ein leeres Array oder ein fehlerhaftes Objekt mit rows → 400.

Teil-Akzeptanz und Idempotenz

Gültige Zeilen werden übernommen, auch wenn andere Zeilen in failed landen.
Ein Job schreibt in Abschnitten. Bricht er unterwegs ab (workerError, oder lineReplacementRequired nach einer gleichzeitigen Änderung), können frühere Abschnitte schon geschrieben sein. Den Stapel erneut zu senden ist gefahrlos.
Ein identischer Import lässt sich gefahrlos wiederholen: bereits vorhandene Zeilen kommen als übersprungen/aktualisiert zurück, es entstehen keine Duplikate.
Artikelfelder in Bestellzeilen (hsCode, articleDescription) wirken nur beim Anlegen — siehe Bestellungen.

Fehlerschlüssel (stabil, nicht lokalisiert)

Das error eines fehlgeschlagenen Jobs ist ein Text: entweder ein reiner Schlüssel oder JSON, dessen key der stabile Teil ist. Zeilen- und Bestellschlüssel stehen im Ergebnis eines abgeschlossenen Jobs als failed[].error.key.

Schlüssel	Ebene	Bedeutung
`batchTooLarge`	Anfrage	Die Anfrage überschreitet das 5.000-Zeilen-Limit (HTTP `413`); es wird nichts angelegt
`lineReplacementRequired`	Job	Ein Bestell-Job würde gespeicherte Zeilen löschen — alle Zeilen der Bestellungen senden oder `replaceLines` setzen. `error` ist JSON: `{"key":"lineReplacementRequired","orderNumbers":[…]}`
`invalidPayload`	Job	Die Zeilen sind bei der erneuten Prüfung im Worker durchgefallen; `error` ist JSON: `{"key":"invalidPayload","issues":[…]}` mit `path` + `code` je Fehler, nie die Werte selbst
`missingImportActor`	Job	Der Benutzer, der den Job angelegt hat (der Benutzer des Schlüssels), existiert nicht mehr; nichts wurde geschrieben — mit einem gültigen Schlüssel erneut senden
`workerError`	Job	Unerwarteter Fehler nach allen Wiederholungsversuchen (Details serverseitig erfasst); frühere Abschnitte können schon geschrieben sein
`dispatchFailed`	Job	Für Sie nicht sichtbar: Der Job konnte nicht gestartet werden, und der `POST` antwortete mit `500` ohne `jobId`. Ein `500` auf den `POST` heißt: Es läuft nichts — erneut senden
`positionIdMixed`	Bestellung	Zeilen mit und ohne `positionId` gemischt — alle oder keine
`duplicatePositionId`	Bestellung	Dieselbe `positionId` auf zwei Zeilen
`conflictingHsCodeForArticle`	Bestellung	Derselbe Artikel mit unterschiedlichen HS-Codes (nur mit Pro-Bestellung-Kopien)
`conflictingDuplicateOrderRows`	Bestellung	Zeilen der Bestellung widersprechen sich in einem Bestellfeld, oder die Übertragung ändert Lieferant, `orderType` oder `orderDate` einer gespeicherten Bestellung
`articleMissingHsCode`	Bestellung / Artikelzeile	Ein neuer Artikel ohne brauchbaren HS-Code (leer oder ein Platzhalter wie `-`)
`articleDeleted`	Bestellung / Artikelzeile	Die Artikelnummer gehört zu einem gelöschten Artikel
`articleNotResolved`	Bestellung	Der Artikel einer Bestellzeile konnte nicht zugeordnet werden
`supplierDeleted`	Bestellung / Artikelzeile	Der genannte Lieferant ist gelöscht
`supplierNotResolved`	Bestellung	Der Lieferant der Einkaufsbestellung konnte weder zugeordnet noch angelegt werden
`selfSupplierError`	Bestellung / Artikelzeile	Verkaufsbestellung bzw. Verkaufsartikel: Der Lieferanten-Datensatz Ihres eigenen Unternehmens konnte nicht geladen werden
`conflictingDuplicateArticleRows`	Artikelzeile	Zeilen derselben `internalArticleNr` widersprechen sich in einem Feld
`purchaseRequiresSupplier`	Artikelzeile	Ein Einkaufsartikel ohne Lieferant (`supplierId` oder `supplierName`)
`supplierExternalIdConflict`	Artikelzeile	Der Lieferantenname trifft einen Lieferanten mit einer anderen externen ID
`invalidWeightPerPiece`	Artikelzeile	`weightPerPieceKg` ist keine positive Zahl
`duplicateInternalArticleNr`	Artikelzeile	Eine gleichzeitige Anfrage hat dieselbe `internalArticleNr` zuerst angelegt
`conflictingDuplicateSupplierRows`	Lieferantenzeile	Zeilen, die denselben Lieferanten nennen (über Name oder externe ID), widersprechen sich
`ambiguousSupplierMatch`	Lieferantenzeile	Name oder externe ID der Zeile treffen mehr als einen gespeicherten Lieferanten, oder beide treffen verschiedene Lieferanten
`supplierModifiedDuringImport`	Lieferantenzeile	Der Lieferant wurde geändert oder gelöscht, während der Job lief
`dbError`	Bestellung / Zeile	Unerwarteter Datenbankfehler ohne spezifischen Schlüssel

Die bestellspezifischen Schlüssel (lineReplacementRequired, positionIdMixed, duplicatePositionId, conflictingHsCodeForArticle, conflictingDuplicateOrderRows) erklärt Bestellungen. Ein Bestellschlüssel lässt die ganze Bestellung fehlschlagen; nichts davon wird geschrieben.

Aufbewahrung

Das Job-Ergebnis bleibt abfragbar; die übermittelten Eingabedaten werden ~24 Stunden nach Abschluss gelöscht, der Job-Datensatz ~30 Tage nach Erstellung gelöscht. Fragen Sie das Ergebnis innerhalb dieses Fensters ab und persistieren Sie es auf Ihrer Seite.

Berechtigungen

Der POST erfordert die Schreibberechtigung der Entität (articles:write, suppliers:write, orders:write), das Abfragen des Jobs die jeweilige Leseberechtigung (in der Schreibberechtigung enthalten). Jobs sind strikt mandantengebunden: eine unbekannte jobId und die jobId eines anderen Unternehmens liefern dieselbe 404.