Store-API des Warenkorb Uploads pro Bestellung – Headless & PWA (Shopware 6)

Hinweis: Verfügbar ab Version 2.3.0

Wenn Sie Ihren Shop nicht mit der Shopware-Storefront betreiben, sondern mit einem eigenen Frontend – etwa einer PWA, einem Next.js- oder Nuxt-Projekt – lässt sich die komplette Upload-Strecke über die Store-API abbilden.

Alle Endpunkte erwarten den sw-access-key-Header Ihres Verkaufskanals und den sw-context-token des Kunden.

Übersicht der Endpunkte

Hinweis: Die Pfade unterscheiden sich bewusst vom Schwester-Plugin Warenkorb Upload pro Artikel, das item-upload verwendet. So können beide Plugins parallel installiert sein, ohne dass sich die Routen ins Gehege kommen.

Wie der Upload abläuft

Der Upload nutzt das tus-Protokoll für wiederaufnehmbare Uploads. Der Ablauf besteht aus zwei Schritten.

1. Upload anlegen

Ein POST ohne Dateiinhalt meldet die Datei an. Die Zuordnung zum Warenkorb passiert über den Upload-Metadata-Header – die Werte sind jeweils Base64-kodiert. Anders als beim Schwester-Plugin gibt es keine lineItemId, weil der Upload für die gesamte Bestellung gilt:

curl -X POST https://ihr-shop.de/store-api/checkout/order-upload/1 \
  -H "sw-access-key: IHR-ACCESS-KEY" \
  -H "sw-context-token: IHR-CONTEXT-TOKEN" \
  -H "Tus-Resumable: 1.0.0" \
  -H "Upload-Length: 20480" \
  -H "Upload-Metadata: cartToken <base64>,name <base64>"

Die Antwort ist 201 Created mit einem Location-Header. Diese URL ist das Ziel für den zweiten Schritt.

Wichtig: cartToken muss der Token des aufrufenden Kontexts sein – also derselbe Wert, den Sie als sw-context-token senden. Ein fremder Warenkorb wird mit 403 abgelehnt.

2. Daten senden

curl -X PATCH <Location-URL> \
  -H "sw-access-key: IHR-ACCESS-KEY" \
  -H "sw-context-token: IHR-CONTEXT-TOKEN" \
  -H "Tus-Resumable: 1.0.0" \
  -H "Upload-Offset: 0" \
  -H "Content-Type: application/offset+octet-stream" \
  --data-binary @datei.pdf

Die Antwort ist 204 No Content. Große Dateien lassen sich in mehreren PATCH-Aufrufen mit fortlaufendem Upload-Offset senden; ein abgebrochener Upload kann an derselben Stelle fortgesetzt werden.

Datei entfernen

curl -X POST https://ihr-shop.de/store-api/checkout/order-upload-delete \
  -H "sw-access-key: IHR-ACCESS-KEY" \
  -H "sw-context-token: IHR-CONTEXT-TOKEN" \
  -d "id=<id des Uploads>"

Antwort bei Erfolg:

{ "apiAlias": "futi_order_upload_delete", "success": true, "id": "…" }

Gehört die Datei zu einem anderen Warenkorb, antwortet die Route mit 403; ist die ID unbekannt, mit 404.

Hinweis: Der Parameter heißt hier id, nicht cartUploadId wie beim Schwester-Plugin. Das entspricht der seit jeher genutzten Storefront-Route dieses Plugins.

Was Sie in Ihrem Frontend selbst bauen müssen

Die Store-API deckt die Serverseite ab. Im Frontend bleiben:

• die Auswahl- und Fortschrittsoberfläche für den Upload (die Storefront nutzt dafür Uppy mit dem tus-Plugin – das lässt sich in jedem JavaScript-Frontend genauso einsetzen)
• die Prüfung auf erlaubte Dateitypen und die maximale Anzahl vor dem Absenden, damit Kunden nicht erst nach dem Upload eine Fehlermeldung sehen
• die Anzeige der bereits hochgeladenen Dateien

Die Einstellungen zu erlaubten Dateitypen und Anzahl pflegen Sie weiterhin in der Plugin-Konfiguration, siehe Erweiterung.

Bestellung und Administration

Am Ablauf nach dem Bestellabschluss ändert sich nichts: Die Dateien werden der Bestellung zugeordnet und sind in der Administration abrufbar, siehe Daten herunterladen. Auch das E-Mail-Template funktioniert unverändert.

Nächster Schritt: Changelog →