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 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
Testmodus aktivieren	testMode/activate
Testmodus deaktivieren	testMode/deactivate
Schalter des Testmodus ändern	testMode/update

---

​

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.

Endpunkt	Shopaktion	Konfiguration der Fehlertexte
testMode/activate	TestModeOn	actions.testModeOn
testMode/deactivate	TestModeOff	actions.testModeOff
testMode/update	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.

{
  "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 anspricht.

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.

​

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.

GET https://<ihr-shop>.de/api/v1/testMode/status

​

Parameterübersicht

​

Header-Parameter

Parameter	Beschreibung
x-session	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

​

Beispiel-Response

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

POST https://<ihr-shop>.de/api/v1/testMode/activate

​

Beispiel-Request

{
  "password": "test",
  "debug": true,
  "makePaymentFail": false,
  "searchTestApi": true
}

​

Parameterübersicht

​

Header-Parameter

Parameter	Beschreibung
x-session	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

​

Body-Parameter

Parameter	Typ	Beschreibung
password	string	Pflichtfeld Testmodus-Passwort. Es entspricht dem Wert unter general.testMode im Parameter password.
debug	bool	Schaltet das erweiterte Debugging ein. Default: false
makePaymentFail	bool	Simuliert Zahlungen im Testmodus als fehlgeschlagen. 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. Default: false

​

Beispiel-Response

{
  "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 fest.

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.

​

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.

POST https://<ihr-shop>.de/api/v1/testMode/deactivate

​

Parameterübersicht

​

Header-Parameter

Parameter	Beschreibung
x-session	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

​

Beispiel-Response

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

POST https://<ihr-shop>.de/api/v1/testMode/update

​

Beispiel-Request

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

{
  "debug": false
}

​

Parameterübersicht

​

Header-Parameter

Parameter	Beschreibung
x-session	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: 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.

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.

Für das Formular auf der Testmodus-Seite des Shops gilt das nicht. Die dort verwendete Aktion 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.

​

Beispiel-Response

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

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

---

​

Übergang in den Bestellablauf

Wenn Sie aus der Storefront über session/prepareRedirect 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 nach dem Feld verificationStatus filtern.
• Ist makePaymentFail eingeschaltet, laufen Zahlungen auch im Bestellablauf in den Fehlerfall.

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.

---

​

Weiterführende Links

• $wsTestMode: Zustand des Testmodus im Template abfragen.
• TestMode-Aktionen: Testmodus über Formulare im Template steuern.
• actions - Testmodus: Fehlertexte der Testmodus-Aktionen.
• general.testMode: Passwort, Template und Sperre bei fehlgeschlagenen Passworteingaben.
• Storefront API Session-Handling: Session erstellen und an das Template-Theme übergeben.
• Search API: Schnittstelle der WEBSALE Suche.