Handbuch
Rücksendungen auch ohne Storefront: Store API und Admin-API.
Für Headless-Shops und Apps gibt es Routen der Store API: Anmeldung zur Bestellung, Anlegen, Rücksendeschein und Labels, mit denselben Bedingungen wie im Shop. Für Warenwirtschaft und eigene Abläufe gibt es Routen der Admin-API und die Entitäten des Plugins, alle mit dem Recht „Rücksendungen nutzen (Vollzugriff)“.
Store API
Welche Routen hat die Store API?
Alle Routen der Store API sind POST und liegen unter /store-api/dvsn/return-shipment/. Bis auf die Anmeldung zur Bestellung brauchen sie einen angemeldeten Kunden im Kontext-Token oder den Zugang, den die Anmeldung zur Bestellung öffnet.
| Route | wofür | Felder | Antwort |
|---|---|---|---|
order-login | Anmeldung zur Bestellung ohne Kundenkonto | orderNumber, emailOrZipcode | 200 mit orderId; 404; 429 mit Retry-After |
create | Rücksendung anlegen | orderId, comment, lineItems, freiwillig carrier | id und number; 400 return_shipment_invalid |
document | Rücksendeschein | id | PDF als base64; 404; 403 approval_pending |
label | Label oder QR-Code eines Dienstleisters | id, carrier, kind (label, qr_code) | Datei als base64 |
dhl-label | DHL-Label | id | Datei als base64 |
dhl-qr-code | QR-Code von DHL | id | Datei als base64 |
ups-label | UPS-Label | id | Datei als base64 |
Dateien kommen als JSON mit content (base64), contentType, fileName und fileExtension.
Wie kommt ein Kunde ohne Konto an seine Bestellung?
Wie im Shop meldet sich ein Kunde ohne Kundenkonto mit Bestellnummer und E-Mail-Adresse oder PLZ an. Die Route prüft dasselbe wie die Seite im Shop und bremst ebenso zu viele Versuche. Danach gilt der Zugang zur Bestellung für das Kontext-Token dieser Anfrage, und die übrigen Routen arbeiten mit der orderId.
POST /store-api/dvsn/return-shipment/order-loginmit{"orderNumber": "11099", "emailOrZipcode": "24103"}- Antwort 200 mit der
orderId; 404, wenn Bestellnummer und Angabe nicht zusammenpassen. - Antwort 429 nach zu vielen Versuchen, mit der Kopfzeile
Retry-After: so viele Sekunden bis zum nächsten Versuch.
Wie legt eine App eine Rücksendung an, und warum lehnt die Route ab?
Die Route create prüft dasselbe wie das Formular im Shop: Bedingungen an Bestellung und Produkten, Frist, Gründe und Vorgehensweisen des Verkaufskanals, Kommentarpflicht und Stückzahl. Je Position kommen id (die Position der Bestellung), quantity, reasonId, procedureId und comment mit; carrier ist dhl, ups oder self. Was gilt: Fotos, Dateien und die Checkliste gehören zum Formular des Shops, ein Grund mit Pflicht-Dateien lehnt über die Store API darum ab.
Code in violations | bedeutet |
|---|---|
order_not_found | die Bestellung gibt es nicht, oder sie gehört einem anderen Kunden oder Verkaufskanal |
order_not_returnable | eine Bedingung der Bestellung oder die Frist lässt keine Rücksendung zu; detail nennt den Grund |
nothing_selected | keine Position hat ein Stück |
position_unknown, position_twice | eine Position, die der Kunde nicht zurückgeben kann, oder dieselbe Position zweimal |
quantity_invalid, quantity_too_high | keine ganze Zahl ab 1, oder mehr Stück als offen |
reason_missing, reason_unknown | Grund fehlt oder gilt nicht in diesem Verkaufskanal |
procedure_missing, procedure_unknown | Vorgehensweise fehlt oder gilt nicht |
comment_missing | der Grund verlangt einen Kommentar |
files_missing | der Grund verlangt ein Foto oder eine Datei |
carrier_unavailable | ein Dienstleister, der nicht angeboten wird, bei DHL und UPS auch unter dem Mindestwarenwert; detail nennt ihn dann |
Eine Ablehnung kommt mit Status 400 und dem Code return_shipment_invalid; meta.parameters.violations nennt je Verstoß code, lineItemId und detail.
Eine Rücksendung über die Store API löst dieselben Flows aus wie eine aus dem Shop, also die E-Mails „Rücksendung angelegt“ an Kunde und Team. Wartet sie auf die Freigabe, liefert document bis dahin 403 approval_pending.
Wie holt eine App Rücksendeschein und Label?
Die Routen der Labels liefern das neueste Label der Rücksendung oder erstellen das erste, mit der E-Mail „Rücksendelabel“; ein weiteres Label erstellen sie nicht. Es gelten dieselben Regeln wie auf der Seite der Rücksendung, auch die Bezahlung eines kostenpflichtigen Labels.
| Antwort | bedeutet |
|---|---|
| 200 | die Datei als base64 |
| 404 | Rücksendung unbekannt oder nicht die des Kunden |
| 400 | eine Anfrage, die nicht passt, etwa ein QR-Code bei UPS |
| 403 | eine Regel des Labels passt nicht, oder die Rücksendung wartet auf die Freigabe (approval_pending) |
| 409 | eine Grenze ist erreicht, oder ein Label entsteht gerade |
| 502 | der Dienstleister lehnt ab; seine Meldung steht nur mit „Fehlermeldung des Dienstleisters zeigen“ in der Antwort |
Admin-API
Was kann eine Warenwirtschaft über die Admin-API tun?
Die Routen der Admin-API liegen unter /api/dvsn-return-shipment/; jede verlangt das Recht des Plugins. Dazu kommen die üblichen Endpunkte von Shopware für die Entitäten des Plugins, etwa dvsn_return_shipment, dvsn_return_shipment_reason oder dvsn_return_shipment_dhl, ebenfalls nur mit dem Recht.
| Bereich | Routen |
|---|---|
| Anlegen | create, create/prepare/{orderId}, create/search |
| Status und Freigabe | status/change, status/usage, approval/approve, approval/label-option, order-delivery/suggestion/{id}, order-delivery/apply |
| Prüfen | goods-receipt/check, goods-receipt/suggestion, goods-receipt/reopen |
| Ausgleich | refund/prepare/{id}, refund/calculate, refund/save, refund/document/{refundId}, replacement/prepare/{id}, replacement/create, b-stock/create |
| Kommunikation | message/send, attachment/{attachmentId} |
| Dokumente und Labels | document/{returnShipmentId}, label/check/{id}, label/create, label/send-mail, label/file/{fileId} |
| Zugangsdaten prüfen | dhl-api-validator/validate, ups-api-validator/validate, ups-api-validator/validate-oauth-token |
| Auswertung | dashboard/{part}, statistics/{tab}, export/rows, return-rate/product/{id}, return-rate/product/{id}/comments, return-rate/customer/{id}, return-rate/shop |
| Produkthinweise | product-hint/suggestion, product-hint/product/{id}, product-hint/product/{id}/comments, product-hint/reject, product-hint/create |
Was dabei gilt:
- Ein Statuswechsel über die Admin-API steht im Verlauf der Rücksendung und löst den Flow „Status geändert“ aus. Ob der Kunde eine E-Mail bekommt, entscheidet dann der Schalter „E-Mail an den Kunden senden“ am Status.
- Ein Status, den eine Rücksendung nutzt, lässt sich auch über die API nicht löschen; die Antwort nennt
DVSN_RETURN_SHIPMENT_STATUS_IN_USE. - Eine Integration, die mit der Kopfzeile
sw-skip-trigger-flowschreibt, löst keinen Flow aus und damit keine E-Mail.
So richtest du den Zugang für eine Warenwirtschaft ein
Eine Warenwirtschaft greift über eine Integration von Shopware zu. Eine Integration mit Administratorrechten darf alles; ohne sie braucht sie eine Rolle mit dem Recht Rücksendungen nutzen (Vollzugriff). Das Recht enthält alle Entitäten des Plugins und die Leserechte am Kern, die die Rücksendungen brauchen.
- 1
Lege unter Einstellungen › System › Benutzer & Rechte eine Rolle an, etwa „Warenwirtschaft“, und schalte in der Karte Zusätzliche Berechtigungen das Recht Rücksendungen nutzen (Vollzugriff) ein.
- 2
Öffne Einstellungen › System › Integrationen und klicke auf Integration anlegen. Gib einen Namen ein.
- 3
Lass Administrator aus und wähle unter Rollen die Rolle mit dem Recht.
- 4
Kopiere Zugangs-ID und Sicherheitsschlüssel in die Warenwirtschaft und klicke auf Integration speichern.
Mit Zugangs-ID und Schlüssel holt die Warenwirtschaft ein Token über die OAuth-Route von Shopware und ruft damit die Routen auf.
Häufige Fragen
Kann eine App Rücksendungen ohne Storefront anlegen?
Ja, über die Store API mit der Route create. Sie prüft dieselben Bedingungen wie das Formular im Shop und löst dieselben E-Mails aus.
Braucht der Kunde dafür ein Kundenkonto?
Nein. Die Route order-login öffnet die Bestellung mit Bestellnummer und E-Mail-Adresse oder PLZ für das Kontext-Token; danach arbeiten die übrigen Routen mit der Bestellung.
Gelten Frist und Bedingungen auch über die Store API?
Ja. Bedingungen an Bestellung und Produkten, Frist, Gründe und Vorgehensweisen des Verkaufskanals werden genauso geprüft; eine Ablehnung nennt den Code je Verstoß.
Kann die Store API Fotos zur Rücksendung hochladen?
Nein, Fotos, Dateien und die Checkliste gehören zum Formular des Shops. Ein Grund, der Fotos verlangt, lehnt über die Store API mit files_missing ab.
Wie lädt eine App das Label über die Store API?
Mit der Route label und den Feldern id, carrier und kind, oder mit dhl-label, dhl-qr-code und ups-label. Sie liefern das neueste Label oder erstellen das erste, als Datei in base64.
Welches Recht braucht eine Warenwirtschaft für die Admin-API?
Eine Integration mit Administratorrechten oder mit einer Rolle, die „Rücksendungen nutzen (Vollzugriff)“ hat. Jede Route und jede Entität des Plugins verlangt dieses Recht.
Schickt ein Statuswechsel über die Admin-API eine E-Mail?
Er löst den Flow „Status geändert“ aus. Der Kunde bekommt die E-Mail, wenn der neue Status „E-Mail an den Kunden senden“ an hat und der Flow aktiv ist.
Weitere Kapitel