by

ShopAware-Hilfe

Storefront-API-Referenz

Authentifizierung, Anfrage- und Antwortfelder, Fehler, Ratenbegrenzung und Kompatibilität für Website-Entwickler.

Diese Referenz beschreibt den Entwicklungsstand vom 15. September 2026. Sie ist ohne ShopAware-Anmeldung oder Repository-Zugang verfügbar. Beginnen Sie mit der Schlüsseleinrichtung und dem Website-Integrationsbeispiel.

Basis-URL und Authentifizierung

Basis-URL der Entwicklungs-API: https://api.dev.shopaware.co. Ein Produktionszugang ist noch nicht verfügbar. Verwenden Sie die API-Adresse, nicht die Website-Adresse; vor Storefront-Pfaden steht kein /api/v1.

Senden Sie einen von ShopAware ausgestellten swak_...-Schlüssel im Header sw-access-key. Er legt Shop, Verkaufskanal und Katalogsprache fest. Er ist weder der Shopware-Store-API-Schlüssel noch ein Shopware-Admin-API-Zugang.

Bewahren Sie ihn im Website-Backend auf. Er gehört nicht in URLs, Browser-Code, Screenshots, Analyseereignisse oder Supportnachrichten. Senden Sie keine Käufer-Cookies, Bearer-Tokens, Bestellhistorien oder weitergereichten IP-Header an ShopAware. Direkte Browser-Aufrufe sind nicht der unterstützte Standard; beliebige Origins werden nicht automatisch zugelassen.

Anfragen

GET /store-api/product/11111111111141118111111111111111/cross-selling?limit=5
Host: api.dev.shopaware.co
sw-access-key: YOUR_SERVER_SIDE_SHOPAWARE_KEY
Accept: application/json
POST /store-api/product/11111111111141118111111111111111/cross-selling
Host: api.dev.shopaware.co
sw-access-key: YOUR_SERVER_SIDE_SHOPAWARE_KEY
Content-Type: application/json

{"limit": 5}

Ersetzen Sie die Beispiel-UUID durch die UUID eines importierten Ausgangsprodukts. UUIDs mit Bindestrichen und 32-stellige Hexadezimalwerte werden akzeptiert. limit ist standardmäßig 5 und muss eine ganze Zahl zwischen 1 und 5 je Gruppe sein. Bei POST darf der Body fehlen. Andere Criteria-Eigenschaften werden ignoriert; sie filtern oder sortieren keine Empfehlungen. GET verwendet den Query-Parameter, POST den JSON-Body.

sw-language-id wird aus Kompatibilitätsgründen akzeptiert, aber ignoriert. Der Header überschreibt die Schlüsselsprache nicht. Für eine andere Katalogsprache oder einen anderen Verkaufskanal benötigen Sie einen entsprechend begrenzten Schlüssel.

Beispielantwort

[
  {
    "crossSelling": {
      "id": "44444444444444448444444444444444",
      "name": "Alternativen",
      "position": 1,
      "type": "productList",
      "active": true,
      "limit": 5,
      "translated": {"name": "Alternativen"},
      "apiAlias": "product_cross_selling"
    },
    "products": [
      {
        "id": "22222222222242228222222222222222",
        "productNumber": "DEMO-2",
        "name": "Beispielprodukt",
        "description": null,
        "translated": {"name": "Beispielprodukt", "description": null},
        "cover": null,
        "apiAlias": "product",
        "extensions": {
          "shopaware": {
            "familyId": "22222222222242228222222222222222",
            "intent": "similar",
            "partialProduct": true,
            "rank": 1,
            "similarity": 0.84
          }
        }
      }
    ],
    "total": 1,
    "apiAlias": "cross_selling_element"
  }
]

Namen folgen der Katalogsprache des Schlüssels. Unabhängig aktivierte Profile liefern Alternativen (similar) und/oder Ergänzungen (cross_sell). Ist keines aktiv, gilt das akzeptierte allgemeine Profil Verwandte Produkte (general). Ohne ausreichend sichere Treffer kann eine Gruppe entfallen oder die gesamte Antwort [] sein. Es gibt höchstens zwei Gruppen mit jeweils bis zu fünf Produkten. total zählt die Produkte dieser Gruppe; es ist weder ein Kataloggesamtwert noch ein Paginierungs-Cursor.

Felder und Geschäftsdaten

  • crossSelling: stabile Gruppen-ID, lokalisierter Name, Position, Aktivstatus und angefragtes Limit je Gruppe.
  • products[].id: Produkt-UUID als 32-stelliger kleingeschriebener Hexadezimalwert.
  • productNumber, description, cover: Katalogfelder, die null sein dürfen. Ein Cover kann eine Bild-URL enthalten; es ist optional.
  • name, translated: normalisierte Katalogtexte. Als Text darstellen, niemals als ungeprüftes HTML.
  • extensions.shopaware.familyId: Produktfamilie; je Gruppe höchstens ein Kandidat pro Familie, ohne die Familie des Ausgangsprodukts.
  • intent, rank, similarity: Empfehlungsmetadaten. Reihenfolge erhalten; Ähnlichkeit ist weder Wahrscheinlichkeit noch Umsatzprognose.
  • partialProduct: immer true. Verbindliche Preise, Steuern, Währung, Bestand, Mengenregeln und Checkout-Berechtigung kommen nicht von ShopAware.

Laden Sie Geschäftsdaten vor der Anzeige über Ihren Shopware-Verkaufskanal-Client und den aktuellen Einkaufskontext. Nicht verfügbare oder nicht prüfbare Produkte entfallen; die verbleibende Reihenfolge bleibt bestehen. Leere Ergebnisse nicht auffüllen und Preise nicht erfinden. Das OpenAPI-Schema zum Herunterladen enthält Antwortmodelle und Anfragevalidierung. Erweiterungsobjekte bleiben im Schema offen; die obigen Felder beschreiben diesen Stand.

Fehler und Ratenbegrenzung

  • 401: fehlender, ungültiger, unbekannter, widerrufener oder einem inaktiven Kontext zugeordneter Schlüssel. Die Antwort unterscheidet diese Fälle absichtlich nicht. Serverkonfiguration prüfen, ohne den Schlüssel offenzulegen.
  • 404: ungültige UUID oder Ausgangsprodukt außerhalb des genauen Schlüsselkontexts. Import, Verkaufskanal und Katalogsprache prüfen.
  • 409: aktives Profil kann nicht sicher ausgeliefert werden. Bereich ausblenden; Händler soll das Profil prüfen.
  • 422: ungültiges Limit oder Anfrageformat. Anfrage korrigieren statt unverändert wiederholen. Validierungsdetails können eine strukturierte Liste sein.
  • 429: Minutenlimit erreicht. Retry-After beachten; aktuell gibt der Dienst 60 Sekunden zurück. Während der Pause Empfehlungen ausblenden, statt bei jedem Seitenbesuch erneut anzufragen.
  • 5xx, Netzwerkfehler oder Zeitüberschreitung: Shop ohne Empfehlungsbereich nutzbar halten. Begrenzte Zeitlimits verwenden, keine Wiederholungsschleifen.

Normale Anwendungsfehler verwenden JSON, etwa {"detail":"Authorization information is missing or invalid"}. Gateways können andere Formate liefern. Nach HTTP-Status verzweigen und rohe Antworttexte weder Käufern zeigen noch protokollieren.

Das technische Standardlimit beträgt 120 Anfragen je Schlüssel und UTC-Minute, gemeinsam über alle API-Worker. Es ist kein kostenpflichtiges Monatskontingent. Erfolgreiche Antworten und explizit behandelte 401/404/409/429-Fehler verwenden Cache-Control: private, no-store und Vary: sw-access-key. In Ihrer Integration alle Antworten einschließlich Validierungs- und Gateway-Fehlern als nicht cachebar behandeln. Schlüssel dürfen keine im Browser sichtbaren Cache-Schlüssel sein.

Lebenszyklus der Schlüssel

Nur Unternehmensadministratoren verwalten Schlüssel. Im Bereich Storefront-Integration unter Empfehlungen wählen Sie Verkaufskanal und Sprache und erstellen, rotieren oder widerrufen den Schlüssel. Nur die Erstellungsantwort zeigt den Rohwert; Listen enthalten einen Hinweis aus sechs Zeichen.

Rotation widerruft sofort den bisherigen Schlüssel dieses Kontexts. Gemeinsame Aktualisierung und Verhalten bei leeren Ergebnissen vorbereiten, rotieren, Ersatzwert sicher speichern, alle Website-Backend-Instanzen neu laden und eine Anfrage prüfen. Eine kurze Unterbrechung ist möglich. Es gibt kein Überlappungsfenster und keine Rückkehr zum alten Schlüssel. Geht der Ersatzwert verloren, erneut rotieren.

Die Verwaltungsrouten sind GET/POST /api/v1/stores/{store_id}/storefront-access-keys und DELETE /api/v1/stores/{store_id}/storefront-access-keys/{access_key_id}. Sie erfordern das signierte Benutzer-Bearer-Token und die passende Unternehmensrolle. Ein Storefront-Schlüssel gewährt keinen Zugriff auf Konten, Kalibrierung, Nutzung oder Administration.

Kompatibilität

Der aktuelle Pfad enthält kein URL-Versionssegment. Das Datum bezeichnet einen Entwicklungsstand, keine Shopware-Version und keine Produktions-SLA. Clients sollten zusätzliche optionale Felder akzeptieren und keine feste Gruppen- oder Ergebniszahl voraussetzen. Inkompatible Änderungen benötigen einen neu dokumentierten Vertrag und Migrationshinweise. Monatstarife, direkte Browser-Origin-Unterstützung und Shopware-Sprach-ID-Zuordnung sind separate Funktionen und dürfen nicht vorausgesetzt werden.

Zurück zu allen Hilfeartikeln