> ## Documentation Index
> Fetch the complete documentation index at: https://help.polygon-one.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Einführung

> Integrieren Sie Ihr ERP-System mit der Polygon One EUDR-Compliance-Plattform

## Ü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:

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

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

```bash theme={null}
Authorization: Bearer eudr_8f7d2a...
```

<Warning>
  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.
</Warning>

## 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:

```json theme={null}
{
  "article": { "id": "...", "name": "..." }
}
```

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

```json theme={null}
{
  "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)](/api-reference/batch-import).

## 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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.