Bestellungen: Zeilen, Positionsnummern, Status, Delta-Sync

​

Bestellungen: replaceLines und die Vollständigkeitsregel

• Standard (replaceLines fehlt oder ist nicht true): Würde der Stapel gespeicherte Zeilen löschen, schlägt der gesamte Job vor dem ersten Schreibvorgang fehl. Das error-Feld des Jobs ist ein Text, der JSON enthält — werten Sie ihn als JSON aus:
  { "error": "{\"key\":\"lineReplacementRequired\",\"orderNumbers\":[\"O\"]}" }
  
  Senden Sie die genannten Bestellungen mit allen ihren Zeilen erneut. Eine Ausnahme: Ändert ein anderer Schreibvorgang eine der Bestellungen, während der Job läuft, kann der Job mit diesem Schlüssel fehlschlagen, nachdem frühere Bestellungen desselben Jobs schon geschrieben wurden.
• "replaceLines": true erlaubt das Ersetzen: Die gesendeten Zeilen werden maßgeblich, auch wenn dabei Zeilen entfallen. Der Wert muss das JSON-Boolean true sein, auf oberster Ebene neben rows. Der Text "true" gilt als nicht gesetzt, und ein reines Array von Zeilen kann den Wert nicht setzen.
• Dieselbe orderNumber nie in zwei Anfragen, die gleichzeitig laufen: Jobs eines Unternehmens können parallel laufen, ihre Reihenfolge ist nicht garantiert, und am Ende könnten die Zeilen der älteren Anfrage gespeichert sein. Eine geänderte Bestellung erst erneut senden, wenn der vorige Job dafür completed oder failed erreicht hat.

​

Positionen (positionId)

• Zeilen mit positionId werden nie zusammengefasst. Zwei Zeilen desselben Artikels mit verschiedenen Positionsnummern bleiben zwei Zeilen; ohne positionId werden sie beim Abgleich als eine Zeile (Summe der Mengen) behandelt.
• Ganz oder gar nicht pro Bestellung: Innerhalb einer Anfrage müssen alle Zeilen einer Bestellung eine positionId haben oder keine (positionIdMixed). Eine Positionsnummer darf pro Bestellung nur einmal vorkommen (duplicatePositionId). Beides lässt die gesamte Bestellung fehlschlagen, nichts davon wird geschrieben.
• Abgleich: Beim erneuten Senden einer Bestellung wird jede Zeile über ihre positionId verglichen — eine geänderte Menge oder ein geänderter Artikel auf derselben Positionsnummer gilt als Änderung, eine fehlende Positionsnummer als entfernte Zeile (Prüfung auf ersetzte Zeilen, siehe oben).
• Umstellung: Eine ohne Positionsnummern gespeicherte Bestellung, die erstmals mit positionId gesendet wird, gilt als vollständig ersetzt. Dasselbe gilt umgekehrt: eine mit Positionsnummern gespeicherte Bestellung, die ohne sie gesendet wird. Senden Sie diesen Import mit "replaceLines": true.
• Rücklesen: GET /api/v1/orders liefert positionId an jeder Zeile zurück. DDS-Referenzen sind nicht mit Zeilen verknüpft: ddsReferences gehört zur ganzen Bestellung (siehe unten).

​

Bestellstatus (status)

• notRelevant: Keine Zeile der Bestellung trägt einen EUDR-relevanten Artikel. Zeilen, deren Artikel gelöscht wurde, zählen nicht (sie fehlen auch in lines[]). Ein Artikel, dessen HS-Code noch auf die manuelle Prüfung der EUDR-Relevanz wartet (z. B. Position 9403), hält die Bestellung auf open, nicht auf notRelevant oder done; an dieser Zeile ist lines[].article.needsManualCheck true.
• done: Jede EUDR-relevante Zeile ist durch eine eingereichte, validierte oder gruppierte DDS-Erklärung abgedeckt, die mit dieser Bestellung verknüpft ist und den Artikel der Zeile für den Lieferanten der Bestellung mit ausreichender Menge deklariert. Ein DDS-Eintrag ist ein Lieferantenartikel: Er deckt nur Bestellungen desselben Lieferanten und verbraucht nur deren Mengen. Die Menge des Artikels, summiert über alle mit dieser DDS-Erklärung verknüpften Bestellungen dieses Lieferanten, darf die deklarierte Menge nicht übersteigen — genau wie die Restmenge der DDS-Erklärung selbst. Eine Bestellung eines anderen Lieferanten, die manuell mit dieser DDS-Erklärung verknüpft wurde, bleibt open.
• open: alles andere — auch eine Bestellung mit einem Artikel, der auf die manuelle Prüfung der EUDR-Relevanz wartet.

• Freigabe einer Position (z. B. SAP-Sperre): Geben Sie eine Position nur frei, wenn
  1. der status der Bestellung done ist (jede EUDR-relevante Zeile ist durch eine eingereichte DDS-Erklärung abgedeckt) oder notRelevant, oder
  2. für eine einzelne Zeile lines[].article.eudrRelevant false und lines[].article.needsManualCheck false ist (der Artikel der Zeile ist nicht EUDR-relevant).
  Eine einzelne Position hat kein eigenes notRelevant. Entscheiden Sie immer auf Grundlage des aktuellen Abrufs, nie eines früheren. ddsReferences brauchen Sie erst nach dieser Entscheidung: für die TRACES-Referenz und die Verifizierungsnummer, die Sie auf die Dokumente drucken.

• status kann open sein, obwohl ddsReferences nicht leer ist. ddsReferences enthält jede verknüpfte DDS-Erklärung, die nicht zurückgezogen oder abgelehnt ist — auch Entwürfe, archivierte, externe, in Kontrolle befindliche und gelöschte (soft-deleted) Erklärungen sowie Erklärungen, deren deklarierte Menge überbucht ist; keine davon macht die Bestellung done. Lesen Sie die zu druckenden TRACES-Nummern aus ddsReferences (eine externe DDS-Erklärung macht eine Bestellung nie done, ihre Referenz steht also nur hier); sie gehören zur Bestellung, nicht zu einer Position. Lesen Sie status dafür, ob die ganze Bestellung abgedeckt ist.
• Filter ?status=: nimmt genau einen Wert (open, done oder notRelevant) und darf nur einmal übergeben werden; alles andere ist ein 400.
• Nicht jeder Statuswechsel ist für die Bestellung eine Änderung im Sinne von changedSince. Diese Ereignisse ändern status, ohne die Bestellung zu ändern: eine andere Bestellung erhöht ihre Menge auf derselben DDS-Erklärung, die EUDR-Relevanz eines Artikels ändert sich, die manuelle Prüfung eines Artikels wird abgeschlossen, ein Artikel der Bestellung wird gelöscht, die deklarierte Menge eines DDS-Artikels wird bearbeitet, ein Lieferantenartikel wird gelöscht, die Artikel einer abdeckenden DDS-Erklärung ändern sich. Lesen Sie zum Abgleich mit ?status=open&limit=1000 neu und blättern Sie mit offset, bis eine Seite kürzer als limit ist.
• Das Löschen eines Lieferanten entfernt alle seine Bestellungen aus GET /api/v1/orders, auch aus dem Voll-Sync. Behandeln Sie eine Bestellung, die im Voll-Sync fehlt, als gelöscht.

​

Delta-Sync (changedSince)

​

Artikelfelder in Bestellzeilen wirken nur beim Anlegen

​

HS-Code auf Bestellzeilen mit Pro-Bestellung-Kopien (hsCode)

• ein Einkaufsbestellungs-Import ihn angelegt hat — in jedem Arbeitsbereich, mit oder ohne die Einstellung unten;
• er mit sourceScope: "perOrder" gesendet wurde;
• die Arbeitsbereich-Einstellung „Bestellimport legt Pro-Bestellung-Kopien an“ aktiv ist (standardmäßig aus, wird auf Anfrage von Polygon One eingeschaltet) und eine Zeile einer Einkaufsbestellung ihn nennt — außer einem Artikel mit einer externen Artikelnummer (vom Bestellimport angelegte Artikel tragen keine).

• Die Kopie trägt den HS-Code der Zeile. Weicht der HS-Code von dem der Vorlage ab, wird die EUDR-Relevanz neu berechnet; sonst bleibt die Einstufung der Vorlage erhalten. Eine Zeile ohne hsCode behält die Kopie, die sie hat, bzw. übernimmt den HS-Code der Vorlage.
• Ein geänderter HS-Code verschiebt die Zeile auf eine andere Version. Senden Sie die Bestellung mit einem geänderten HS-Code erneut (verglichen ohne Trennzeichen, also 4407.11 = 440711), zeigt die Zeile auf die Version der Kopie dieser Bestellung, die diesen HS-Code hat. Eine neue Version entsteht nur, wenn es noch keine gibt; eine ältere Version mit diesem HS-Code wird samt ihren Lieferantendaten wiederverwendet. Eine neue Version startet ohne Lieferantendaten. Die übrigen Versionen bleiben unverändert.
• Erneute Anfrage an den Lieferanten. Die Automatisierung „Auto-Einladung“ (automations.autoInviteSuppliers) lädt nach ihren eigenen Regeln ein: Ein Lieferant in einem EU-Land wird nicht eingeladen; ein Lieferant außerhalb der EU wird unabhängig von der Risikostufe seines Landes eingeladen, solange EUDR-relevante Daten fehlen; ein Lieferant ohne E-Mail-Adresse wird übersprungen (Sie erhalten eine Benachrichtigung); eine laufende Einladung, die Sie manuell zustellen, wird um die neue Version erweitert, aber nicht per E-Mail versendet. Ist die Herkunftsbestätigung pro Bestellung (automations.confirmOriginPerOrder) eingeschaltet und hat der Lieferant eine laufende Einladung, kann er zusätzlich eine Anfrage zur Herkunftsbestätigung erhalten. Diese Anfrage richtet sich nach dem Artikel, nicht nach dem HS-Code: Sie kann für die neue Version „Herkunft unverändert“ anbieten, gestützt auf eine früher beantwortete Kopie.
• Unveränderter HS-Code: Eine identische erneute Übertragung ändert nichts — keine neue Version, keine neue Anfrage.
• Widersprüchliche HS-Codes: Nennen zwei Zeilen einer Bestellung denselben Artikel mit unterschiedlichen HS-Codes — oder hat eine gleichzeitige Übertragung dieselbe Version mit einem anderen HS-Code angelegt —, schlägt die Bestellung mit conflictingHsCodeForArticle fehl.

​

Herkunft pro Bestellung per ERP

1. Kopie finden. Entnehmen Sie sie GET /api/v1/orders → lines[].article (id und supplierLinks: [{ supplierId, supplierArticleId }]). Sie können auch GET /api/v1/articles?internalArticleNr=<Nr>%23<Bestellnummer> abfragen (exakter Treffer; # als %23 kodiert); nach einem HS-Wechsel liefert das einen Artikel pro Version — nehmen Sie den, auf den die Bestellzeile zeigt.
2. Parzellen. POST /api/v1/plots mit supplierArticleIds: [<supplierArticleId>] (plots:write).
3. Nachweise. POST /api/v1/evidence/upload-url mit { fileName, contentType, fileSize } → die Bytes per PUT an uploadUrl (gleicher Content-Type, genau fileSize Bytes, sonst 403, innerhalb von 10 Minuten) → POST /api/v1/evidence als multipart/form-data mit supplierId, articleId (die ID der Kopie), uploadedS3Key (der zurückgegebene s3Key), uploadedFileName, uploadedFileSize, uploadedMimeType (evidence:write). Dieser Weg nimmt Dateien bis 10 MB an. Das Feld file statt der uploaded*-Felder nimmt höchstens 4 MB an (eine größere Datei ist ein 400). Was gespeichert ist, listet GET /api/v1/evidence?supplierArticleId=<id> (evidence:read). Dieselbe Datei an weitere Lieferantenartikel hängen: nicht erneut hochladen, sondern POST /api/v1/evidence je Ziel nur mit supplierId, articleId und reuseS3Key (der s3Key aus der ersten erfolgreichen Antwort) senden, optional mit evidenceType oder note. Jeder Aufruf legt einen eigenen Nachweis an diesem Artikel an.

​

Herkunft vom Lieferanten bestätigen lassen

curl -X POST "https://app.polygon-one.com/api/v1/orders/<orderId>/origin-confirmation" \
  -H "Authorization: Bearer eudr_8f7d2a..." \
  -H "Content-Type: application/json" \
  -d '{ "supplierArticleIds": ["<supplierArticleId>"] }'

• Auswahl: jede supplierArticleId aus lines[].article.supplierLinks dieser Bestellung — eine aktive Verknüpfung eines EUDR-relevanten Artikels der Bestellung mit ihrem Lieferanten. Die Prüfung gilt für alle oder keine: Ist eine ID ungültig, wird nichts eingereiht.
• Antwort: 202 { "status": "queued", "orderId", "supplierArticleCount" }. Die Anfrage an den Lieferanten und ihre E-Mail entstehen asynchron. Ein wiederholter Aufruf wird in die laufende Anfrage zusammengeführt und verschickt keine weitere E-Mail.
• Was der Lieferant bestätigt: die aktuellen Herkunftsdaten dieser Bestellung. Daten früherer Bestellungen werden nie übernommen, und die Urheberschaft Ihrer hochgeladenen Daten bleibt unverändert.
• Voraussetzungen: orders:write, und die Herkunftsbestätigung pro Bestellung (automations.confirmOriginPerOrder) ist für Ihren Arbeitsbereich eingeschaltet.