# REST API

Der REST-API-Transport sendet transformierte Bestellungen als JSON an eine REST-Schnittstelle Ihrer Wahl. Im Vergleich zum [HTTP POST](/docs/http) bietet er feingranulare Steuerung: konfigurierbare HTTP-Methode, eigenes Content-Type, Custom Header, diverse Auth-Mechanismen und Adapter für spezifische Zielsysteme (z. B. Shopware 6, Spryker).

## Wann REST API wählen?

- Ihr Zielsystem erwartet **JSON** statt XML
- Es verlangt **OAuth-Authentifizierung** oder Custom-Header
- Sie wollen **PUT/PATCH** statt POST einsetzen (z. B. für idempotente Upserts)
- Sie brauchen einen **Integrations-Adapter** (Shopware 6, Spryker) – der technisch als REST-API-Transport läuft

Für reinen XML-Versand ohne weitere Anforderungen reicht der einfachere [HTTP POST](/docs/http).

## Einrichtung

### Schritte im Wizard / in der Detailansicht

1. Pipeline öffnen → **Transporte → Hinzufügen**
2. Typ: **REST API**
3. **URL** eintragen (z. B. `https://api.ihr-erp.de/v2/orders`)
4. **HTTP-Methode**: `POST`, `PUT` oder `PATCH`
5. **Content-Type**: Default `application/json`; für Spryker z. B. `application/vnd.api+json`
6. **Authentifizierung** wählen (siehe unten)
7. Optional: **Custom Header** hinzufügen (Key/Value-Paare)
8. Optional: **Erwartete Status-Codes** (Default `[200, 201, 202]`)
9. Speichern → **Verbindung testen**

### Auth-Typen

| Typ | Wie wird gesendet? | Einsatzbereich |
|---|---|---|
| **Keine** | – | Interne APIs mit IP-Allowlist |
| **Basic Auth** | `Authorization: Basic base64(user:pass)` | Einfache Legacy-APIs |
| **Bearer Token** | `Authorization: Bearer {token}` | Moderne APIs, interne Tokens |
| **API-Key-Header** | Custom Header (z. B. `X-API-Key: {key}`) | Plattformen mit spezifischem Header-Design |
| **OAuth Client Credentials** | Automatisch Token holen, dann `Bearer {access_token}` | Shopware 6 Admin API |
| **OAuth Password Grant** | Automatisch Token mit Benutzerkonto holen | Spryker Glue API |

### Timeouts

Standardmäßig:

- **Connect-Timeout**: 10 s
- **Gesamt-Timeout**: 30 s

Beide Werte sind in der Transport-Config (`timeout`, `connect_timeout`) überschreibbar – nützlich für langsamere Backends.

### Adapter

Bei Integrations-Zielen (Shopware 6, Spryker) wird zusätzlich ein Adapter gesetzt:

- `adapter_type: "shopware6"` – [siehe Shopware 6](/docs/shopware6)
- `adapter_type: "spryker"` – [siehe Spryker](/docs/spryker)

Der Adapter transformiert das generische JSON in das zielsystem-spezifische Schema, bevor der HTTP-Call abgesetzt wird.

## Technische Details

### Custom Header

Eigene Header (z. B. `X-API-Key`, `X-Tenant`) können pro Transport als Key-Value-Paare hinterlegt werden. Sie werden zusätzlich zu den automatisch gesetzten Auth- und Content-Type-Headern gesendet.

### OAuth-Token-Handling

Bei OAuth-Auth holt sich Orderport beim ersten Zustellversuch automatisch einen Access Token und hält ihn im Speicher, bis er abläuft. Läuft er ab, wird transparent ein neuer geholt. Scheitert der Token-Endpoint, greift die normale [Retry-Strategie](/docs/fehlerbehebung).

### Erwartete Status-Codes

Default: `[200, 201, 202]`. Manche APIs antworten mit `204 No Content` bei Erfolg – dann `expected_status` anpassen. Liegt der tatsächliche Status nicht in der Liste, gilt der Versuch als fehlgeschlagen.

### Response-Handling

- Bis zu 5 000 Zeichen der Antwort werden im Transport-Log gespeichert
- Antwort-Header werden aktuell nicht persistiert (Antwort-Zeit schon)
- Fehlermeldungen landen bei 4xx/5xx im `error_message`-Feld

## Fehlerbehebung

| Symptom | Ursache | Lösung |
|---|---|---|
| 401 / 403 unmittelbar | Falsche Credentials oder expired Token | Verbindungstest; bei OAuth Client-ID/Secret neu eintragen |
| 400 „Bad Request" | Ziel erwartet anderes Content-Type oder Feld-Schema | `content_type` anpassen; Mapping-Regeln ggf. auf Ziel-Schema ausrichten |
| 413 Payload Too Large | Ziel hat niedrigeres Limit als 5 MB | Mit Ziel-Admin abstimmen; Bestellung splitten ist nicht in Scope |
| Timeout bei OAuth-Token | Token-Endpoint langsam | `connect_timeout` erhöhen |
| Antwort kommt als HTML statt JSON | Falsche URL (Login-Redirect) | URL prüfen, Auth-Header setzen |

## Nächste Schritte

- [Zugangsdaten](/docs/credentials) – OAuth und HMAC im Detail
- [HTTP POST](/docs/http) – einfacher XML-Versand
- [Shopware 6](/docs/shopware6) / [Spryker](/docs/spryker) – konkrete Adapter