Slevomat.cz Partner API

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

Possible examples of use:

• A customer purchases a voucher, where the condition for the service is to enter a code on the partner's website when creating the order. Thanks to the API, the voucher is immediately checked for validity after this entry. Its value is then deducted in the partner's cart and at the same time the voucher is automatically redeemed in Discountomat.
• In the same way, it is also possible to verify the validity of vouchers in the partner's booking system or to upload a purchased credit of a certain value to the customer directly on the partner's website.

The Partner API requires a token that is unique for each partner and is sent as part of each request. 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. a request to check the validity of a voucher might 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 corresponding 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 an error, the error entry 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 case of an error.

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

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

Voucher validation

• 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 event 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>
}

The variant and variantName fields contain the ID or name of the ordered variant of the event, if the event contains variants. If not, both attributes are NULL.

Error conditions

• Code 1101 (HTTP status code 400): authentication token or voucher code was not entered,
• Code 1102 (HTTP status code 403): the token is not in the database,
• code 1103 (HTTP status code 404): the voucher with the given code does not exist,
• code 1104 (HTTP status code 401): the order on 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 cancelled,
• code 1108 (HTTP status code 401): the event has already been billed to the partner; no further vouchers can be claimed,
• code 1109 (HTTP status code 401): the vouchers for this event have not yet started to expire.
• code 1111 (HTTP status code 500): internal server error

Example request

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

Example of response

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

Redeeming a voucher

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

Attempts to redeem the voucher of the given code.

The test voucher number can be used for testing purposes. In this case, the voucher will not be redeemed, but the system will return a response as if it had been redeemed.

Response data format

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

Error conditions

• Code 1201 (HTTP status code 400): authentication token or voucher code has not been entered,
• code 1202 (HTTP status code 403): the token is not in the database,
• code 1203 (HTTP status code 404): the voucher with the given code does not exist,
• code 1204 (HTTP status code 401): the order on 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 cancelled,
• code 1208 (HTTP status code 401): the event has already been billed to the partner; no further vouchers can be claimed,
• code 1209 (HTTP status code 401): the vouchers for this event have not yet started to expire.
• code 1211 (HTTP status code 500): internal server error

Example request

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

Example of response

{
 "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 deduct the value or products in your cart, consider including multiple attributes to the voucherData parameter. This is important, especially if you want to use the voucher parameter. This is important when you have multiple running promotions with different product values. In particular, we recommend using product or variant attributes.