Storefront API Test mode

Query test mode via the Storefront API, activate it with a password, deactivate it and change the switches for debugging, simulated payment failures, the WEBSALE Search test API and template compilation.

With the test mode endpoints of the Storefront API, you can control the shop’s test mode from your own storefront. You can query the current state, activate test mode with the corresponding password and toggle the switches for debugging, simulated payment failures, the WEBSALE Search test API and template compilation. You can also deactivate test mode again.

Test mode applies to the session passed in the x-session header. All endpoints therefore require a valid session.

---

Supported methods

List of all supported methods.

Command	Endpoints	GET	POST	PUT	DELETE
Query the test mode state	testMode/status
Activate test mode	testMode/activate
Deactivate test mode	testMode/deactivate
Change test mode switches	testMode/update

---

Basic concept

Mapping to shop actions

Internally, the writing endpoints execute the same shop actions as the forms in the template. The error codes therefore come from these actions. You maintain their error texts in the configuration under actions - Test mode.

Endpoint	Shop action	Error text configuration
testMode/activate	TestModeOn	actions.testModeOn
testMode/deactivate	TestModeOff	actions.testModeOff
testMode/update	TestModeChange	actions.testModeChange

Response on success

On success, all four endpoints respond with status 200 and the current state of test mode. The structure corresponds to the $wsTestMode module.

{
  "active": true,
  "debug": true,
  "makePaymentFail": false,
  "searchTestApi": true,
  "compileTemplates": false
}

Field	Type	Description
active	bool	true if test mode is active for the session.
debug	bool	true if extended debugging is switched on.
makePaymentFail	bool	true if payments in test mode are deliberately simulated as failed.
searchTestApi	bool	true if the storefront should use the WEBSALE Search test API instead of the production API.
compileTemplates	bool	true if the shop compiles the views from the template sources on every request instead of loading them from the precompiled theme.

searchTestApi switch

The searchTestApi switch does not change the shop itself. It is merely a signal to your storefront. Based on its value, the storefront decides whether to address the test API or the production API of WEBSALE Search.

The shop does not call WEBSALE Search itself. Instead, it only stores the switch in the session and passes it on in the response so that your storefront can react to it. You implement the switch to the test API in your storefront.

compileTemplates switch

With the compileTemplates switch, the shop compiles the views from the current template sources on every request instead of loading them from the precompiled theme. This makes changes to the templates immediately visible in your session. The switch only takes effect while test mode is active for the session, and only for that session. In the template, you query the state via $wsTestMode.compileTemplates.

Compiling on every request slows down page loads. Therefore, switch compileTemplates off again as soon as you have checked the changes. You can do this with testMode/update and the value false.

General responses

Status / code	Description
Status 400	No valid session was passed. For testMode/activate and testMode/update, also if the request contains no body or only an empty object {}.
Status 404	The endpoint was called with an unsupported HTTP method.
invalidParameters	The request contains an unknown field or a field with the wrong data type.

---

Methods for test mode

GET testMode/status

The following call returns the current state of test mode for the session.

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

Parameter overview

Header parameters

Parameter	Description
x-session	Required field ID of the current session. More information: Storefront API Basics

Example response

{
  "active": false,
  "debug": false,
  "makePaymentFail": false,
  "searchTestApi": false,
  "compileTemplates": false
}

POST testMode/activate

With the following call, you activate test mode for the session. Optionally, you can switch on extended debugging, the simulation of failed payments, the signal for the WEBSALE Search test API and template compilation.

The call defines the initial state of test mode. Switches that you do not send are then off. If test mode is already active for the session, switches that are not sent keep their previous value.

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

Example request

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

Parameter overview

Header parameters

Parameter	Description
x-session	Required field ID of the current session. More information: Storefront API Basics

Body parameters

Parameter	Type	Description
password	string	Required field Test mode password. It corresponds to the value of the password parameter under general.testMode.
debug	bool	Switches on extended debugging. Default: false
makePaymentFail	bool	Simulates payments in test mode as failed. Default: false
searchTestApi	bool	Signals to the storefront that it should use the WEBSALE Search test API instead of the production API. For more information, see searchTestApi switch. Default: false
compileTemplates	bool	Compiles the views from the template sources on every request. For more information, see compileTemplates switch. Default: false

Example response

{
  "active": true,
  "debug": true,
  "makePaymentFail": false,
  "searchTestApi": true,
  "compileTemplates": false
}

Error codes

Code	Description
noPassword	No password was submitted.
invalidPassword	The submitted password is incorrect.
tooManyAttempts	Access to test mode is temporarily blocked for the caller’s IP address due to too many failed password attempts. You define the limits and lockout duration under general.testMode.

The lockout applies to the IP address, not to the session. A new session therefore does not lift it. During the lockout, the shop also rejects a correct password with tooManyAttempts.

POST testMode/deactivate

The following call deactivates test mode for the session. The shop resets the values active, debug, makePaymentFail, searchTestApi and compileTemplates to false. A request body is not required.

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

Parameter overview

Header parameters

Parameter	Description
x-session	Required field ID of the current session. More information: Storefront API Basics

Example response

{
  "active": false,
  "debug": false,
  "makePaymentFail": false,
  "searchTestApi": false,
  "compileTemplates": false
}

POST testMode/update

The following call changes the debug, makePaymentFail, searchTestApi and compileTemplates switches without leaving test mode. The prerequisite is that test mode was previously activated with the password for the respective session.

The call only changes the switches that you send in the request. Switches that are not specified keep their previous value. All switches are therefore optional.

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

Example request

This request switches debug off and leaves makePaymentFail, searchTestApi and compileTemplates unchanged.

{
  "debug": false
}

Parameter overview

Header parameters

Parameter	Description
x-session	Required field ID of the current session. More information: Storefront API Basics

Body parameters

Parameter	Type	Description
debug	bool	Switches extended debugging on (true) or off (false). Optional.
makePaymentFail	bool	Switches the simulation of failed payments on (true) or off (false). Optional.
searchTestApi	bool	Signals to the storefront that it should use the WEBSALE Search test API (true) or the production API (false). Optional.
compileTemplates	bool	Switches compiling the views from the template sources on every request on (true) or off (false). Optional.

With testMode/update, only the switches you send are changed. To switch a switch off, explicitly send it with the value false. Omitting it means “do not change”. This way, existing integrations continue to work unchanged even if further switches are added later.

This does not apply to the form on the shop’s test mode page. The TestModeChange action used there always sets all switches when saving. The reason is that the browser does not send an unchecked checkbox at all. A switch that is not checked in the form is therefore off after saving.

Example response

The response shows the state after the example request. Only debug has changed.

{
  "active": true,
  "debug": false,
  "makePaymentFail": false,
  "searchTestApi": true,
  "compileTemplates": false
}

Error codes

Code	Description
notAllowed	Test mode is not active for the session. Activate it first via testMode/activate.

---

Transition to the checkout

If you redirect from the storefront to a checkout of the template theme via session/prepareRedirect, test mode is retained because the shop takes over the session. The following applies to the rest of the process:

• Orders receive the verification status “Test”. You can recognize them in the order overview in the admin interface and filter by the verificationStatus field via the Admin Interface API.
• If makePaymentFail is switched on, payments also fail in the checkout.

The link from session/prepareRedirect is valid for 30 seconds. If it is called later, the shop creates a new, empty session. Test mode is no longer active in this session, and orders are executed as regular orders.

---

Related links

• $wsTestMode: query the test mode state in the template.
• TestMode actions: control test mode via forms in the template.
• actions - Test mode: error texts of the test mode actions.
• general.testMode: password, template and lockout after failed password attempts.
• Storefront API Session handling: create a session and pass it to the template theme.
• Search API: WEBSALE Search interface.