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

> Testmodus über die Storefront API abfragen, per Passwort aktivieren, deaktivieren und die Schalter für Debugging und simulierte Zahlungsfehler ändern.

Mit den Testmodus-Endpunkten der Storefront-API können Sie den [Testmodus](/frontend/referenz/module/wstestmode) des Shops aus einer eigenen Storefront heraus steuern. Sie können den aktuellen Zustand abfragen, den Testmodus mit dem Testmodus-Passwort aktivieren, Debugging und simulierte Zahlungsfehler umschalten und den Testmodus wieder deaktivieren.

Der Testmodus gilt für die Session, die im Header `x-session` übergeben wird. Alle Endpunkte setzen deshalb eine gültige Session voraus.

***

## Unterstützte Methoden

Angabe aller unterstützten Methoden.

| **Befehl** | **Endpunkte** | **GET** | **POST** | **PUT** | **DELETE** |
| - | - | - | - | - | - |
| Zustand des Testmodus abfragen | `testMode/status` | <Icon icon="check" /> | <Icon icon="ban" color="#DC2626" /> | <Icon icon="ban" color="#DC2626" /> | <Icon icon="ban" color="#DC2626" /> |
| Testmodus aktivieren | `testMode/activate` | <Icon icon="ban" color="#DC2626" /> | <Icon icon="check" /> | <Icon icon="ban" color="#DC2626" /> | <Icon icon="ban" color="#DC2626" /> |
| Testmodus deaktivieren | `testMode/deactivate` | <Icon icon="ban" color="#DC2626" /> | <Icon icon="check" /> | <Icon icon="ban" color="#DC2626" /> | <Icon icon="ban" color="#DC2626" /> |
| Schalter des Testmodus ändern | `testMode/update` | <Icon icon="ban" color="#DC2626" /> | <Icon icon="check" /> | <Icon icon="ban" color="#DC2626" /> | <Icon icon="ban" color="#DC2626" /> |

***

## Grundkonzept

### Zuordnung zu den Shopaktionen

Die schreibenden Endpunkte führen intern dieselben Shop-Aktionen aus wie die Formulare im Template. Die Fehlercodes stammen daher aus diesen Aktionen. Ihre Fehlertexte pflegen Sie in der Konfiguration unter [actions - Testmodus](/konfiguration/actions-fehlertexte-e-mails/actions-testmodus).

| **Endpunkt** | **Shopaktion** | **Konfiguration der Fehlertexte** |
| - | - | - |
| `testMode/activate` | [TestModeOn](/frontend/referenz/aktionen/testmode#testmodeon) | `actions.testModeOn` |
| `testMode/deactivate` | [TestModeOff](/frontend/referenz/aktionen/testmode#testmodeoff) | `actions.testModeOff` |
| `testMode/update` | [TestModeChange](/frontend/referenz/aktionen/testmode#testmodechange) | `actions.testModeChange` |

### Antwort bei Erfolg

Alle vier Endpunkte antworten bei Erfolg mit dem Status 200 und dem aktuellen Zustand des Testmodus. Der Aufbau entspricht dem Modul [\$wsTestMode](/frontend/referenz/module/wstestmode).

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "active": true,
  "debug": true,
  "makePaymentFail": false
}
```

| **Feld** | **Typ** | **Beschreibung** |
| - | - | - |
| `active` | bool | `true`, wenn der Testmodus für die Session aktiv ist. |
| `debug` | bool | `true`, wenn das erweiterte Debugging eingeschaltet ist. |
| `makePaymentFail` | bool | `true`, wenn Zahlungen im Testmodus absichtlich als fehlgeschlagen simuliert werden. |

### Allgemeine Antworten

| **Status / Code** | **Beschreibung** |
| - | - |
| Status 400 | Es wurde keine gültige Session übergeben. Bei `testMode/activate` und `testMode/update` auch dann, wenn der Request keinen Body enthält. |
| Status 404 | Der Endpunkt wurde mit einer nicht unterstützten HTTP-Methode aufgerufen. |
| `invalidParameters` | Der Request enthält ein unbekanntes Feld oder ein Feld mit falschem Datentyp. |

***

## Methoden für den Testmodus

### GET testMode/status

Folgender Aufruf liefert den aktuellen Zustand des Testmodus für die Session.

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

#### Parameterübersicht

#### Header-Parameter

| **Parameter** | **Beschreibung** |
| - | - |
| `x-session` | **Pflichtfeld**<br />ID der aktuellen Session.<br />Mehr Informationen dazu: [Storefront API Basics](/schnittstellen/storefront-api/storefront-api-basics) |

#### Beispiel-Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "active": false,
  "debug": false,
  "makePaymentFail": false
}
```

### POST testMode/activate

Mit folgendem Aufruf aktivieren Sie den Testmodus für die Session. Dabei können Sie optional das erweiterte Debugging und die Simulation fehlgeschlagener Zahlungen einschalten.

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

#### Beispiel-Request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "password": "test",
  "debug": true,
  "makePaymentFail": false
}
```

#### Parameterübersicht

#### Header-Parameter

| **Parameter** | **Beschreibung** |
| - | - |
| `x-session` | **Pflichtfeld**<br />ID der aktuellen Session.<br />Mehr Informationen dazu: [Storefront API Basics](/schnittstellen/storefront-api/storefront-api-basics) |

#### Body-Parameter

| **Parameter** | **Typ** | **Beschreibung** |
| - | - | - |
| `password` | string | **Pflichtfeld**<br />Testmodus-Passwort. Es entspricht dem Wert unter [general.testMode](/konfiguration/general-allgemeine-shopeinstellungen#general-testmode-testmodus) im Parameter `password`. |
| `debug` | bool | Schaltet das erweiterte Debugging ein.<br />Default: `false` |
| `makePaymentFail` | bool | Simuliert Zahlungen im Testmodus als fehlgeschlagen.<br />Default: `false` |

#### Beispiel-Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "active": true,
  "debug": true,
  "makePaymentFail": false
}
```

#### Fehlercodes

| **Code** | **Beschreibung** |
| - | - |
| `noPassword` | Es wurde kein Passwort übermittelt. |
| `invalidPassword` | Das übermittelte Passwort ist falsch. |
| `tooManyAttempts` | Der Zugang zum Testmodus ist für die IP-Adresse des Aufrufers wegen zu vieler fehlgeschlagener Passworteingaben vorübergehend gesperrt. Grenzwerte und Sperrdauer legen Sie unter [general.testMode](/konfiguration/general-allgemeine-shopeinstellungen#general-testmode-testmodus) fest. |

<Note>
  Die Sperre gilt für die IP-Adresse, nicht für die Session. Eine neue Session hebt sie deshalb nicht auf. Während der Sperre lehnt der Shop auch ein richtiges Passwort mit `tooManyAttempts` ab.
</Note>

### POST testMode/deactivate

Folgender Aufruf deaktiviert den Testmodus für die Session. Dabei setzt der Shop die drei Werte `active`, `debug` und `makePaymentFail` auf `false` zurück. Ein Request-Body ist nicht erforderlich.

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

#### Parameterübersicht

#### Header-Parameter

| **Parameter** | **Beschreibung** |
| - | - |
| `x-session` | **Pflichtfeld**<br />ID der aktuellen Session.<br />Mehr Informationen dazu: [Storefront API Basics](/schnittstellen/storefront-api/storefront-api-basics) |

#### Beispiel-Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "active": false,
  "debug": false,
  "makePaymentFail": false
}
```

### POST testMode/update

Folgender Aufruf ändert die Schalter `debug` und `makePaymentFail`, ohne den Testmodus zu verlassen. Voraussetzung ist, dass der Testmodus für die jeweilige Session zuvor mit dem Passwort aktiviert wurde.

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

#### Beispiel-Request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "debug": true,
  "makePaymentFail": false
}
```

#### Parameterübersicht

#### Header-Parameter

| **Parameter** | **Beschreibung** |
| - | - |
| `x-session` | **Pflichtfeld**<br />ID der aktuellen Session.<br />Mehr Informationen dazu: [Storefront API Basics](/schnittstellen/storefront-api/storefront-api-basics) |

#### Body-Parameter

| **Parameter** | **Typ** | **Beschreibung** |
| - | - | - |
| `debug` | bool | Schaltet das erweiterte Debugging ein (`true`) oder aus (`false`). |
| `makePaymentFail` | bool | Schaltet die Simulation fehlgeschlagener Zahlungen ein (`true`) oder aus (`false`). |

<Warning>
  `testMode/update` setzt alle Einstellungen zurück. Ein fehlender Schalter Schalter im Request wird auf `false` gesetzt. Das entspricht dem Verhalten einer nicht angehakten Checkbox im Formular. Senden Sie deshalb immer beide Schalter mit, auch den, den Sie nicht ändern möchten.
</Warning>

#### Beispiel-Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "active": true,
  "debug": true,
  "makePaymentFail": false
}
```

#### Fehlercodes

| **Code** | **Beschreibung** |
| - | - |
| `notAllowed` | Der Testmodus ist für die Session nicht aktiv. Aktivieren Sie ihn zuerst über [testMode/activate](#post-testmodeactivate). |

***

## Übergang in den Bestellablauf

Wenn Sie aus der Storefront über [session/prepareRedirect](/schnittstellen/storefront-api/storefront-api-session-handling#post-sessionprepareredirect) in einen Bestellablauf des Template-Themes weiterleiten, bleibt der Testmodus erhalten, weil der Shop die Session übernimmt. Für den weiteren Ablauf gilt:

* Bestellungen erhalten den Verifizierungsstatus „Test“. Sie erkennen sie in der Bestellübersicht im Admin Interface und können über die [Admin-Interface-API](/schnittstellen/admin-interface-api/api-referenz-bestellungen#get-orders) nach dem Feld `verificationStatus` filtern.
* Ist `makePaymentFail` eingeschaltet, laufen Zahlungen auch im Bestellablauf in den Fehlerfall.

<Warning>
  Der Link aus `session/prepareRedirect` ist **30 Sekunden** gültig. Wird er später aufgerufen, legt der Shop eine neue, leere Session an. In dieser ist der Testmodus nicht mehr aktiv und Bestellungen werden als reguläre Bestellungen ausgeführt.
</Warning>

***

## Weiterführende Links

* [\$wsTestMode](/frontend/referenz/module/wstestmode): Zustand des Testmodus im Template abfragen.
* [TestMode-Aktionen](/frontend/referenz/aktionen/testmode): Testmodus über Formulare im Template steuern.
* [actions - Testmodus](/konfiguration/actions-fehlertexte-e-mails/actions-testmodus): Fehlertexte der Testmodus-Aktionen.
* [general.testMode](/konfiguration/general-allgemeine-shopeinstellungen#general-testmode-testmodus): Passwort, Template und Sperre bei fehlgeschlagenen Passworteingaben.
* [Storefront API Session-Handling](/schnittstellen/storefront-api/storefront-api-session-handling): Session erstellen und an das Template-Theme übergeben.


## Related topics

- [$wsTestMode - Testmodus](/frontend/referenz/module/wstestmode.md)
- [Changelog](/changelog.md)
- [Storefront API Kundenkonto](/schnittstellen/storefront-api/storefront-api-kundenkonto.md)
- [Storefront API](/schnittstellen/storefront-api.md)
- [storefrontApi - Storefront-API](/konfiguration/storefrontapi-storefront-api.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.