Storefront API Test mode - WEBSALE Dokumentation

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 test mode password and toggle the switches for debugging, simulated payment failures and the WEBSALE Search test API. 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
}

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.

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

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
}

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 and the signal for the WEBSALE Search test API. 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
}

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`

Example response

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

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 and searchTestApi 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
}

POST testMode/update

The following call changes the debug, makePaymentFail and searchTestApi 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 and searchTestApi 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.

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
}

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.

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

​Supported methods

​Basic concept

​Mapping to shop actions

​Response on success

​searchTestApi switch

​General responses

​Methods for test mode

​GET testMode/status

​Parameter overview

​Header parameters

​Example response

​POST testMode/activate

​Example request

​Parameter overview

​Header parameters

​Body parameters

​Example response

​Error codes

​POST testMode/deactivate

​Parameter overview

​Header parameters

​Example response

​POST testMode/update

​Example request

​Parameter overview

​Header parameters

​Body parameters

​Example response

​Error codes

​Transition to the checkout

​Related links

Supported methods

Basic concept

Mapping to shop actions

Response on success

`searchTestApi` switch

General responses

Methods for test mode

GET testMode/status

Parameter overview

Header parameters

Example response

POST testMode/activate

Example request

Parameter overview

Header parameters

Body parameters

Example response

Error codes

POST testMode/deactivate

Parameter overview

Header parameters

Example response

POST testMode/update

Example request

Parameter overview

Header parameters

Body parameters

Example response

Error codes

Transition to the checkout

Related links