> For the complete documentation index, see [llms.txt](https://docs.premsoft.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.premsoft.de/plugins/formular-baukasten/store-api.md).

# 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.

{% hint style="info" %}
Diese Seite richtet sich an Entwickler:innen, die eigene Frontends, mobile Apps oder integrierende Drittsysteme anbinden.
{% endhint %}

## 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

```http
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:

```json
{
    "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:

```json
{
    "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:

```http
POST /store-api/search/prems-form
```

Body:

```json
{
    "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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.premsoft.de/plugins/formular-baukasten/store-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.