Slevomat.cz Partner API

The API is used to transfer information about vouchers between Zlavomat and the business partner's system. It allows the partner to verify the validity of vouchers in their system and redeem vouchers. The partner does not have to use the Partner Interface for this purpose.

Possible examples of use:

• The customer purchases a voucher, where the condition for providing the service is to enter the code on the partner's website when creating the order. Thanks to the API, after this entry, the voucher validity is immediately checked. Its value is then deducted from the partner's cart and the voucher is automatically redeemed at the Zlavomot.
• In the same way, the validity of vouchers can also be verified in the partner's reservation system or the customer can upload a purchased credit of a certain value directly on the partner's website.

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

Request format

The API access point is located at /api.

The request format is

<URL přístupového bodu>/<akce>[<pa­rametry>]

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

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 corresponding Content-type header. The basic structure of the answer 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 the event of an error, the error item contains the error code ( code ) and its description ( message ). In addition to the indication in the error field, the system returns the corresponding HTTP status code (400, 401, 403, 404) in the event of an error.

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

All data are in the format YYYY-MM-DDTHH:MM:SSZ (ISO8601; eg 2011–01–01T10:10:10+02:00).

Voucher validity verification

• action: voucherCheck
• parameters: token (mandatory; unique partner token), code (mandatory; 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": <autentizační token>,
 "code": <kód voucheru>,
 "voucherData": <data voucheru>
}

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

{
 "id": <ID voucheru>,
 "orderId": <ID objednávky>,
 "title": <název voucheru>,
 "ordered": <datum a čas objednávky; datum a čas>,
 "paidDate": <datum zaplacení objednávky; datum>
 "validFrom": <začátek platnosti voucheru; datum>,
 "validTo": <konec platnosti voucheru; datum>,
 "key": <kód voucheru>,
 "code": <kód voucheru>,
 "product": <ID akce>,
 "productName": <název akce>,
 "variant": <ID varianty akce>,
 "variantName": <název varianty akce>,
 "imageUrl": <URL obrázku>,
 "smallImageUrl": <URL náhledu>,
 "productUrl": <URL akce>
}

Variant items or variantName contain ID or the name of the ordered variant of the action, if the given action contains variants. If not, both attributes are NULL .

Error states

• code 1101 (HTTP status code 400): authentication token or voucher code was not entered,
• 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 was not paid,
• code 1105 (HTTP status code 401): the voucher has already been used,
• code 1106 (HTTP status code 401): the voucher has been refunded,
• code 1107 (HTTP status code 401): the order or voucher has been cancelled,
• code 1108 (HTTP status code 401): the action has already been billed to the partner; it is not possible to apply other vouchers,
• code 1109 (HTTP status code 401): the validity of vouchers for this event has not yet started.
• code 1111 (HTTP status code 500): internal server error

Example of a request

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

Example answer

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <název voucheru>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Voucher redemption

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

An attempt will be made to redeem the voucher of the given code.

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

Response data format

The format of the answer is exactly the same as in the case of checking the validity of the voucher.

Error states

• code 1201 (HTTP status code 400): authentication token or voucher code was not entered,
• 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 was not paid,
• code 1205 (HTTP status code 401): the voucher has already been used,
• code 1206 (HTTP status code 401): the voucher has been refunded,
• code 1207 (HTTP status code 401): the order or voucher has been cancelled,
• code 1208 (HTTP status code 401): the action has already been billed to the partner; it is not possible to apply other vouchers,
• code 1209 (HTTP status code 401): the validity of vouchers for this event has not yet started.
• code 1211 (HTTP status code 500): internal server error

Example of a request

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

Example answer

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <název voucheru>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Note: To use the Partner API to read the value or products in the cart, consider including more attributes of the voucherData parameter. It is especially important. at the moment when you have several running campaigns with different value of the offered products. We recommend using mainly the product or variant attributes.