Empfohlene Integrationsabläufe

Die übrigen Seiten dokumentieren jeden Endpunkt und jede Regel. Diese Seite bringt sie in eine Reihenfolge: welche Aufrufe eine ERP-Anbindung macht, in welcher Abfolge, und was sie speichern sollte. Jeder Ablauf verweist auf die Seite mit den Details. Basis-URL, Schlüssel und Header wie im Schnellstart.

Ablauf	Modul	Wann
Bestell-Sync	EUDR	Ihr ERP führt Einkaufs- oder Verkaufsbestellungen und braucht die TRACES-Referenz je Bestellposition zurück
Parzellen und Geo-Analyse	EUDR	Sie haben Parzellengeometrien und wollen die Entwaldungsanalyse und den Parzellenbericht
PPWR-Mengenmeldung	PPWR	Sie melden Verpackungsmengen an LUCID oder ein anderes nationales Register

Bestell-Sync

Vom ERP zu Polygon One und die DDS-Referenzen zurück — der zentrale EUDR-Ablauf. Ihr ERP überträgt Stammdaten und Bestellungen; in Polygon One werden die Bestellungen mit DDS-Erklärungen verknüpft; Ihr ERP liest je Bestellung und Position zurück, ob die Bestellung abgedeckt ist und welche TRACES-Referenz dazugehört.

Zuerst Stammdaten: Lieferanten, dann Artikel

Senden Sie Lieferanten und Artikel als Stapel vor den Bestellungen, damit Bestellzeilen auf bereits vorhandene Artikel zeigen — hsCode und articleDescription einer Bestellzeile werden nur gelesen, wenn der Artikel noch nicht existiert (nur beim Anlegen). Lieferanten werden über externalSupplierId oder den Namen abgeglichen, Artikel über internalArticleNr. Ein Einkaufsartikel braucht einen Lieferanten (supplierId oder supplierName).

curl -X POST "https://app.polygon-one.com/api/v1/suppliers" \
  -H "Authorization: Bearer eudr_8f7d2a..." \
  -H "Content-Type: application/json" \
  -d '{ "rows": [ { "name": "Sägewerk Beispiel GmbH", "externalSupplierId": "LIEF-4711", "email": "eudr@saegewerk-beispiel.de", "country": "Germany", "address": "Waldweg 1, 79100 Freiburg" } ] }'

curl -X POST "https://app.polygon-one.com/api/v1/articles" \
  -H "Authorization: Bearer eudr_8f7d2a..." \
  -H "Content-Type: application/json" \
  -d '{ "rows": [ { "name": "Kiefernbrett 20 mm", "internalArticleNr": "ART-1001", "hsCode": "4407.11", "supplierName": "Sägewerk Beispiel GmbH" } ] }'

Beide antworten 202 mit einer jobId. Warten Sie, bis der Lieferanten-Job abgeschlossen ist, bevor Sie die Artikel senden, und bis der Artikel-Job abgeschlossen ist, bevor Sie die Bestellungen senden (Abfrage wie in Schritt 3). Jobs eines Arbeitsbereichs können gleichzeitig laufen: Eine Artikelzeile, deren supplierName noch nicht gespeichert ist, legt einen neuen Lieferanten an, der nur diesen Namen trägt.

Bestellungen als Stapel senden — alle Zeilen einer Bestellung in derselben Anfrage

Eine Zeile im Stapel ist eine Bestellzeile; Zeilen mit derselben orderNumber bilden eine Bestellung. Der Import einer Bestellung ersetzt alle ihre Zeilen, eine Anfrage, die eine Bestellung nennt, muss also alle ihre Zeilen enthalten. Hat Ihr ERP Positionsnummern, senden Sie sie als positionId an jeder Zeile der Bestellung.

curl -X POST "https://app.polygon-one.com/api/v1/orders" \
  -H "Authorization: Bearer eudr_8f7d2a..." \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      { "orderNumber": "PO-4500012345", "orderType": "purchase", "supplierName": "Sägewerk Beispiel GmbH", "articleNumber": "ART-1001", "positionId": "00010", "quantity": 1200 },
      { "orderNumber": "PO-4500012345", "orderType": "purchase", "supplierName": "Sägewerk Beispiel GmbH", "articleNumber": "ART-1001", "positionId": "00020", "quantity": 800 }
    ]
  }'

quantity ist die Nettomasse in Kilogramm. Höchstens 5.000 Zeilen pro Anfrage — teilen Sie größere Abgleiche auf mehrere Anfragen auf und halten Sie dabei die Zeilen jeder Bestellung zusammen.

Import-Job abfragen und Ergebnis speichern

curl "https://app.polygon-one.com/api/v1/import-jobs/6f7a..." \
  -H "Authorization: Bearer eudr_8f7d2a..."

Fragen Sie etwa alle 2 Sekunden ab, bei großen Jobs mit steigendem Abstand (z. B. exponentiell bis ~30 s), bis status completed oder failed ist. Speichern Sie result bei sich — der Job-Datensatz wird ~30 Tage nach Erstellung gelöscht. Fehlgeschlagene Zeilen tragen stabile Fehlerschlüssel in failed[].error.key. Ein failed-Job trägt seinen Grund in error, einem Text; bei lineReplacementRequired enthält er JSON mit den orderNumbers — eine Anfrage hätte gespeicherte Zeilen gelöscht: Senden Sie die genannten Bestellungen mit allen ihren Zeilen erneut.

Bestellungen regelmäßig per Delta abfragen

Fragen Sie mit changedSince = Beginn Ihres letzten Abrufs minus einige Minuten (ein ISO-8601-Zeitstempel mit Z oder Versatz) und limit=1000 ab. Stündlich wird empfohlen. fields beschränkt die Antwort auf das, was die Entscheidung in Schritt 5 braucht.

curl "https://app.polygon-one.com/api/v1/orders?changedSince=2026-10-05T05:55:00Z&limit=1000&fields=orderNumber,status,lines,ddsReferences" \
  -H "Authorization: Bearer eudr_8f7d2a..."

Eine volle Seite (1000 Bestellungen) heißt: Geänderte Bestellungen sind nicht mitgekommen. Blättern Sie im selben changedSince-Fenster mit offset, bis eine Seite kürzer als limit ist, und fragen Sie häufiger ab. Eine Bestellung kann doppelt erscheinen; eine, die sich während des Blätterns ändert, kommt im nächsten Delta wieder.

Je Bestellung und Position entscheiden

Entscheiden Sie auf Grundlage des aktuellen Abrufs, nie eines früheren:

Ob die ganze Bestellung abgedeckt ist: status (done, open oder notRelevant). Ein Artikel, der auf die manuelle Prüfung der EUDR-Relevanz wartet, hält die Bestellung auf open.
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).
Welche TRACES-Referenz Sie drucken: erst nach dieser Entscheidung, aus ddsReferences (referenceNumber, verificationNumber), für die Dokumente.

Geben Sie Ware nicht frei, weil ddsReferences nicht leer ist. ddsReferences gehört zur ganzen Bestellung und listet jede verknüpfte DDS-Erklärung, die nicht zurückgezogen oder abgelehnt ist — auch Entwürfe ohne referenceNumber, externe und archivierte Erklärungen. Trägt eine Bestellung mehrere Referenzen, sagt die API nicht, welche welche Position abdeckt.

status kann open sein, obwohl ddsReferences nicht leer ist (z. B. bei einem Entwurf oder einer externen DDS-Erklärung). Eine zurückgezogene oder abgelehnte DDS-Erklärung fällt aus ddsReferences heraus, und die Bestellung erscheint im nächsten Delta erneut.

Nächtlicher Voll-Sync als Auffangnetz

Gelöschte Bestellungen, Bestellungen eines gelöschten Lieferanten und entkoppelte DDS-Erklärungen erscheinen nie in einem Delta. Lesen Sie einmal pro Nacht die vollständige Liste und gleichen Sie ab; blättern Sie mit offset, bis eine Seite kürzer als limit ist. Behandeln Sie eine Bestellung, die in der vollständigen Liste fehlt, als gelöscht.

curl "https://app.polygon-one.com/api/v1/orders?limit=1000&offset=0&fields=orderNumber,status,lines,ddsReferences" \
  -H "Authorization: Bearer eudr_8f7d2a..."

Manche Statuswechsel bringen die Bestellung nicht ins Delta (z. B. wenn eine andere Bestellung ihre Menge auf derselben DDS-Erklärung erhöht oder die manuelle Prüfung eines Artikels abgeschlossen wird). Lesen Sie zum Abgleich mit ?status=open&limit=1000 neu und blättern Sie ebenso mit offset.

Was am häufigsten schiefgeht

Eine Bestellung auf mehrere Anfragen verteilen. Die zweite Anfrage würde die Zeilen der ersten löschen; die Prüfung auf ersetzte Zeilen lässt stattdessen den ganzen Job mit lineReplacementRequired fehlschlagen. Senden Sie alle Zeilen jeder Bestellung, oder "replaceLines": true, wenn eine Bestellung Zeilen verlieren soll.
positionId nur an einigen Zeilen. Alle Zeilen einer Bestellung tragen eine oder keine (positionIdMixed), und jede nur einmal pro Bestellung (duplicatePositionId). Eine ohne Positionsnummern gespeicherte Bestellung, die erstmals mit ihnen gesendet wird, braucht "replaceLines": true.
Ware auf eine Referenz freigeben. Geben Sie nur auf status oder auf lines[].article.eudrRelevant und lines[].article.needsManualCheck, beide false, im aktuellen Abruf frei — nie, weil ddsReferences nicht leer ist, und nie auf Grundlage eines früheren Abrufs.
Bei einer vollen Delta-Seite aufhören. Die Bestellungen dahinter kommen nur wieder, wenn sie sich erneut ändern; blättern Sie das Fenster mit offset durch.

Details: Bestellungen (Vollständigkeitsregel, Positionen, Status, Delta-Sync) und Stapelimport (asynchron).

Variante: Herkunft pro Bestellung aus dem ERP

Eine Bestellzeile zeigt auf eine eigene Kopie des Artikels, wenn der Artikel eine Pro-Bestellung-Vorlage ist: ein Artikel, den ein Einkaufsbestellungs-Import angelegt hat, ein mit sourceScope: "perOrder" gesendeter Artikel, oder — mit der Arbeitsbereich-Einstellung „Bestellimport legt Pro-Bestellung-Kopien an“ (standardmäßig aus, wird auf Anfrage von Polygon One eingeschaltet) — ein vorhandener Artikel, den eine Zeile einer Einkaufsbestellung nennt. Ihr ERP kann dieser Kopie Parzellen und Dokumente direkt zuordnen, ohne Lieferantenportal: Kopie finden, Parzellen mit ihrer supplierArticleId anlegen, Nachweise hochladen. Dafür braucht der Schlüssel plots:write und evidence:write; die Schlüssel-Vorlage ERP-Anbindung enthält beide (einem damit vor dem 1. Oktober 2026 angelegten Schlüssel fehlen sie — prüfen Sie seine Berechtigungen). Schritte und Antworten: Herkunft pro Bestellung per ERP. Sind alle aktuellen Parzellen hochgeladen, rufen Sie POST /api/v1/orders/{id}/origin-confirmation mit den ausgewählten supplierArticleIds der Bestellzeilen auf; der Lieferant bestätigt dann die aktuellen Herkunftsdaten dieser Bestellung. Daten früherer Bestellungen werden nie übernommen, die Urheberschaft des Käufers bleibt unverändert. Details: Herkunft vom Lieferanten bestätigen lassen.

Parzellen und Geo-Analyse

Parzellengeometrie senden, Entwaldungsanalyse abwarten, Ergebnis lesen, Bericht herunterladen. Ein Artikel oder Lieferant ist nicht nötig — eine Parzelle mit Rohstoffgruppe genügt.

Optional: Geometrie prüfen

Ein Probelauf mit demselben Body wie beim Anlegen — schreibt nichts, antwortet mit valid und den Codes, die das Anlegen liefern würde. commodityGroup ist hier optional; senden Sie aber "wood", verlangt auch der Probelauf eine wissenschaftliche Holzart, wie beim Anlegen. Ihr Parzellen-Limit prüft er nicht.

curl -X POST "https://app.polygon-one.com/api/v1/plots/validate" \
  -H "Authorization: Bearer eudr_8f7d2a..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "LIEF-4711-P03", "country": "BR", "commodityGroup": "wood", "species": [{ "commonName": "Eucalyptus", "scientificName": "Eucalyptus grandis" }], "geojson": { "type": "Polygon", "coordinates": [[[-47.060123, -21.180245], [-47.058531, -21.180245], [-47.058531, -21.181934], [-47.060123, -21.181934], [-47.060123, -21.180245]]] } }'

Parzelle anlegen

curl -X POST "https://app.polygon-one.com/api/v1/plots" \
  -H "Authorization: Bearer eudr_8f7d2a..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "LIEF-4711-P03", "country": "BR", "commodityGroup": "wood", "species": [{ "commonName": "Eucalyptus", "scientificName": "Eucalyptus grandis" }], "geojson": { "type": "Polygon", "coordinates": [[[-47.060123, -21.180245], [-47.058531, -21.180245], [-47.058531, -21.181934], [-47.060123, -21.181934], [-47.060123, -21.180245]]] } }'

201 mit der Parzelle unter created. Übernehmen Sie created.id. 409 mit code: "PLOT_LIMIT_REACHED" heißt: Ihr Parzellen-Limit oder Monatskontingent ist erreicht; nichts wird angelegt, und eine Wiederholung hilft nicht.

Analysestatus abfragen

Alle 15 bis 30 Sekunden, solange analysisStatus pending oder in_progress ist:

curl "https://app.polygon-one.com/api/v1/plots/5b0c…?fields=analysisStatus,analysis" \
  -H "Authorization: Bearer eudr_8f7d2a..."

Bericht einmal herunterladen

curl "https://app.polygon-one.com/api/v1/plots/5b0c…/report" \
  -H "Authorization: Bearer eudr_8f7d2a..." \
  -o LIEF-4711-P03.pdf

Was am häufigsten schiefgeht

Eine FeatureCollection senden. Eine Anfrage legt eine Parzelle an — senden Sie jedes Feature einzeln.
Den Bericht statt des Status abfragen. Jeder Berichtsaufruf erzeugt das PDF neu; laden Sie es einmal herunter, sobald das Ergebnis vorliegt.
Keine Parzellenreferenz in name. Gleicher name, gleiches country, gleiche Geometrie und gleiche supplierArticleIds werden wiedererkannt ("deduplicated": true) — das macht eine Wiederholung gefahrlos.
Kein country. Ohne Land greift das Überspringen für Länder mit geringem Risiko nie, und die Parzelle wird immer analysiert.

Details: Geo-Analyse (Status, Idempotenz, Fehlercodes, Rezept).

PPWR-Mengenmeldung

Eine Kurzfassung des Integrationsrezepts ERP zu LUCID. Schritte 1–3 sind einmalige Stammdaten, Schritte 4–6 der wiederkehrende Job. Die Stammdaten-Endpunkte antworten synchron (200); der Mengen-Feed ist ein Import-Job. Die Artikel (SKUs) müssen in Polygon One schon existieren: Legen Sie fehlende mit POST /api/v1/articles an (articles:write). Eine unbekannte Artikelnummer ist in article-links und im Mengen-Job eine Fehlerzeile.

Komponenten mit Material und Masse

curl -X POST "https://app.polygon-one.com/api/v1/ppwr/components" \
  -H "Authorization: Bearer eudr_8f7d2a..." \
  -H "Content-Type: application/json" \
  -d '{ "rows": [ { "code": "K-1", "name": "Faltschachtel", "materials": ["paper_board"], "massGrams": "12" } ] }'

Verpackungseinheiten — immer mit internalRef

Eine Einheiten-Zeile ohne internalRef legt immer eine neue Einheit an. notes ist Pflicht.

curl -X POST "https://app.polygon-one.com/api/v1/ppwr/units" \
  -H "Authorization: Bearer eudr_8f7d2a..." \
  -H "Content-Type: application/json" \
  -d '{ "rows": [ { "name": "Faltschachtel Teefilter", "internalRef": "U-1", "packagingType": "sales", "role": "manufacturer", "notes": "Faltschachtel für Teefilter" } ] }'

Stückliste und SKU-Verknüpfungen

Verknüpfen Sie Komponenten mit Einheiten über POST /api/v1/ppwr/links und Artikel (SKUs) mit Einheiten über POST /api/v1/ppwr/article-links, das eine unbekannte Artikelnummer als Fehlerzeile meldet.

curl -X POST "https://app.polygon-one.com/api/v1/ppwr/links" \
  -H "Authorization: Bearer eudr_8f7d2a..." \
  -H "Content-Type: application/json" \
  -d '{ "rows": [ { "specInternalRef": "U-1", "componentCode": "K-1", "quantity": 1 } ] }'

Wiederkehrend: Mengen je SKU, Markt und Jahr senden

curl -X POST "https://app.polygon-one.com/api/v1/ppwr/quantities" \
  -H "Authorization: Bearer eudr_8f7d2a..." \
  -H "Content-Type: application/json" \
  -d '{ "rows": [ { "articleNumber": "SKU-1", "periodYear": 2026, "market": "DE", "quantity": 125000 } ], "replaceScope": "period-market" }'

202 mit einer jobId — fragen Sie GET /api/v1/import-jobs/{jobId} ab wie beim Bestell-Sync. Die quantity jeder Zeile ist die Gesamtmenge für diese SKU, dieses Jahr und diesen Markt und ersetzt den gespeicherten Wert — senden Sie nie Zuwächse, Retouren oder Gutschriften als eigene Zeilen, sondern verrechnen Sie sie in der Gesamtmenge. Senden Sie replaceScope: "period-market", wenn der Stapel die vollständige Liste für jedes genannte Jahr und jeden genannten Markt ist; lassen Sie das Feld weg, wenn der Stapel nur die geänderten SKUs enthält.

Bericht erzeugen

curl -X POST "https://app.polygon-one.com/api/v1/ppwr/mengenmeldung/reports" \
  -H "Authorization: Bearer eudr_8f7d2a..." \
  -H "Content-Type: application/json" \
  -d '{ "periodYear": 2026, "market": "DE", "format": "lucid_de", "reportType": "HJM1", "systemOperatorId": "DE1234567890123" }'

Ein 422 nennt Ihnen Punkt für Punkt, welche Daten noch nicht meldefähig sind — korrigieren, erneut senden, erneut erzeugen.

Datei abholen und bei LUCID hochladen

Listen Sie den aktuellen Bericht und laden Sie ihn mit GET /api/v1/ppwr/mengenmeldung/{id}/xml herunter:

curl "https://app.polygon-one.com/api/v1/ppwr/mengenmeldung/reports?periodYear=2026&market=DE&status=generated" \
  -H "Authorization: Bearer eudr_8f7d2a..."

Das Hochladen der XML bei LUCID ist der eine Schritt, der sich nicht automatisieren lässt.

Was am häufigsten schiefgeht

Einheiten-Zeilen ohne internalRef. Jede Wiederholung legt eine weitere Einheit an.
SKUs über articleNumbers der Einheiten-Zeile verknüpfen. Eine unbekannte Artikelnummer wird dort übersprungen; die Antwort zählt solche Nummern nur (articleNumbersUnmatched) und nennt sie nicht. POST /api/v1/ppwr/article-links meldet jede als Fehlerzeile.
Einen gespeicherten Wert ohne overwrite: true überschreiben. Der ganze Stapel wird mit 409 overwriteRequired abgelehnt, nichts wird geschrieben.
Erwarten, dass der Feed einen von Hand eingetragenen Wert ersetzt. Das tut er nie; betroffene Einheiten kommen in conflicts zurück.

Um ausgestellte Konformitätserklärungen in Ihren Artikelstamm zurückzuschreiben, siehe das ERP-Rezept unter Konformitätserklärungen lesen.

Vor dem Go-live

Schlüsselberechtigungen je Ablauf. Bestell-Sync: suppliers:write, articles:write, orders:write (Stapelimport); Herkunft pro Bestellung zusätzlich plots:write und evidence:write; Parzellen: plots:write (Geo-Analyse); PPWR: packaging:write, dazu articles:write, wenn Sie die SKUs über die API anlegen (PPWR). Schreibrechte schließen Leserechte ein. Die Schlüssel-Vorlage ERP-Anbindung enthält all diese (einem damit vor dem 1. Oktober 2026 angelegten Schlüssel fehlen plots:write und evidence:write).
Module und Exporte. Ein Schlüssel handelt als ein Benutzer. Die PPWR-Endpunkte brauchen das PPWR-Modul für diesen Benutzer. Der Parzellenbericht braucht das EUDR-Modul für diesen Benutzer und aktivierte Exporte für Ihren Arbeitsbereich (sonst 403).
Das Rate-Limit gilt je IP. 1000 Anfragen pro 60 Sekunden je Client-IP, über alle /api-Pfade und einschließlich der Nutzer der Web-App aus demselben Netz. Verteilen Sie geplante Jobs zeitlich und nutzen Sie die Stapel-Endpunkte (Rate-Limit).
Nur wiederholen, was gefahrlos wiederholbar ist. 429 mit JSON und 5xx mit exponentiellem Backoff und Jitter; Stapelimporte sind gefahrlos wiederholbar. Ein wiederholter POST mit einem einzelnen Lieferanten antwortet 409 (gleicher Name oder gleiche externalSupplierId). Ein wiederholter POST mit einer einzelnen Bestellung antwortet 409, ebenso das Umbenennen einer Bestellung auf eine bereits vorhandene Bestellnummer — suchen Sie die Bestellung zuerst, oder senden Sie Bestellungen als Stapel mit einer Zeile (Wiederholungen).
Es gibt keine Sandbox. Jeder Aufruf wirkt auf Ihren Live-Arbeitsbereich (Nicht in v1).
Protokollieren Sie x-vercel-id bei jedem fehlgeschlagenen Aufruf — der Support braucht den Wert (Anfrage-Referenz).
Unbekannte Antwortfelder ignorieren. v1 ergänzt mit der Zeit Felder (Versionierung).

API-Dokumentation

Artikel

Lieferanten

Parzellen

Nachweise

Bestellungen

Import-Jobs

DDS-Erklärungen

PPWR – Verpackungsdaten

PPWR – Dokumente

PPWR – Konformitätserklärungen

PPWR – Mengen & Mengenmeldung

Bestell-Sync

Variante: Herkunft pro Bestellung aus dem ERP

Parzellen und Geo-Analyse

PPWR-Mengenmeldung

Vor dem Go-live

​Bestell-Sync

​Variante: Herkunft pro Bestellung aus dem ERP

​Parzellen und Geo-Analyse

​PPWR-Mengenmeldung

​Vor dem Go-live

Bestell-Sync

Variante: Herkunft pro Bestellung aus dem ERP

Parzellen und Geo-Analyse

PPWR-Mengenmeldung

Vor dem Go-live