The API is used to transfer information about orders between the Discount Machine and the business partner's system. The API requires the implementation of two-way communication – the Discount Machine system calls the partner's API and the partner calls the Discount Machine API.
Orders exported to the partner API can no longer be manipulated in the Zlavomat partner interface, only viewed. Exported orders can now only be manipulated via the API.
All requests must be made over HTTPS and all data is in JSON format.
API accessibility
You can access the API in the Settings tab of your partner interface. To retrieve data, you must enter the root URL of the partner part of the API for use in the direction Zlavomat → Partner, e.g.
https://example.com/slevomat-zbozi-apiAccess data will only be displayed when the API is accessed, so keep it safe.
Once the API is made available, the system will start exporting newly created orders to it.
Initial data export
To transfer existing orders at the moment the API is made available, it is possible to use a one-time export to CSV in the partner interface.
When you already have existing orders (created before the API was made available) in your own system and you want to start working with them via the API, use the "Start working with marked orders via API" function in the "Bulk actions with orders" menu.
Description of common HTTP responses
200 OK– the request was successfully processed204 No Content– the request was successfully processed, the response has no content400 Bad Request– the request is not valid – there may be missing or invalid parameters compared to the specification403 Forbidden– client authorization failed404 Not Found– endpoint or requested data not found405 Method Not Allowed– the endpoint does not support this HTTP protocol method422 Unprocessable Entity– expected error while processing the request (see section Error states )500 Internal Server Error– an error occurred on the server side502 Bad Gateway– an error occurred on the server side503 Service Unavailable– the server is in maintenance mode (a new version deployment or planned downtime may be in progress)504 Gateway Timeout– an error occurred on the server side
HTTP 5×x responses do not have to use JSON format.
In case of errors4xx There is an error in the outgoing request and it needs to be fixed before trying again.
Errors5xx indicate server errors and the request can be repeated without changing it. In the case of503 the caller should respect the response headerRetry-After and repeat the next attempt only after the time specified in the header has elapsed.
Order statuses
The order is always in one of the following statuses:
| Status value | Description |
| 1 | New paid order |
| 2 | It is being prepared. |
| 3 | On the way (only orders with shipping) |
| 4 | Preparing for personal collection – e.g. transport to a branch is in progress |
| 5 | Ready for personal collection |
| 6 | Delivered to customer – awaiting customer confirmation |
| 7 | Delivered and confirmed by customer |
| 8 | The customer refused to confirm receipt of the order. |
| 9 | Cancelled order |
The customer is informed of any change in status by email.
An order does not necessarily have to go through all statuses to be successfully delivered; from the "New paid order" status, it is possible to go straight to "On the way" / "Ready for personal collection" and then to "Delivered to customer – awaiting customer confirmation". However, using all statuses leads to better customer information about the progress of the order and we recommend it.
Error states
In the case of HTTP 4×x codes, the response always contains a keystatus (see code list below) and fieldmessages with text descriptions of errors.
| Status value | Description |
| 1 | Invalid request – missing or invalid values |
| 2 | Invalid login details |
| 3 | Non-existent order |
| 4 | Non-existent order item |
| 5 | Order transition to unauthorized status |
| 6 | Invalid cancellation – canceling more items than exist |
| 7 | Another error |
| 8 | The order has not yet been exported to the partner API – it is not possible to manipulate it through the API |
| 9 | To automatically set the status to "Goods delivered to customer", it is necessary to have the shipment automatically set to the status "Goods ready for pickup" |
Sample:
{ "status": 3, "messages": [ "Order #1234 was not found." ] }Data types
The data types of individual keys in requests and responses are always described for specific endpoints. Unless otherwise noted, the value in quotes"" is always a required string. Unless otherwise specified, the numeric value is always a required integer.
Communication Discount Machine ⇒ Partner
This part of the API is implemented on the partner's side and Zlavovamat calls it.
The required API root URL will be shared by the partner, it should be in the form
https://www.example.com/slevomat-zbozi-api/v1Authorization of requests
When the API is turned on, the partner receivespartner_api_secret , which proves that incoming requests really come from Zlavomat.
This parameter is passed in the HTTP headerX-PartnerApiSecret .
Test interface
The discount machine includes functionality to call the API on the partner side and display the response. The root URL specified by the partner when making the API available is attached to-test , so as part of testing, the API is called at, for example,
https://example.com/slevomat-zbozi-api-testto avoid mixing test data with live orders.
Partner API testing is done using POST requests to the following addresses:
– New orderhttps://www.zlavomat.sk/test-zbozi-partner-api/v1/new-order
– Bulk update of expected shipping dateshttps://www.zlavomat.sk/test-zbozi-partner-api/v1/update-shipping-dates
– Changing the order status to "Delivered to customer – awaiting customer confirmation"https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/mark-delivered
– Changing the order status to "Ready for personal collection"https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/ready-for-pickup
– Delivery confirmationhttps://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/confirm-delivery
– Refusal to accepthttps://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/reject-delivery
– Cancelhttps://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/cancel
Part of the URL<orderId> replace with any order number, requests to the partner API are made with this order number.
Requests to this test interface need to be authorized with headersX-PartnerToken andX-ApiSecret .
When testing a partner API call, the system sends a headerX-PartnerApiSecret just like in live operation.
The data sent with a new order is of a test nature and randomly generated.
In case of sending an order cancellation, it is necessary to include the JSON field in the POST request body.items (in the same format as the API sends), which the test interface validates and forwards to the partner API in the same form.
New order
The request contains the data of the newly created order.
Orders are always uniquezlavomatId If a duplicate arrives in the APIzlavomatId , the partner API should ignore the request (the first request made by Zľavomat was evaluated as unsuccessful and therefore we are repeating it) and also respond with HTTP 204.
created is a date in ISO 8601 format, i.e.YYYY-MM-DD'T'HH:mm:ss+zz:zz .
productId contains the action ID, variantId ID of the purchased variant.
OptionalinternalId means the internal ID entered for the action variant when creating it in the partner interface. It is used to identify the product in the partner system.
InbillingAddress (billing address) only the name ( is required)name ) of the customer.
InshippingAddress (delivery address) is an optional company (company ). In case of delivery to the addressshippingAddress contains the customer's address, in the case of personal collection, the address of the store where the customer will pick up the goods.
Keydelivery .type can take on valuesaddress (delivery to address) orpickup (personal collection).delivery .name contains the name of the transport or the name of the operation.
delivery .expectedShippingDate (expected date of dispatch) anddelivery .expectedDeliveryDate (estimated delivery date) is the data in the formatYYYY-MM-DD .
Keyweight contains the weight of the order in kilograms. If we do not know the weight of all items in the order, it takes the valuenull .
POST /order/$slevomatId
{ "slevomatId": "480058070336", "created": "2021–09–06T16:39:02+02:00", "items": [ { "slevomatId": "7767", "productId": "25", "variantId": "194", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "4764573102", "productId": "3065", "variantId": "385", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": null, "street": null, "city": null, "postalCode": null, "country": null }, "shippingAddress": { "name": "Petr Novák", "company": null, "street": "Strašnická 8", "city": "Praha", "postalCode": "100 00", "phone": "+420777888999" }, "delivery": { "type": "address", "name": "PPL", "expectedShippingDate": "2021–09–08", "expectedDeliveryDate": "2021–09–11", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@example.com" }, "weight": 1.2 }POST /order/$slevomatId
{ "slevomatId": "286238184713", "created": "2021–09–06T16:39:02+02:00", "items": [ { "slevomatId": "3461", "productId": "9", "variantId": "136", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "2320086446", "productId": "2855", "variantId": "7027", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": "Novák a syn", "street": "Vodičkova 32", "city": "Praha 1", "postalCode": "110 00", "country": "Česko" }, "shippingAddress": { "name": "Provozovna Jahodová", "company": null, "street": "Jahodová 33", "city": "Praha 10", "postalCode": "100 00", "phone": "+420222888999", "deliveryPremise": { "id": 45445, "name": "Provozovna Jahodová" } }, "delivery": { "type": "pickup", "name": "Osobní odběr na provozovně", "expectedShippingDate": "2021–09–07", "expectedDeliveryDate": "2021–09–07", "price": 0.0 }, "status": 1, "customer": { "email": "petr.novak@example.com" }, "weight": 1.2 }Bulk update of expected shipping dates
If the deals manager, at the partner's request, moves the shipping dates of selected orders in bulk, the system informs the partner API about this update.
The data sent includes a field with the order ID and a new expected shipping date.
POST /update-shipping-dates
{ "expectedShippingDate": "2021–09–06", "slevomatIds": [ "123456", "45454544" ] }Cancel
Cancellations can be created both on the Zlavomat side and on the partner system. This endpoint handles the creation of cancellations on the Zlavomat side and its transfer to the partner system.
Creates a cancellation of order items in the specified quantity. If the entire order is to be canceled, all items with the corresponding quantity are listed.
Individual items can also be partially cancelled (e.g. 1 piece out of two).
Cancellation note (note ) is optional.
POST /order/$slevomatId/cancel
{ "items": [ { "slevomatId": "1212", "amount": 1 }, { "slevomatId": "4545454", "amount": 2 } ], "note": "storno v zákonné lhůtě" }Delivery confirmation
After you mark an order as "Delivered to Customer", we will request confirmation from the customer that they have actually received it. When an order is marked as received, this endpoint will be called.
POST /order/$slevomatId/confirm-delivery
{}Refusal to accept
POST /order/$slevomatId/reject-delivery
{ "rejectionReason": "Důvod odmítnutí zákazníkem" }Changing the order status to "Ready for personal collection"
This endpoint will be called if the previous status "Preparing for personal collection" was set toautoMarkReadyForPickuptrue and on the Zlavomat side, the order was automatically switched to the "Ready for personal collection" status
POST /order/$slevomatId/delivery-ready-for-pickup
{}Changing the order status to "Delivered to customer – awaiting customer confirmation"
This endpoint will be called if the previous status was set to "On the way", "Preparing for personal collection" or "Ready for personal collection" withautoMarkDeliveredtrue and on the Zlavomat side, the order was automatically switched to the status "Delivered to customer – awaiting confirmation by the customer".
POST /order/$slevomatId/mark-delivered
{}Communication Partner ⇒ Discount machine
This part of the API is implemented on the Zľavomat side and is called by the partner system.
The API root URL is
https://www.zlavomat.sk/zbozi-api/v1PHP library
To implement this API page, you can use a ready-made PHP library. The library currently requires PHP version 5.4 or higher and assumes the use of the Composer tool.
The library's instructions and source code are on GitHub .
Authorization of requests
When the API is turned on, the partner receivespartner_token andapi_secret , which is used to prove when calling the Zlavomat API.
These parameters are passed in headersX-PartnerToken andX-ApiSecret .
Test interface
The root URL of the test interface is
https://www.zlavomat.sk/zbozi-api/v1-testIt is possible to call all actions on it as on the other interface.
The test interface checks the authorization of requests (correctness of the partner token and API secret) and the validity of the incoming request bodies (JSON). In these respects, it behaves identically to the live API.
However, the test interface does not work with real orders. It does not validate whether the order is transitioning between the correct states and whether it contains items with the given IDs. Once authorization and validation of the request form pass, the test interface always responds with a success code of 200 or 204.
Create a cancellation
Create order cancellation items in a specified quantity. If the entire order is to be canceled, all items with the corresponding quantity are listed.
Individual items can also be partially cancelled (e.g. 1 piece out of two).
Cancellation note (note ) is optional.
POST /order/$slevomatId/cancel
{ "items": [ { "slevomatId": 45454, "amount": 15 } ], "note": "nepovinná poznámka" }Changing the order status to "Processing"
POST /order/$slevomatId/mark-pending
{}Changing the order status to "On the way"
When ordering, the parameter isautoMarkDelivered determine whether the status should automatically switch to "Delivered to customer – awaiting customer confirmation" after the set transport period ("Time from shipment to delivery")
The response includes an updated estimated delivery date.
POST /order/$slevomatId/mark-en-route
{ "autoMarkDelivered": true }Response 200
{ "expectedDeliveryDate": "2021–08–25" }Changing the order status to "Preparing for personal collection"
When ordering, the parameter isautoMarkReadyForPickup determine whether the status should automatically switch to "Ready for personal collection" after the time from shipment to delivery for a given type of collection point has elapsed.
When ordering, the parameter isautoMarkDelivered determine whether the status should automatically switch from "Ready for personal collection" to "Delivered to customer – awaiting customer confirmation" after the set number of days for pickup at a given type of collection point.
Parameter combinationautoMarkReadyForPickup false andautoMarkDelivered true is not allowed. In this case, error code 9 is returned.
The response includes an updated estimated delivery date.
POST /order/$slevomatId/mark-getting-ready-for-pickup
{ "autoMarkReadyForPickup": true, "autoMarkDelivered": true }Response 200
{ "expectedDeliveryDate": "2021–09–06" }Changing the order status to "Ready for personal collection"
When ordering, the parameter isautoMarkDelivered determine whether the status should automatically switch to "Delivered to customer – awaiting customer confirmation" after the set number of days for pickup for a given type of collection point.
POST /order/$slevomatId/mark-ready-for-pickup
{ "autoMarkDelivered": true }Changing the order status to "Delivered to customer – awaiting customer confirmation"
POST /order/$slevomatId/mark-delivered
{}Change of delivery address
The delivery address can only be changed when delivering to the address (ie the place of similar collection cannot be changed).
All keys exceptcompany are mandatory.
Valid values for the keystate arecz (Czech Republic) andsk (Slovakia).
POST /order/$slevomatId/update-shipping-address
{ "name": "Karel Novák", "street": "Pod horou 34", "city": "Pardubice", "postalCode": "530 00", "state": "CZ", "phone": "+420777888999", "company": "Knihkupectví Novák" }