Store API
Diese Seite richtet sich an Entwickler & Integratoren. Sie beschreibt die HTTP-Schnittstellen für den Einsatz des Konfigurators in einem Headless-Frontend (PWA, App, Composable Commerce).
Die gesamte preiswirksame Logik ist über die Store API verfügbar. Ein Headless-Client benötigt drei Bausteine: Preis berechnen, in den Warenkorb legen und (optional) Konfigurationen speichern/laden.
Alle Store-API-Aufrufe benötigen den Header sw-access-key des Verkaufskanals. Der Kontext (Sprache, Währung, Kunde) wird wie üblich über sw-context-token geführt. Die Konfigurator-Routen sind öffentlich (_loginNotRequired), erfordern also keinen eingeloggten Kunden.
Live-Preis berechnen
POST /store-api/prems/configurator/priceBerechnet Stückpreis, Maße und Zwischenergebnisse für eine Konfiguration neu. Nicht gecacht.
Request-Body:
{
"productId": "0199b586c0f273aa8d2f4e1b2c3d4e5f",
"fields": {
"color": "gold",
"width": "30",
"height": "20",
"extras": ["gift_wrap", "express"]
}
}productId(string, erforderlich) – ID des Produkts.fields(object, erforderlich) – Map aus technischem Bezeichner → Wert. Werte sind Strings oder Arrays von Strings (Mehrfachauswahl).
Response:
price(float) – neuer Stückpreis in der Kontextwährung.formattedPrice(string) – sprach-/währungsformatierter Preis.priceChanged(bool) – ob die Konfiguration den Preis verändert hat.measurements(object) –width,height,length,weight(neu berechnet oder Produktwerte).interimResults(object) – Map aus Feld-Bezeichner → berechnetem Anzeigetext.
Existiert kein (aktiver) Konfigurator für das Produkt, wird der Basispreis mit priceChanged: false zurückgegeben.
In den Warenkorb legen
Es gibt keine eigene Warenkorb-Route. Verwende die Standard-Route und hänge das Objekt premsConfigurator auf oberster Ebene an den Request an:
Request-Body:
Der Server validiert die Felder serverseitig (Pflichtfelder, E-Mail/Telefon, Min/Max, erlaubte Optionen). Bei Verstößen antwortet er mit einer ConstraintViolation. Bei Erfolg wird das Line-Item mit dem berechneten Preis, den Eingabewerten (für die Checkout-Anzeige) sowie ggf. berechneten Maßen und einer Artikelnummer angereichert. Positionen mit unterschiedlicher Konfiguration werden nicht zusammengeführt.
Die Preisneuberechnung erfolgt bei jeder Warenkorb-Operation serverseitig – der Client muss den Preis nicht selbst setzen.
Konfiguration speichern
Erfordert, dass Konfiguration speichern im Verkaufskanal aktiviert ist (sonst Fehlerantwort).
Request-Body:
Response:
token(string) – öffentlicher Token der gespeicherten Konfiguration.
Mit dem Token lässt sich die Konfiguration später wiederherstellen. Im klassischen Storefront öffnet die Route GET /prems/configurator/c/{token} den Share-Link und leitet auf die Produktseite mit dem Query-Parameter premsSavedConfig={token} weiter; ein Headless-Frontend liest den Token selbst aus und ruft damit erneut die Preis-Route auf bzw. lädt die gespeicherten Werte.
Storefront-Routen (klassisches Theme)
Diese Routen werden vom mitgelieferten Storefront genutzt und sind für Headless-Clients in der Regel nicht nötig:
POST /prems/configurator/price
Storefront-Wrapper der Preis-Route (XHR).
POST /prems/configurator/save
Speichern; liefert zusätzlich shareUrl.
POST /prems/configurator/change
„Konfiguration ändern" aus dem Warenkorb (Redirect).
GET /prems/configurator/c/{token}
Share-Link öffnen; Redirect auf die Produktseite.
Admin-API: Formel prüfen
Nur im authentifizierten Admin-Kontext (für eigene Backend-Erweiterungen):
Request (form-encoded): formula=<twig> und optional variables[]=<name>.
Response:
valid(bool),message(string|null),line(int|null).
Integrations-Workflow (Headless)
Produktseite rendert das Konfigurator-Formular (Feldstruktur über deine eigene Datenquelle/Admin-API).
Bei jeder Eingabe-Änderung:
POST /store-api/prems/configurator/price→ Preis & Zwischenergebnisse aktualisieren.„In den Warenkorb":
POST /store-api/checkout/cart/line-itemmitpremsConfigurator. ConstraintViolations dem Nutzer anzeigen.Optional „Speichern":
POST /store-api/prems/configurator/save→ Token teilen.Beim Öffnen eines geteilten Links: Token auslesen, gespeicherte Werte laden und Schritt 2 erneut ausführen.
War das hilfreich?
