REST API
Der REST-API-Transport sendet transformierte Bestellungen als JSON an eine REST-Schnittstelle Ihrer Wahl. Im Vergleich zum HTTP POST 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.
Einrichtung
Schritte im Wizard / in der Detailansicht
- Pipeline öffnen → Transporte → Hinzufügen
- Typ: REST API
- URL eintragen (z. B.
https://api.ihr-erp.de/v2/orders) - HTTP-Methode:
POST,PUToderPATCH - Content-Type: Default
application/json; für Spryker z. B.application/vnd.api+json - Authentifizierung wählen (siehe unten)
- Optional: Custom Header hinzufügen (Key/Value-Paare)
- Optional: Erwartete Status-Codes (Default
[200, 201, 202]) - 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 6adapter_type: "spryker"– siehe 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.
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 – OAuth und HMAC im Detail
- HTTP POST – einfacher XML-Versand
- Shopware 6 / Spryker – konkrete Adapter