> ## 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, simulierte Zahlungsfehler und die Test-API der WEBSALE Suche ä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 sowie die Schalter für Debugging, simulierte Zahlungsfehler und die Test-API der WEBSALE-Suche umschalten. Darüber hinaus können Sie 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,
  "searchTestApi": true
}
```

| **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. |
| `searchTestApi` | bool | `true`, wenn die Storefront die Test-API der WEBSALE Suche verwenden soll statt der produktiven. |

### Schalter `searchTestApi`

Der Schalter `searchTestApi` verändert den Shop selbst nicht. Er ist lediglich ein Signal an Ihre Storefront. Anhand seines Werts entscheidet die Storefront, ob sie die Test-API oder die produktive API der [WEBSALE Suche](/schnittstellen/search-api) anspricht.

<Note>
  Der Shop ruft die WEBSALE-Suche nicht selbst auf. Stattdessen speichert er den Schalter nur in der Session und gibt ihn in der Antwort weiter, damit Ihre Storefront darauf reagieren kann. Die Umschaltung auf die Test-API setzen Sie in Ihrer Storefront um.
</Note>

### 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 oder nur ein leeres Objekt `{}` 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,
  "searchTestApi": false
}
```

### POST testMode/activate

Mit dem folgenden Aufruf aktivieren Sie den Testmodus für die Session. Dabei können Sie optional das erweiterte Debugging, die Simulation fehlgeschlagener Zahlungen sowie das Signal für die Test-API der WEBSALE-Suche einschalten.

Der Aufruf legt den Startzustand des Testmodus fest. Schalter, die Sie nicht mitsenden, sind anschließend aus. Wenn der Testmodus für die Sitzung bereits aktiv ist, behalten nicht mitgesendete Schalter ihren bisherigen Wert.

```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,
  "searchTestApi": true
}
```

#### 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` |
| `searchTestApi` | bool | Signalisiert der Storefront, dass sie die Test-API der WEBSALE Suche verwenden soll statt der produktiven. Mehr dazu unter [Schalter searchTestApi](#schalter-searchtestapi).<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,
  "searchTestApi": true
}
```

#### 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 Werte `active`, `debug`, `makePaymentFail` und `searchTestApi` 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,
  "searchTestApi": false
}
```

### POST testMode/update

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

Der Aufruf ändert ausschließlich die Schalter, die Sie im Request mitsenden. Nicht genannte Schalter behalten ihren bisherigen Wert. Somit sind alle Schalter optional.

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

Dieser Request schaltet `debug` aus und lässt `makePaymentFail` und `searchTestApi` unverändert.

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "debug": 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`). Optional. |
| `makePaymentFail` | bool | Schaltet die Simulation fehlgeschlagener Zahlungen ein (`true`) oder aus (`false`). Optional. |
| `searchTestApi` | bool | Signalisiert der Storefront, dass sie die Test-API der WEBSALE Suche verwenden soll (`true`) oder die produktive (`false`). Optional. |

<Note>
  Mit `testMode/update` werden nur die Schalter geändert, die Sie mitsenden. Um einen Schalter auszuschalten, senden Sie ihn ausdrücklich mit dem Wert `false`. Ihn wegzulassen bedeutet „nicht ändern". Dadurch bleiben bestehende Integrationen auch dann unverändert lauffähig, wenn später weitere Schalter hinzugefügt werden.
</Note>

<Note>
  Für das Formular auf der Testmodus-Seite des Shops gilt das nicht. Die dort verwendete Aktion [TestModeChange](/frontend/referenz/aktionen/testmode#testmodechange) setzt beim Speichern immer alle Schalter. Der Grund ist, dass der Browser eine nicht angehakte Checkbox gar nicht erst mit schickt. Ein Schalter, der im Formular nicht angehakt ist, ist nach dem Speichern also aus.
</Note>

#### Beispiel-Response

Die Antwort zeigt den Zustand nach dem Beispiel-Request. Nur `debug` hat sich geändert.

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

#### 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.
* [Search API](/schnittstellen/search-api): Schnittstelle der WEBSALE Suche.


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