Slevomat.cz Partner API

The API is used to transfer information about vouchers between Zľavomat and the business partner's system. It allows the partner to verify the validity of vouchers and redeem vouchers within their own system. Therefore, the partner does not need to use the Partner Interface for this purpose.

Possible usage examples:

• A customer purchases a voucher where entering the code on the partner's website is required to provide the service when placing an order. Thanks to the API, the validity of the voucher is checked immediately after entering the code. Its value is then deducted in the partner's cart and at the same time the voucher is automatically redeemed in Zľavomat.
• The validity of vouchers can also be checked in the partner's reservation system in the same way, or the purchased credit of a certain value can be credited directly to the customer's account on the partner's website.

The Partner API requires a token that is unique for each partner and is sent with every request. If you want to use the Partner API, contact your/our sales representative.

Request format

The API endpoint is located at /api.

The request format is

<API endpoint URL>/<action>[<parameters>]

All requests are standard HTTP GET requests, i.e., a request to check the validity of a voucher may look like this:

https://www.zlavomat.sk/api/vouchercheck?code=1234-5677-77-111&token=123456789012345.

Response format

The server response is always in JSON format with the appropriate Content-type header. The basic structure of the response is as follows.

{
 "result": true,
 "data": {
 ...
 },
 "error": {
 "code": 0,
 "message": null
 }
}

The value of the result item is true (in case of success) or false (in case of error). In case of error, the error item contains the error code (code) and its description (message). In addition to the indication in the error field, the system also returns the corresponding HTTP status code (400, 401, 403, 404) in case of an error.

The data item contains the data returned by the called action and its content is individual.

All dates are in the format YYYY-MM-DDTHH:MM:SSZ (ISO8601; e.g., 2011⁠–⁠01⁠–⁠01T10:10:10+0­2:00).

Voucher validity check

• action: voucherCheck
• parameters: token (required; unique partner token), code (required; voucher code)

There are three test voucher codes:

• 1234⁠–⁠5677⁠–⁠77⁠–⁠111 (paid, unused),
• 2234⁠–⁠5688⁠–⁠88⁠–⁠222 (paid, used),
• 3234⁠–⁠5699⁠–⁠99⁠–⁠333 (unpaid, unused).

If the application uses one of these codes, the server will return the corresponding response (in the case of a paid and unused voucher, it will also return sample voucher and action data).

Response data format

{
 "token": <authentication token>,
 "code": <voucher code>,
 "voucherData": <voucher data>
}

The voucherData parameter contains the voucher definition in the following format.

{
 "id": <voucher ID>,
 "orderId": <order ID>,
 "title": <voucher name>,
 "ordered": <order date and time; date and time>,
 "paidDate": <order payment date; date>
 "validFrom": <voucher validity start; date>,
 "validTo": <voucher validity end; date>,
 "key": <voucher code>,
 "code": <voucher code>,
 "product": <action ID>,
 "productName": <action name>,
 "variant": <action variant ID>,
 "variantName": <action variant name>,
 "imageUrl": <image URL>,
 "smallImageUrl": <thumbnail URL>,
 "productUrl": <action URL>
}

The variant and variantName items contain the ID and name of the ordered action variant, if the given action contains variants. If not, both attributes have the value NULL.

Error states

• code 1101 (HTTP status code 400): authentication token or voucher code was not provided,
• code 1102 (HTTP status code 403): the given token is not in the database,
• code 1103 (HTTP status code 404): voucher with the given code does not exist,
• code 1104 (HTTP status code 401): the order on the basis of which the voucher was issued has not been paid,
• code 1105 (HTTP status code 401): the voucher has already been redeemed,
• code 1106 (HTTP status code 401): the voucher has been refunded,
• code 1107 (HTTP status code 401): the order or voucher has been canceled,
• code 1108 (HTTP status code 401): the action has already been settled with the partner; it is not possible to redeem more vouchers,
• code 1109 (HTTP status code 401): the validity of vouchers for this action has not started yet.
• code 1111 (HTTP status code 500): internal server error

Request example

https://www.zlavomat.sk/api/vouchercheck?code=1234-5677-77-111&token=123456789012345

Response example

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <voucher name>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Voucher redemption

• action: voucherApply
• parameters: token (required; unique partner token), code (required; voucher code)

Attempts to redeem the voucher with the given code.

For testing purposes, it is possible to use the test voucher number. In that case, the voucher will not actually be redeemed, but the system will return a response as if it had been.

Response data format

The response format is exactly the same as in the case of voucher validity check.

Error states

• code 1201 (HTTP status code 400): authentication token or voucher code was not provided,
• code 1202 (HTTP status code 403): the given token is not in the database,
• code 1203 (HTTP status code 404): voucher with the given code does not exist,
• code 1204 (HTTP status code 401): the order on the basis of which the voucher was issued has not been paid,
• code 1205 (HTTP status code 401): the voucher has already been redeemed,
• code 1206 (HTTP status code 401): the voucher has been refunded,
• code 1207 (HTTP status code 401): the order or voucher has been canceled,
• code 1208 (HTTP status code 401): the action has already been settled with the partner; it is not possible to redeem more vouchers,
• code 1209 (HTTP status code 401): the validity of vouchers for this action has not started yet.
• code 1211 (HTTP status code 500): internal server error

Request example

https://www.zlavomat.sk/api/voucherapply?code=1234-5677-77-111&token=123456789012345

Response example

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <voucher name>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Note: For using the Partner API to deduct value or products in the cart, consider including more attributes of the voucherData parameter. This is especially important when you have several ongoing actions with different values of offered products. We recommend using especially the product or variant attributes.