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

Hinweis: Verfügbar ab Version 2.4.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

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 zu Warenkorb und Position passiert über den Upload-Metadata-Header – die Werte sind jeweils Base64-kodiert:

curl -X POST https://ihr-shop.de/store-api/checkout/item-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>,lineItemId <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.

Hochgeladene Dateien abrufen

Dafür gibt es keinen eigenen Endpunkt – die Dateien kommen über den Warenkorb selbst. Rufen Sie /store-api/checkout/cart ab, trägt jede Position ihre Uploads in der uploads-Extension:

{
  "lineItems": [
    {
      "id": "…",
      "extensions": {
        "uploads": [
          { "id": "…", "fileName": "druckdatei.pdf", "fileSize": 20480, "qquuid": "…" }
        ]
      }
    }
  ]
}

Datei entfernen

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

Antwort bei Erfolg:

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

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

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 maximale Größe vor dem Absenden, damit Kunden nicht erst nach dem Upload eine Fehlermeldung sehen
• die Anzeige der bereits hochgeladenen Dateien aus der uploads-Extension

Die Einstellungen zu erlaubten Dateitypen und Größe pflegen Sie weiterhin in der Plugin-Konfiguration, siehe Erweiterung.

Bestellung und Administration

Am Ablauf nach dem Bestellabschluss ändert sich nichts: Die Dateien werden der Bestellposition zugeordnet und sind in der Administration an der Bestellung abrufbar. Auch die E-Mail-Templates funktionieren unverändert.

Nächster Schritt: Changelog →