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

> Online-Formulare des Shops über die Storefront API auflisten, einzelne Formulare oder Felder abrufen und ausgefüllte Daten zurück übermitteln.

Über den API-Endpunkt für Formulare werden die im Shop verfügbaren Online-Formulare bereitgestellt und deren Felder, Pflichtangaben und Validierungen ausgeliefert. Über den Endpunkt können alle Formulare aufgelistet, ein einzelnes Formular oder Feld abgerufen und ausgefüllte Formulare übermittelt werden.

***

## Unterstützte Methoden

Angabe aller unterstützten Methoden.

| **Befehl**                                      | **Endpunkte**      | **GET**               | **PUT**             | **POST**              | **DELETE**          |
| ----------------------------------------------- | ------------------ | --------------------- | ------------------- | --------------------- | ------------------- |
| Alle Formulare abrufen.                         | `form/list`        | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" />   | <Icon icon="ban" /> |
| Ein bestimmtes Formular abrufen.                | `form/get`         | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" />   | <Icon icon="ban" /> |
| Ein bestimmtes Formularfeld abrufen.            | `form/getField`    | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" />   | <Icon icon="ban" /> |
| Eine Formularanfrage versenden.                 | `form/send`        | <Icon icon="ban" />   | <Icon icon="ban" /> | <Icon icon="check" /> | <Icon icon="ban" /> |
| Details einer zuvor gesendeten Anfrage abrufen. | `form/loadInquiry` | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" />   | <Icon icon="ban" /> |

## Methoden für Formulare

Diese Methoden decken den kompletten Lebenszyklus von Online-Formularen im Shop ab. Sie lesen alle konfigurierten Formulare einschließlich der Felder, der Pflichtkennzeichnung, der Validierungen und der E-Mail-Einstellungen aus. Bei Bedarf können ein einzelnes Formular oder ein einzelnes Feld gezielt nach ID geladen werden. Darüber hinaus ist das Übermitteln ausgefüllter Formulare möglich. Dabei wird eine Vorgangs-ID (`inquiryId`) bereitgestellt, die eine spätere Nachverfolgung bzw. Detailabfragen ermöglicht.

### GET form/list

Der folgende Aufruf liefert alle im Shop konfigurierten Formulare inklusive Felddefinitionen und E-Mail-Einstellungen. Er kann zum Erstellen von Formularen inklusive Pflichtfeldern und Validierungen genutzt werden.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<ihr-shop>.de/api/v1/form/getAll
```

#### **Parameterübersicht**

| **Parameter** | **Typ** | **Beschreibung**              |
| ------------- | ------- | ----------------------------- |
| --            | --      | Keine zusätzlichen Parameter. |

#### **Beispiel-Response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[
  {
    "email": {
      "fromAddress": "contact@myshop.de",
      "fromName": "myshop Versender",
      "merchantEmail": "dev-test@websale.de",
      "subject": "Ihre Kontaktanfrage wurde aufgenommen.",
      "template": "contact.htm"
    },
    "fields": [
      { "label": "Vorname", "name": "firstName", "required": false, "validations": [ { "name": "minLength", "type": "dataChecker" }, { "name": "maxLength", "type": "dataChecker" } ] },
      { "label": "Nachname", "name": "lastName", "required": false, "validations": [ { "name": "minLength", "type": "dataChecker" }, { "name": "maxLength", "type": "dataChecker" } ] },
      { "label": "Betreff", "name": "subject", "required": true,  "validations": [ { "name": "maxLength", "type": "dataChecker" } ] },
      { "label": "Kundennummer", "name": "customerNumber", "required": false, "validations": [ { "name": "maxLength", "type": "dataChecker" } ] },
      { "label": "Text", "name": "text", "required": true, "validations": [ { "name": "minLength", "type": "dataChecker" }, { "name": "maxLength", "type": "dataChecker" } ] }
    ],
    "name": "contact"
  },
  {
    "email": {
      "fromAddress": "contact@myshop.de",
      "fromName": "myshop Versender",
      "merchantEmail": "dev-test@websale.de",
      "subject": "Ihre Kontaktanfrage wurde aufgenommen.",
      "template": "contact.htm"
    },
    "fields": [
      { "label": "Vorname", "name": "firstName", "required": false, "validations": [ { "name": "minLength", "type": "dataChecker" }, { "name": "maxLength", "type": "dataChecker" } ] },
      { "label": "Nachname", "name": "lastName", "required": false, "validations": [ { "name": "minLength", "type": "dataChecker" }, { "name": "maxLength", "type": "dataChecker" } ] },
      { "label": "Betreff", "name": "subject", "required": true,  "validations": [ { "name": "maxLength", "type": "dataChecker" } ] },
      { "label": "Kundennummer", "name": "customerNumber", "required": false, "validations": [ { "name": "maxLength", "type": "dataChecker" } ] },
      { "label": "Text", "name": "text", "required": true, "validations": [ { "name": "minLength", "type": "dataChecker" }, { "name": "maxLength", "type": "dataChecker" } ] }
    ],
    "name": "contact_friendlycaptcha"
  }
]
```

### GET form/get

Mit folgendem Aufruf kann ein einzelnes Formular anhand seiner technischen ID (abrufbar über „form/getAll”) inklusive Felddefinitionen, Pflichtangaben, Validierungen und E-Mail-Einstellungen geladen werden. Er kann zum gezielten Anzeigen eines Formulars verwendet werden.

Beispiel-Aufruf, der ein Formular mit der `formId` `contact` lädt:

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<ihr-shop>.de/api/v1/form/get?formId=contact
```

#### **Parameterübersicht**

| **Parameter** | **Typ** | **Beschreibung**                                                               |
| ------------- | ------- | ------------------------------------------------------------------------------ |
| `formId`      | string  | **Pflichtfeld**<br />Technische ID des Formulars (abrufbar über `form/getAll`) |

#### **Beispiel-Response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "email": {
    "fromAddress": "contact@myshop.de",
    "fromName": "myshop Versender",
    "merchantEmail": "dev-test@websale.de",
    "subject": "Ihre Kontaktanfrage wurde aufgenommen.",
    "template": "contact.htm"
  },
  "fields": [
    {
      "label": "Vorname",
      "name": "firstName",
      "required": false,
      "validations": [
        { "name": "minLength", "type": "dataChecker" },
        { "name": "maxLength", "type": "dataChecker" }
      ]
    },
    {
      "label": "Nachname",
      "name": "lastName",
      "required": false,
      "validations": [
        { "name": "minLength", "type": "dataChecker" },
        { "name": "maxLength", "type": "dataChecker" }
      ]
    },
    {
      "label": "Betreff",
      "name": "subject",
      "required": true,
      "validations": [
        { "name": "maxLength", "type": "dataChecker" }
      ]
    },
    {
      "label": "Kundennummer",
      "name": "customerNumber",
      "required": false,
      "validations": [
        { "name": "maxLength", "type": "dataChecker" }
      ]
    },
    {
      "label": "Text",
      "name": "text",
      "required": true,
      "validations": [
        { "name": "minLength", "type": "dataChecker" },
        { "name": "maxLength", "type": "dataChecker" }
      ]
    }
  ],
  "name": "contact"
}
```

### GET form/getField

Mit dem folgenden Aufruf wird ein Formularfeld mit Label, Pflichtstatus und Validierungen geladen. Er kann verwendet werden, um das Feld gezielt anzuzeigen, ohne das ganze Formular neu zu laden.

Beispiel-Aufruf, der das Feld `firstName` aus dem Formular `contact` lädt:

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<ihr-shop>.de/api/v1/form/getField?formId=contact&fieldId=firstName
```

#### **Parameterübersicht**

| **Parameter** | **Typ** | **Beschreibung**                                                               |
| ------------- | ------- | ------------------------------------------------------------------------------ |
| `formId`      | string  | **Pflichtfeld**<br />Technische ID des Formulars (abrufbar über `form/getAll`) |
| `fieldId`     | string  | **Pflichtfeld**<br />ID/Name des Feldes im Formular (z.B. `firstName`)         |

#### **Beispiel-Response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "label": "Vorname",
  "name": "firstName",
  "required": false,
  "validations": [
    { "name": "minLength", "type": "dataChecker" },
    { "name": "maxLength", "type": "dataChecker" }
  ]
}
```

### GET form/loadInquiry

Mit folgendem Aufruf kann eine bereits versendete Anfrage anhand ihrer Vorgangs-ID geladen werden. Er kann verwendet werden, um nach dem Absenden des Formulars eine Bestätigungsseite anzuzeigen oder um eine Anfrage später erneut anzusehen.

Beispiel-Aufruf, der die Anfrage mit der ID `7930f7e9fa7bb07b` lädt:

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<ihr-shop>.de/api/v1/form/loadInquiry?inquiryId=7930f7e9fa7bb07b
```

#### **Parameterübersicht**

| **Parameter** | **Typ** | **Beschreibung**                                                                                |
| ------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `inquiryId`   | string  | **Pflichtfeld**<br />Vorgangs-ID der Anfrage (erhältlich z.B. aus dem Response von `form/send`) |

 

#### **Beispiel-Response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "createdAt": "2025-11-11T14:36:03Z",
  "form": {
    "customerNumber": { "label": "Kundennummer", "value": "" },
    "firstName":      { "label": "Vorname",      "value": "Eren" },
    "lastName":       { "label": "Nachname",     "value": "Jäger" },
    "subject":        { "label": "Betreff",      "value": "Wichtige Mitteilung" },
    "text":           { "label": "Text",         "value": "tatakae!" }
  },
  "formId": "contact",
  "id": "7930f7e9fa7bb07b",
  "submitter": {
    "email": "test@example.de",
    "ipAddress": "172.18.0.XXX",
    "sessionId": "4d1536fe...cd07d"
  }
}
```

### POST form/send

Mit folgendem Aufruf wird eine Formularanfrage (z. B. ein Kontaktformular) an den Shop gesendet und dafür ein Vorgang erzeugt. Er ist zum Absenden eines Formulars und zum Anzeigen einer Bestätigung inklusive Vorgangsnummer verwendbar.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
POST https://<ihr-shop>.de/api/v1/form/send
```

#### **Beispiel-Request**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "formId": "contact",
  "email": "test@example.de",
  "form": {
    "firstName": "Eren",
    "lastName": "Jäger",
    "subject": "Wichtige Mitteilung",
    "text": "tatakae!"
  }
}
```

#### **Parameterübersicht**

| **Parameter** | **Typ** | **Beschreibung**                                                                                                                                                          |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `formId`      | string  | **Pflichtfeld**<br />Technische ID des Formulars (abrufbar über `form/getAll`)                                                                                            |
| `email`       | string  | **Pflichtfeld**<br />Absender-/Antwort-E-Mail-Adresse der anfragenden Person.                                                                                             |
| `form`        | object  | **Pflichtfeld**<br />Hier werden die Feld-IDs aus der Formular-Definition (z.B. `firstName`, `subject`, `text`) inklusive ihres Wertes (Vorname, Betreff etc.) angegeben. |

#### **Beispiel-Response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "inquiryId": "7930f7e9fa7bb07b"
}
```

`InquiryId` ist die Vorgangs-ID der gesendeten Anfrage.

#### **Fehlercodes**

| **Code**              | **Beschreibung**                                                                      |
| --------------------- | ------------------------------------------------------------------------------------- |
| `captchaFailed`       | Für das Formular ist ein Captcha konfiguriert und das mitgegebene Captcha ist falsch. |
| `invalidFormId`       | Die angegebene Formular-ID ist ungültig.                                              |
| `createInquiryFailed` | Interner Fehler. Bitte wende dich an den WEBSALE-Support.                             |