This API is for providing Slevomat.cz a voucher code after a customer pays an order for a deal. Usually, Slevomat.cz generates its own voucher code but with using this API, our business partner can be let known about the order and generate his own custom voucher code for the customer.
All requests are performed over HTTPS protocol (which requires the business partner's server to support HTTPS and have a valid certificate) and all data must be formatted as JSON.
Changelog
01. 03. 2017 – handling invalid request section added
10. 02. 2017 – initial version
Enabling the API
All requests are performed by Slevomat.cz application sending a request to the partner's server. The request will contain X-RequestToken HTTP header with a secret string. This string must be checked by the partner's server in order to guarantee security. This secret string is known only by Slevomat.cz and the partner.
To enable the API partner has to ask Slevomat.cz and provide a URL where the API will be, for example:
https://example.com/slevomat-external-voucher-code/generate
Once Slevomat.cz enables the API for the partner and gives the partner the X-RequestToken value, it's in testing mode only, meaning no real orders are going to perform a request to get a custom voucher code. But it enables the partner to develop and test the API on his server with the provided X-RequestToken value.
After the API on partner's server is developed and tested, Slevomat.cz will switch the mode to real orders. Orders for deals that started selling after the switch will request the partner's API for custom voucher codes.
Generating voucher code
When an order for a deal is paid, Slevomat.cz will send a POST request to partner's server to generate a voucher code and will give the partner some information about the order. This request will be sent individually for each unit sold.
The request contains required voucher code prefix. The generated voucher code must start with this prefix.
The request body will look like this:
{ "uuid": "91987a73-095c-4b94-bd38-f6ffd4ab86a7", "deal": { "product_id": 123, "product_name": "Aktivní dovolená: 4 až 6 dní s all inclusive v Rakousku. 2 děti do 8,9 let zdarma!", "variant_id": 456, "variant_name": "1 osoba | 4 dny (3 noci) | Období So 13. 5. – So 24. 6. 2017, Ne 27. 8. – Ne 5. 11. 2017" }, "customer": { "email": "cu******@ex*****.com" }, "voucherCodePrefix": "LIN", "repeatReason": 1 }The server should respond with HTTP status code 200 and the response body with the generated voucher code must look like this:
{ "voucherCode": "LIN1234567890" }The server must respond within 10 seconds, otherwise the request is marked as unsuccessful. Generated voucher code must begin with a given prefix and must be unique. There are other reasons why we might not accept the generated voucher code.
When the request is not successful, it is repeated with the reason in the repeatReason field until it's successful. This field will contain one of the following values:
| Repeat reason | Description |
|---|---|
| 1 | First attempt. |
| 2 | Connection to the server was not successful. This can either mean invalid HTTPS certificate or that the network was down. |
| 3 | Server did not respond in time. |
| 4 | Server responded with a non-200 HTTP status code. |
| 5 | Server responded with HTTP 200, but the response body did not contain JSON or the JSON did not contain voucherCode key. |
| 6 | Generated voucher code did not contain required prefix. |
| 7 |
Generated voucher code contained invalid characters. Only valid characters are: [a-zA-Z0-9-]+.
|
| 8 | Generated voucher code was not unique. |
Request body will always contain the same uuid identifier as the previous request for generating the voucher code for the same customer order.
Handling invalid request
When there will occur a request, that does not meet security requirements, i.e. contain invalid X-RequestToken, the server must respond with HTTP code 403 Forbidden.
Testing API implementation
Sign in as our partner to see your API status and test and verify your API implementation.
