Schnellstart

Diese Seite führt Sie in fünf Schritten zu einer funktionierenden Integration. Sie benötigen curl (oder einen anderen HTTP-Client) und Zugriff auf Einstellungen > API-Schlüssel in Polygon One.

Es gibt keine Sandbox. Jeder Aufruf wirkt auf Ihren Live-Arbeitsbereich. Die Datensätze, die Sie unten anlegen, sind echt — löschen Sie sie anschließend in der App, oder verwenden Sie Testnamen, die Sie wiedererkennen.

Lieber mit Postman oder Insomnia? Importieren Sie die OpenAPI-3.1-Spezifikation von https://help.polygon-one.com/api-reference/openapi.json. Dieselbe Datei funktioniert mit OpenAPI-Client-Generatoren.

1. API-Schlüssel anlegen

Öffnen Sie Einstellungen > API-Schlüssel und klicken Sie auf API-Schlüssel erstellen.
Für diesen Schnellstart vergeben Sie articles:write und suppliers:write. Schreibberechtigungen schließen die Leseberechtigung ein.
Kopieren Sie den Schlüssel. Er beginnt mit eudr_ — das hat historische Gründe; derselbe Schlüssel funktioniert für EUDR und PPWR, sofern er die Berechtigungen hat und der Benutzer, für den er handelt, das Modul aktiviert hat.

Speichern Sie den Schlüssel in einer Umgebungsvariable oder einem Secret Store, nie in clientseitigem Code. Details: Authentifizierung.

2. Erster Aufruf

Einen Artikel lesen:

curl "https://app.polygon-one.com/api/v1/articles?limit=1" \
  -H "Authorization: Bearer eudr_8f7d2a..."

Erfolg: 200 mit einem JSON-Array. In einem neuen Arbeitsbereich ist das Array leer ([]). Die zwei häufigsten Fehler beim ersten Aufruf:

Was Sie sehen	Ursache	Lösung
`401` mit `{"error":"Invalid or expired API key"}`	Der Schlüssel ist falsch, widerrufen oder abgelaufen	Schlüssel erneut kopieren oder einen neuen anlegen
`429` mit einer HTML-Seite	Der `Authorization`-Header fehlt oder ist fehlerhaft. Anfragen ohne gültigen `Bearer`-Header hält der Bot-Schutz auf, bevor sie die API erreichen	`Authorization: Bearer <Schlüssel>` senden — der Wert muss mit `Bearer` beginnen

Mehr zu Statuscodes: Fehler & Limits.

3. Lieferant und Artikel anlegen

Ein POST mit einem Objekt legt einen Datensatz an und antwortet synchron mit 201. Lieferant — name, email, country und address sind Pflicht. country ist der englische Ländername (z. B. Germany, nicht DE); address braucht street, postalCode und city:

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

Die Antwort ist 201 mit { "supplier": { "id": "…", … } }. Merken Sie sich supplier.id. Artikel — name, internalArticleNr und hsCode sind Pflicht. Ein Einkaufsartikel (der Standard) braucht zusätzlich einen Lieferanten, über supplierId oder supplierName:

curl -X POST "https://app.polygon-one.com/api/v1/articles" \
  -H "Authorization: Bearer eudr_8f7d2a..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kiefernbrett 20 mm",
    "internalArticleNr": "ART-1001",
    "hsCode": "4407.11",
    "supplierId": "<SUPPLIER_ID>"
  }'

Die Antwort ist 201 mit { "article": { "id": "…", … } }. Die EUDR-Relevanz wird aus dem HS-Code bestimmt. Dieselbe internalArticleNr ein zweites Mal ergibt 409 — der Artikel existiert bereits. Ein 409 mit einem warnings-Array bedeutet ein mögliches Duplikat (gleicher Name oder gleiche EAN); siehe Duplikatwarnungen.

4. Stapel senden und Job abfragen

Ein Array (oder {"rows": [...]}) ist ein Stapel. Er läuft asynchron: Die API antwortet mit 202 und einer jobId, importiert ist noch nichts.

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 25 mm", "internalArticleNr": "ART-1002", "hsCode": "4407.11", "supplierName": "Sägewerk Beispiel GmbH" },
      { "name": "Kiefernbrett 30 mm", "internalArticleNr": "ART-1003", "hsCode": "4407.11", "supplierName": "Sägewerk Beispiel GmbH" }
    ]
  }'

{ "jobId": "6f7a...", "status": "queued", "statusUrl": "/api/import-jobs/6f7a..." }

Fragen Sie den Job etwa alle 2 Sekunden ab, bis status completed oder failed ist:

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

{
  "jobId": "6f7a...",
  "kind": "articles",
  "source": "erp",
  "runId": null,
  "status": "completed",
  "progress": { "total": 2, "processed": 2, "failed": 0 },
  "result": { "…": "…" },
  "error": null,
  "createdAt": "2026-10-05T08:00:00.000Z",
  "finishedAt": "2026-10-05T08:00:03.000Z"
}

result listet importierte, aktualisierte, übersprungene und fehlgeschlagene Zeilen. Denselben Stapel erneut zu senden ist gefahrlos: vorhandene Zeilen kommen als übersprungen oder aktualisiert zurück, es entstehen keine Duplikate. Details: Stapelimport (asynchron).

5. Nächste Schritte

Empfohlene Integrationsabläufe

Bestell-Sync, Parzellen und PPWR als vollständige Abläufe — welcher Aufruf wann.

Stapelimport (asynchron)

Artikel, Lieferanten und Bestellungen im Stapel, Job-Ergebnisse, Fehlerschlüssel, Delta-Sync.

PPWR

Verpackungsstammdaten, Mengen und Mengenmeldung.

Geo-Analyse

Parzellengeometrie senden, Entwaldungsanalyse lesen, Bericht herunterladen.

Fehler & Limits

Statuscodes, Rate-Limit, Wiederholungen, Größenlimits.

API-Dokumentation

Artikel

Lieferanten

Parzellen

Nachweise

Bestellungen

Import-Jobs

DDS-Erklärungen

PPWR – Verpackungsdaten

PPWR – Dokumente

PPWR – Konformitätserklärungen

PPWR – Mengen & Mengenmeldung

1. API-Schlüssel anlegen

2. Erster Aufruf

3. Lieferant und Artikel anlegen

4. Stapel senden und Job abfragen

5. Nächste Schritte

Empfohlene Integrationsabläufe

Stapelimport (asynchron)

PPWR

Geo-Analyse

Fehler & Limits

​1. API-Schlüssel anlegen

​2. Erster Aufruf

​3. Lieferant und Artikel anlegen

​4. Stapel senden und Job abfragen

​5. Nächste Schritte

Empfohlene Integrationsabläufe

Stapelimport (asynchron)

PPWR

Geo-Analyse

Fehler & Limits

1. API-Schlüssel anlegen

2. Erster Aufruf

3. Lieferant und Artikel anlegen

4. Stapel senden und Job abfragen

5. Nächste Schritte