Einführung

Übersicht

Die Polygon One API ermöglicht Ihnen die programmatische Verwaltung Ihrer EUDR-Compliance-Daten. Sie ist für die Server-zu-Server-Integration mit Ihrem ERP-System (SAP, Oracle, Microsoft Dynamics, etc.) konzipiert. Was Sie mit der API tun können:

Artikel — Artikel erstellen, aktualisieren und abfragen. Die EUDR-Relevanz wird automatisch anhand des HS-Codes bestimmt.
Lieferanten — Lieferantendaten verwalten und Lieferanten mit Artikeln verknüpfen.
Bestellungen — Einkaufs- und Verkaufsbestellungen importieren (einzeln oder im Stapel). Bestellungen können automatisch DDS-Erklärungen zugewiesen werden.
DDS-Erklärungen — Sorgfaltspflichterklärungen für die TRACES-Einreichung erstellen und verwalten.

Authentifizierung

Alle API-Endpunkte erfordern einen Bearer-Token. Generieren Sie Ihren API-Schlüssel im Polygon One Dashboard:

Navigieren Sie zu Einstellungen > API-Schlüssel
Klicken Sie auf API-Schlüssel erstellen
Wählen Sie die erforderlichen Berechtigungen (z.B. articles:read, orders:write)
Kopieren Sie den generierten Schlüssel

Fügen Sie den Schlüssel im Authorization-Header jeder Anfrage hinzu:

Authorization: Bearer eudr_8f7d2a...

API-Schlüssel sind vertrauliche Zugangsdaten für die Server-zu-Server-Kommunikation. Speichern Sie diese in Umgebungsvariablen und geben Sie sie niemals in clientseitigem Code preis.

Basis-URL

Alle API-Anfragen werden an folgende URL gerichtet:

https://app.polygon-one.com

Berechtigungen

Jedem API-Schlüssel werden spezifische Berechtigungen zugewiesen, die den Zugriff steuern:

Berechtigung	Beschreibung
`articles:read`	Artikel lesen
`articles:write`	Artikel erstellen, aktualisieren, löschen
`suppliers:read`	Lieferanten lesen
`suppliers:write`	Lieferanten erstellen, aktualisieren, löschen
`orders:read`	Bestellungen lesen
`orders:write`	Bestellungen erstellen, aktualisieren, löschen
`dds:read`	DDS-Erklärungen lesen
`dds:write`	DDS-Erklärungen erstellen, aktualisieren, löschen

Schreibberechtigungen schließen die jeweilige Leseberechtigung ein. Ein Schlüssel mit articles:write darf also sowohl schreibende Operationen als auch GET-Anfragen für Artikel ausführen.

Antwortformat

Erfolgreiche Antworten liefern JSON-Daten direkt zurück. Listen-Endpunkte geben Arrays zurück, Einzelressourcen-Endpunkte geben Objekte zurück. Einzelne Ressource erstellen gibt HTTP 201 zurück:

{
  "article": { "id": "...", "name": "..." }
}

Stapelimporte (Array oder {"rows": [...]}) laufen asynchron und geben HTTP 202 mit einer Job-Referenz zurück:

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

Den Fortschritt und das Ergebnis (importierte, aktualisierte, übersprungene und fehlgeschlagene Zeilen) liefert GET /api/import-jobs/{jobId} — Details im Leitfaden Stapelimport (asynchron).

Fehlerbehandlung

Die API verwendet Standard-HTTP-Statuscodes:

Code	Beschreibung
`200`	OK — Anfrage erfolgreich
`201`	Erstellt — Ressource erfolgreich erstellt
`400`	Ungültige Anfrage — Ungültige Eingabedaten oder Validierungsfehler
`401`	Nicht autorisiert — Ungültiger oder fehlender API-Schlüssel
`403`	Zugriff verweigert — API-Schlüssel hat nicht die erforderlichen Berechtigungen, oder Kontoeinrichtung ist unvollständig
`404`	Nicht gefunden — Ressource existiert nicht oder gehört nicht zu Ihrem Unternehmen
`409`	Konflikt — Die Ressource kollidiert mit vorhandenen Daten (z.B. eine doppelte `internalArticleNr`) oder hat überschreibbare Warnungen ausgelöst (siehe unten)
`500`	Interner Serverfehler — Auf unserer Seite ist ein Fehler aufgetreten

Fehlerantworten enthalten ein error-Feld und optional details:

{
  "error": "Validation failed",
  "details": [{ "path": ["hsCode"], "message": "Commodity is required." }]
}

Duplikat- und Plausibilitätswarnungen

Beim Erstellen eines Artikels führt die API beratende Prüfungen durch, die statt der Erstellung ein 409 zurückgeben können:

Harter Konflikt (nicht überschreibbar): Ein Artikel mit derselben internalArticleNr existiert bereits. Die Antwort ist 409 mit einer error-Meldung.
Weiche Warnungen (überschreibbar): ein doppelter Artikelname (duplicateName), eine doppelte ean (duplicateEan) oder ein HS-Code, der nicht plausibel zur Beschreibung passt (hsMismatch). Die Antwort ist 409 mit einem maschinenlesbaren warnings-Array:

{
  "error": "Article has unresolved warnings. Resubmit with acknowledgeWarnings=true to override.",
  "warnings": [
    { "type": "duplicateName", "existingInternalArticleNr": "ART-001" },
    { "type": "duplicateEan", "existingArticleName": "Oak plank 20mm" },
    { "type": "hsMismatch" }
  ]
}

Um aus einer nicht-interaktiven Integration trotzdem fortzufahren, senden Sie die Anfrage erneut mit acknowledgeWarnings: true. Harte Konflikte werden durch dieses Flag niemals überschrieben.

API-Dokumentation

Artikel

Lieferanten

Bestellungen

Import-Jobs

DDS-Erklärungen

Übersicht

Authentifizierung

Basis-URL

Berechtigungen

Antwortformat

Fehlerbehandlung

Duplikat- und Plausibilitätswarnungen

​Übersicht

​Authentifizierung

​Basis-URL

​Berechtigungen

​Antwortformat

​Fehlerbehandlung

​Duplikat- und Plausibilitätswarnungen

Übersicht

Authentifizierung

Basis-URL

Berechtigungen

Antwortformat

Fehlerbehandlung

Duplikat- und Plausibilitätswarnungen