> ## Documentation Index > Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt > Use this file to discover all available pages before exploring further. # Storefront API Basics Die Seite Storefront API Basics beschreibt die grundlegenden technischen Rahmenbedingungen für die Nutzung der Storefront API. Dazu gehören u. a. Basis-URL und Versionierung, Request-/Response-Format (JSON), Authentifizierung sowie allgemeine Konventionen wie Header, Fehlercodes und Paging. *** ## Basis URL Alle Storefront API-Endpunkte werden unter folgender URL aufgerufen: ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/api/v1/ ``` Diese URL ist die Basis für sämtliche Anfragen, z.B. ```http theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} GET https://.de/api/v1/config/address_lists ``` ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} GET https://.de/api/v1/watchList/list ``` ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} POST https://.de/api/v1/form/send ``` Als `ihr-shop.de` muss die Domain des WEBSALE Servers verwendet werden. Diese unterscheidet sich von der Hauptdomain des Shops. Bitte klären Sie die Domain mit Ihrem WEBSALE-Ansprechpartner und beachten Sie auch [Abschnitt 5](#5-einrichtung-der-storefront-api-basierten-storefront). ## Authentifizierung Im Gegensatz zur [Admin Interface API](/schnittstellen/admin-interface-api) erfordert die Storefront API keine separate API-Authentifizierung. Anfragen an die Storefront API laufen immer im Kontext des öffentlichen Shops. Einzelne Endpunkte können dennoch eine aktive Session voraussetzen, z.B. für Funktionen rund um das Kundenkonto. In diesen Fällen wird der Zugriff nicht über einen separaten API-Login, sondern über die vorhandene [Session](#3-session-handling) bzw. den normalen Login im Frontend gesteuert. ## Session-Handling Für zusammenhängende Aktionen im Shop (z. B. Warenkorb aufbauen, Merkliste verwenden, kundenabhängige Daten lesen) muss eine Session verwendet werden. Die Session ist die eindeutige ID, mit der der Shop mehrere Requests einem gemeinsamen Kontext zuordnet und damit benutzerspezifische Daten wiedererkennen kann (z. B. Warenkorb-Inhalt und Kundenzuordnung). Nicht alle Endpunkte erfordern eine aktive Session. Das Mitsenden einer Session ist jedoch jederzeit erlaubt und ausdrücklich empfohlen, wenn mehrere Anfragen zu einem zusammenhängenden Nutzungskontext gehören. ### Session erstellen Eine neue Session wird über folgenden Endpunkt erstellt: ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} POST https://.de/api/v1/session/create ``` Die genaue Struktur der Response ist in der [Endpunktdokumentation](/schnittstellen/storefront-api/storefront-api-session-handling) beschrieben. Wesentlich ist, dass die Antwort eine Session-ID zurückliefert (z. B. als Feld wie `sessionId` oder ähnlich), die für weitere Requests wiederverwendet wird. ### Session in Requests übergeben Damit der Shop eine bestehende Session erkennt, wird die Session-ID dann bei allen weiteren Anfragen im HTTP-Header `X-Session` mitgesendet. #### **Beispiel-Request (Rohformat)** ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} GET /api/v1/products/12345 HTTP/1.1 Host: .de X-Session: 0123456789abcdef ``` #### **Beispiel mit** `curl` ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} curl -X GET "https://.de/api/v1/products/12345" \ -H "X-Session: 0123456789abcdef" ``` * `X-Session` ist der Name des Custom-Headers. * Der Header-Wert ist die zuvor erzeugte Session-ID. Die Session wird niemals über Query-Parameter an die URL angehängt (z. B. `?session=…`), sondern ausschließlich über den Header übertragen. Auf diese Weise bleibt die Session-ID aus URLs und Browser-Historien heraus und kann sauber über den Request-Kontext gesteuert werden. ### Auswirkungen der Session Ob eine Session benötigt oder ausgewertet wird, hängt vom jeweiligen Endpunkt ab: * Für rein öffentliche Daten (z. B. allgemeine Produktinformationen) kann ein Request ohne Session möglich sein. * Wird eine gültige Session mitgesendet, können Endpunkte benutzerspezifische Informationen zurückgeben, z. B.: * kundenabhängige Preise, * bereits gefüllte Warenkörbe, * kundenkontoabhängige Einstellungen. Wird ein Endpunkt aufgerufen, der eine gültige Session oder ein angemeldetes Kundenkonto voraussetzt, kann bei fehlender oder ungültiger Session ein Fehler (z. B. `401 Unauthorized` oder `403 Forbidden`) zurückgegeben werden. Die genaue Fehlerbehandlung ist in Abschnitt „[Fehlerbehandlung](#3-fehlerbehandlung)“ beschrieben. ## Fehlerbehandlung Bei der Storefront API werden Fehler einheitlich über HTTP-Statuscodes und eine strukturierte Fehlerantwort im JSON-Format zurückgegeben. * Der HTTP-Statuscode zeigt an, ob eine Anfrage grundsätzlich erfolgreich war (2xx) oder fehlgeschlagen ist (4xx/5xx). * Die Fehlerantwort im JSON-Format liefert zusätzliche Details, mit denen Fehler im Frontend gezielt ausgewertet und angezeigt werden können (z. B. fehlerhafte Parameter oder fachliche Fehler bei der Ausführung). Die in diesem Abschnitt beschriebene Struktur der Fehlerantwort gilt für alle Storefront-API-Endpunkte. Unter den einzelnen Endpunkten werden nur noch die jeweils spezifischen fachlichen Fehlercodes dokumentiert. ### HTTP-Statuscodes Die Storefront API verwendet die üblichen HTTP-Statuscodes. Typische Beispiele: * **2xx – Erfolg** * `200 OK` – Anfrage erfolgreich, Antwort enthält Daten. * `201 Created` – Ressource wurde erfolgreich angelegt. * `204 No Content` – Anfrage erfolgreich, aber es werden keine Daten zurückgegeben. * **4xx – Fehler auf Client-Seite** * `400 Bad Request` – Anfrage ist ungültig, z. B. wegen fehlerhafter oder fehlender Parameter oder fachlicher Fehler. * `401 Unauthorized` – Authentifizierung fehlt oder ist ungültig. * `403 Forbidden` – Anfrage ist authentifiziert, aber nicht berechtigt. * `404 Not Found` – Ressource oder Endpunkt wurde nicht gefunden. * **5xx – Fehler auf Server-Seite** * `500 Internal Server Error` – unerwarteter Fehler im Backend. Bei allen 4xx- und 5xx-Antworten stellt die Storefront API zusätzlich ein Fehlerobjekt im JSON-Format bereit (siehe [Abschnitt 3.2](#4-fehlerbehandlung)). ### Fehler-Response Alle Fehlermeldungen werden im JSON-Format zurückgegeben. Die Antwort folgt einer einheitlichen Struktur, die es ermöglicht, Fehler systematisch auszuwerten und im Frontend aufzubereiten: ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "error": "", "detail": "", "paramErrors": { "": { "type": "" } }, "actionErrors": [ { "code" : "", "details" : {}, "field" : "", "subCode" : "", "text" : "" } ] } ``` #### Parameterübersicht Fehler-Response | **Parameter** | **Typ** | **Beschreibung** | | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `error` | | Kurzer, technischer Fehlercode auf oberster Ebene, der die Art des Fehlers beschreibt (z. B. `invalidParameters`, `actionFailed`). | | `detail` | | Optionale Kurzbeschreibung des Fehlers, z. B. zur Protokollierung oder für technische Auswertungen. | | `paramErrors` | | Objekt mit Detailinformationen zu fehlerhaften Parametern. Die Schlüssel entsprechen den Parameternamen, die Werte sind Objekte mit weiterführenden Angaben zum jeweiligen Fehler. Das Feld `paramErrors` kann je nach Fehlertyp leer sein. Siehe Abschnitt [Parameter-Fehler-Codes](https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3534127105/Storefront+API+Basics#321-parameter-fehler-codes-paramerrors) | | `actionErrors` | | Liste fachlicher Fehler, die bei der Ausführung der eigentlichen Aktion aufgetreten sind (z. B. „Bewertung für diese Bestellung nicht zulässig“). Jeder Eintrag enthält u. a.: - `code` – technischer Fehlercode, der die Ursache bezeichnet, - `field` – optional das betroffene Feld, - `text` – sprechende Fehlermeldung zur Anzeige im Frontend, - `details` / `subCode` – optionale Zusatzinformationen. Das Feld `actionErrors` kann je nach Fehlertyp leer sein. Siehe Abschnitt [Aktionsfehler](https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3534127105/Storefront+API+Basics#323-aktionsfehler-actionerrors) | #### Parameter-Fehler-Codes (`paramErrors`) Parameterfehler treten auf, wenn eine Anfrage formal ungültig ist, z. B. weil ein Pflichtfeld fehlt oder ein Wert das falsche Format besitzt. In diesen Fällen gibt die API in der Regel: * den HTTP-Status `400 Bad Request` * das Fehlerobjekt mit * `error = "invalidParameters"` * einem oder mehreren Einträgen in `paramErrors` Die in `paramErrors..type` verwendeten Fehlercodes haben folgende Bedeutung: | **Error Code** | **Typ** | **Beschreibung** | | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------ | | `unknownDataField` | | Ein unbekanntes Feld wurde gesendet. | | `invalidFormat` | | Der Parameter hat ein ungültiges Format, z. B. String statt Integer oder ein nicht parsebares JSON-Fragment. | | `invalidValue` | | Der Wert des Parameters ist ungültig - z.B. außerhalb des gültigen Bereiches. | | `invalidCombination` | | Zwei oder mehr Parameter schließen sich gegenseitig aus. | | `syntaxError` | | Es besteht ein Syntaxfehler im Parameter. | | `missing` | | Ein Pflichtfeld fehlt. | | `readonlyField` | | Es wurde versucht, ein Read-Only-Feld zu beschreiben. | | `duplicateEntry` | | Ein Wert, der nur einmal vorkommen darf, wurde mehrfach verwendet. | #### Aktionsfehler (`actionErrors`) Als „Action“ werden alle API-Aufrufe bezeichnet, die den “Shop-Zustand” ändern – also in der Regel POST-, PUT- oder DELETE-Aufrufe (z. B. Produkt in den Warenkorb legen, Adresse anlegen, Newsletter abonnieren etc.). Reine Lese-Aufrufe (z. B. Produkte laden) sind keine “Actions” und liefern diese Fehler in der Regel nicht. Aktionsfehler treten dann auf, wenn die Anfrage zwar formal korrekt ist (alle Parameter sind gültig), die angeforderte Aktion aber trotzdem nicht erfolgreich durchgeführt werden kann, z.B. * Für eine Bestellung darf keine weitere Bewertung erstellt werden * Das angegebene Produkt ist in diesem Kontext nicht bewertbar * Eine Aktion ist für den aktuellen Zustand nicht erlaubt (z. B. Artikel nicht mehr verfügbar, Mindestmenge nicht erfüllt) In diesen Fällen wird ein geeigneter HTTP-Statuscode (in der Regel ein [4xx-Code](#4-1-http-statuscodes), häufig `400 Bad Request`) zurückgegeben. Das Fehlerobjekt enthält zudem: * einen passenden Wert im Feld `error`, der die generelle Fehlerkategorie beschreibt, z. B. `actionFailed`, * einen oder mehrere Einträge in `actionErrors`, die den konkreten Aktionsfehler beschreiben * `code` – technischer Fehlercode (z. B. `ratingNotAllowed`, `orderNotFound`, `cartProductNotAvailable`), * `field` – optional das betroffene Feld oder die betroffene Entität (z. B. `productId`, `cart`), * `text` – sprechender Fehlertext, der im Frontend direkt angezeigt oder lokalisiert werden kann, * `details` – optionales Objekt mit Zusatzinformationen (z. B. betroffene IDs, verfügbare Menge), * `subCode` – optionaler Untercode zur feineren Differenzierung. #### **Beispiel** Ein Kunde versucht, ein Produkt in den Warenkorb zu legen. Die Anfrage ist formal korrekt (alle Parameter vorhanden und im richtigen Format), das Produkt ist jedoch nicht mehr verfügbar. HTTP-Antwort → Status: `400 Bad Request` Response-Body: ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "error": "actionFailed", "detail": "Product cannot be added to cart.", "paramErrors": {}, "actionErrors": [ { "code": "cartProductNotAvailable", "details": { "productId": 12345, "requestedQuantity": 2, "availableQuantity": 0 }, "field": "productId", "subCode": "", "text": "Das ausgewählte Produkt ist derzeit nicht verfügbar und kann nicht in den Warenkorb gelegt werden." } ] } ``` Aus dieser Antwort geht hervor: * Die Anfrage ist formal korrekt (`paramErrors` ist leer). * Die Aktion (Produkt in den Warenkorb legen) konnte nicht ausgeführt werden (`error = "actionFailed"`). * Der fachliche Grund ist der Action-Fehler mit * `code = "cartProductNotAvailable"`, * einem betroffenen Feld `field = "productId"` und * einem sprechenden Fehlertext in `text`, der direkt im Frontend angezeigt werden kann. Die hier dargestellte Struktur der Fehlerantwort ist für alle Endpunkte gleich. Welche konkreten Action-Fehlercodes (`actionErrors[].code`) bei einem Endpunkt auftreten können, wird jeweils beim zugehörigen Endpunkt dokumentiert. ## Einrichtung der Storefront-API-basierten Storefront Wird ein WEBSALE Shop über seine Domain aufgerufen (z. B. `www.ihr-shop.de`), wird die Storefront standardmäßig über das WEBSALE Template-Theme ausgeliefert und dargestellt. Soll die Storefront stattdessen auf Basis der Storefront API (z. B. mit einem eigenen Frontend-Framework) betrieben werden, sind entsprechende Einstellungen erforderlich, damit diese neue Storefront ausgeliefert und verwendet wird. Bitte sprechen Sie hierzu mit Ihrem WEBSALE Ansprechpartner, um die dafür notwendigen Einstellungen im Detail zu besprechen.