# API-Zugang

Neben dem automatischen Empfang über Einkaufsnetzwerke (cXML-Webhook) können Sie Bestellungen auch direkt per API an Orderport senden. Das ist nützlich, wenn Sie eigene Systeme anbinden möchten.

## API-Key erstellen

1. Klicken Sie in der Sidebar auf **API-Keys**
2. Klicken Sie auf **Neuer API-Key**
3. Vergeben Sie einen Namen (z. B. "ERP Integration" oder "Test")

Nach dem Erstellen wird der API-Key **einmalig im Klartext angezeigt**. Er hat das Format:

```
ot_live_a1b2c3d4e5f6...
```

> **Wichtig:** Kopieren und speichern Sie den Key sofort! Er wird danach nur noch als gekürzte Version angezeigt und kann nicht erneut abgerufen werden.

### API-Key widerrufen

Klicken Sie auf **Widerrufen** neben einem Key, um ihn dauerhaft zu deaktivieren. Widerrufene Keys können nicht reaktiviert werden. Erstellen Sie bei Bedarf einen neuen Key.

## Bestellung per API senden

Senden Sie Ihre Bestellung als HTTP POST an den generischen Inbound-Endpunkt:

```
POST https://orderport.app/api/v1/inbound
Authorization: Bearer ot_live_a1b2c3d4e5f6...
Content-Type: application/xml
X-Pipeline-Id: 42

<cXML>
  ...Ihr Bestelldokument...
</cXML>
```

### Header

| Header | Pflicht | Beschreibung |
|--------|---------|-------------|
| `Authorization` | Ja | `Bearer {api_key}` |
| `Content-Type` | Ja | `application/xml`, `text/xml` oder `application/json` |
| `X-Pipeline-Id` | Nein | ID der Ziel-Pipeline. Wenn nicht angegeben, erkennt Orderport die Pipeline automatisch |

### Antwort bei Erfolg

```json
{
  "message_id": 123,
  "status": "queued",
  "pipeline_id": 42
}
```

HTTP-Status: **202 Accepted**

### Duplikat erkannt

Wenn eine neue Bestellung mit derselben Bestell-ID bereits existiert:

```json
HTTP/1.1 409 Conflict

{
  "message_id": 42,
  "status": "duplicate",
  "pipeline_id": 42
}
```

### Fehlerfälle

| HTTP-Status | Bedeutung |
|-------------|-----------|
| 401 | Ungültiger oder fehlender API-Key |
| 406 | Ungültiger Content-Type (weder XML noch JSON) |
| 409 | Duplikat – Bestellung mit dieser ID wurde bereits empfangen |
| 413 | Payload zu groß (max. 5 MB) |
| 422 | Leeres Dokument oder keine passende Pipeline gefunden |

## Bestellungsstatus abfragen

Fragen Sie den Verarbeitungsstatus einer Bestellung per GET ab:

```
GET https://orderport.app/api/v1/messages/123
Authorization: Bearer ot_live_a1b2c3d4e5f6...
```

### Antwort

```json
{
  "message_id": 123,
  "status": "delivered",
  "pipeline_id": 42,
  "received_at": "2026-03-07T10:30:00Z",
  "transformed_at": "2026-03-07T10:30:01Z",
  "delivered_at": "2026-03-07T10:30:02Z",
  "transport_logs": [
    {
      "transport": "HTTP POST",
      "status": "success",
      "http_status": 200,
      "attempted_at": "2026-03-07T10:30:02Z"
    }
  ]
}
```

## Unterschied: cXML-Webhook vs. JSON-Webhook vs. API

| Eigenschaft | cXML-Webhook | JSON-Webhook | API-Inbound |
|---|---|---|---|
| URL | `/api/v1/cxml/{token}` | `/api/v1/webhook/{token}` | `/api/v1/inbound` |
| Auth | SharedSecret im XML | Bearer Token / HMAC | API-Key |
| Gedacht für | Ariba, Coupa, SAP | Shopware, Shopify, WooCommerce | Eigene Integrationen |
| Antwort | cXML (XML) | JSON | JSON |
| Pipeline | über URL-Token | über URL-Token | Per Header oder Auto-Detection |

Mehr zum JSON-Webhook-Endpunkt finden Sie im Artikel [JSON-Webhooks](/docs/json-webhook).

## Rate Limits

API-Anfragen sind auf **1.000 Anfragen pro Minute** pro API-Key begrenzt. Der Inbound-Endpunkt ist auf **100 Anfragen pro Minute** begrenzt.

Bei Überschreitung erhalten Sie HTTP-Status **429 Too Many Requests**.

## Nächste Schritte

- [Sicherheit](/docs/sicherheit) – 2FA und IP-Allowlist einrichten
- [Erste Schritte](/docs/erste-schritte) – zurück zur Übersicht