Store API

Das Formular-Werkzeug ist vollständig headless-kompatibel. Alle Storefront-Funktionen — Formular einreichen, Bestätigungs-Logik, Validierung — sind über die Shopware Store API erreichbar.

Diese Seite richtet sich an Entwickler:innen, die eigene Frontends, mobile Apps oder integrierende Drittsysteme anbinden.

Basis-URL & Headers

Header	Wert
Content-Type	multipart/form-data (mit Datei-Upload) oder application/x-www-form-urlencoded
sw-access-key	Storefront-Access-Key des Verkaufskanals
sw-language-id	optional, UUID-Hex der Sprache
sw-context-token	optional, für eingeloggte Kund:innen

Basis-URL: https://<shop>/store-api

Endpoint: Formular absenden

POST /store-api/prems/form/submit

Felder im Body

Feld	Pflicht	Beschreibung
form_id	ja	UUID des Formulars
<identifier>	je nach Definition	je Formularfeld der Wert (Key = Technischer Name)
<identifier>[]	je nach Definition	Checkbox-Gruppen senden ein Array
shopware_basic_captcha_confirm	je nach Captcha-Config	Captcha-Antwort (BasicCaptcha)
g-recaptcha-response	je nach Captcha-Config	Captcha-Token (reCAPTCHA)

Hidden-Inputs bei der Produkt-Anfrage

Feld	Bedeutung
__prems_product_id	Produkt-UUID
__prems_product_number	Produktnummer
__prems_product_name	Anzeigename
__prems_product_price	Formatierter Preis
__prems_product_url	Kanonische URL

Antwort

Bei Erfolg (HTTP 200) liefert der Endpoint ein JSON-Objekt vom Typ FormSubmitRouteResponse mit dem Ergebnis:

{
    "result": {
        "entryId": "01H...HEX",
        "responseType": "success-notice",
        "responseMessage": "Vielen Dank! Ihre Nachricht wurde übermittelt.",
        "redirectUrl": null,
        "redirectDelay": null
    }
}

Bei Validierungsfehlern (HTTP 400) erhältst du eine ConstraintViolationException im Shopware-Standard:

{
    "errors": [
        {
            "code": "VIOLATION::IS_BLANK_ERROR",
            "status": "400",
            "title": "Constraint violation error",
            "detail": "This value should not be blank.",
            "source": { "pointer": "/firstName" },
            "meta": { "parameters": [] }
        }
    ]
}

Bei Captcha-Fehlern (HTTP 403) liefert Shopware Core eine CaptchaException.

Bei deaktiviertem Plugin (HTTP 403) oder unbekannter Formular-ID (HTTP 404) wird eine FormSubmitException zurückgegeben.

Felder eines Formulars laden

Für das Bauen eines eigenen Frontends benötigst du die Definition des Formulars (Felder, Reihenfolge, Pflichtfeld-Flag, Optionen). Du lädst sie über den DAL-Search-Endpoint:

POST /store-api/search/prems-form

Body:

{
    "filter": [
        { "type": "equals", "field": "id", "value": "<formId>" },
        { "type": "equals", "field": "active", "value": true }
    ],
    "associations": {
        "fields": { "sort": [{ "field": "sortOrder" }] }
    }
}

Die Antwort enthält das Formular mit allen Feldern, ihren Übersetzungen und Sichtbarkeits-Bedingungen.

Entity-Aliase

Alias	Inhalt
prems_form	Formular
prems_form_field	einzelnes Feld / Strukturelement
prems_form_field_translation	übersetzbare Eigenschaften pro Sprache
prems_form_entry	Einsendung
prems_form_mail_route	Mail-Route

Events (für eigene Backend-Erweiterungen)

Event	Klasse	Wann ausgelöst
prems_form.submitted	Prems\Plugin\PremsForm\Core\Event\PremsFormSubmittedEvent	nach erfolgreicher Einsendung (auch über die Store API)

Du kannst dich an dieses Event hängen, um eigene Aktionen anzustoßen oder Daten an Drittsysteme weiterzuleiten.