The API is used to transfer order information between Discountomat and the system of the trading partner. The API requires the implementation of a two-sided communication – the partner's API is called by the Discount system and the partner calls the API Discount.
With orders exported to the partner API, it is no longer possible can be manipulated in the partner's interface, only viewed. Manipulation of exported orders can only be done via API.
All requests must be made on HTTPS and all data is in JSON format.
API accessibility
You can access the API from the Settings tab in your Partner Interface. To get the data, you need to enter the root code URL of the partner part of the API for use in the direction Zlevomat → Partner, e.g.
https://example.com/slevomat-zbozi-apiThe access data will only be displayed when the API is accessed, read it carefully keep them carefully.
Once the API is accessed, newly created orders are entered into it by the system will start to export the orders to the system.
Initial data export
To overflow existing orders at the moment the API is made available A one-time export to CSV in the partner interface can be used.
At the moment when you have existing orders (created before API access) in your own system and you want to start working with them via 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– request has been processed successfully204 No Content– request has been processed successfully, response has no content400 Bad Request– request is not valid – may may be missing or invalid parameters against the specification403 Forbidden– client authorization failed404 Not Found– endpoint or data requested were not found405 Method Not Allowed– the endpoint does not support this HTTP protocol method422 Unprocessable Entity– expected error on request processing (see section Error conditions )500 Internal Server Error– an error occurred on the page server502 Bad Gateway– a server-side error occurred503 Service Unavailable– server is in maintenance mode (new version deployment or planned downtime may be in progress)504 Gateway Timeout– an error occurred on the server side server
HTTP 5×x responses may not use JSON format.
In the case of 4xx errors, the error is in the outgoing request and
it needs to be corrected before retrying.
Errors 5xx indicate server errors and the request can be
can be retried without changing it. In the case of 503, the caller should
respect the Retry-After response header and the next attempt
retry only after the time specified in the header has elapsed.
Order states
An order is always in one of the following states:
| Status value | Description |
| 1 | New paid order |
| 2 | Being processed |
| 3 | On the way (orders with shipping only) |
| 4 | In preparation for personal collection – e.g. in transit to branch |
| 5 | Ready for personal collection |
| 6 | Delivered to customer – awaiting customer confirmation |
| 7 | Delivered and confirmed by customer |
| 8 | Customer refused to acknowledge receipt of order |
| 9 | Order cancelled |
The customer is informed of any change in status by email.
The order does not necessarily have to go through all statuses to be successful delivery, it is possible to go straight from the "New Paid Order" status to "On the way" / "Ready for collection" and then to "Delivered to customer – awaiting customer confirmation". Using of all statuses, however, leads to better customer information on the progress of order processing and we recommend it.
Error states
In the case of 4×x HTTP codes, the response always contains a key
status (see code list below) and the field messages
with text descriptions of the errors.
| Status value | Description |
| 1 | Invalid request – missing or invalid values |
| 2 | Invalid credentials |
| 3 | Non-existent order |
| 4 | Non-existent order item |
| 5 | Transition of order to an unauthorised state |
| 6 | Invalid cancellation – cancellation of more items than exists |
| 7 | Other error |
| 8 | Order has not yet been exported to the partner API – it is not cannot be manipulated through the API |
| 9 | To automatically set the "Goods delivered to customer" status it is necessary to have the shipment automatically set to the status "Goods ready ready for collection" |
Example:
{ "status": 3, "messages": [ "Order #1234 was not found." ] }Data types
The data types of the individual keys in the requests and responses are
are always described for specific endpoints. Unless otherwise specified,
the value in quotes "" is always a mandatory string. Unless
otherwise specified, the numeric value is always a mandatory integer.
Communication Discountomat ⇒ Partner
This part of the API is implemented on the partner's side and is used by Zlevomat calls.
The required API root URL is shared by the partner, it should be of the form
https://www.example.com/slevomat-zbozi-api/v1Request Authorization
When the API is enabled, the partner receives partner_api_secret, which
the incoming requests are verified that they are indeed coming from Discount.
This parameter is passed in the HTTP header
X-PartnerApiSecret .
Test interface
Discountomat includes functionality to call the API on the partner side and
display the response. To the root URL specified by the partner when accessing the API
-test is attached to the partner's URL , so that in testing it is called
API at e.g.
https://example.com/slevomat-zbozi-api-testto avoid intermixing test data with live orders.
Testing of the partner API 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 shipment dateshttps://www.zlavomat.sk/test-zbozi-partner-api/v1/update-shipping-dates -
– Change order status to "Delivered to customer – waiting for confirmation by customer"https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/mark-delivered -
– Change order status to "Ready for personal collection"https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/ready-for-pickup -
– Confirmation of deliveryhttps://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/confirm-delivery -
– Refusal of acceptancehttps://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/reject-delivery -
– Cancellationhttps://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/cancel
Replace the <orderId> part of the URL with any number
order number, with this order number requests are transferred to API partner.
Requests to this test interface need to be authorized
with the headers X-PartnerToken and X-ApiSecret.
When a test call is made to the partner API, the system sends the header
X-PartnerApiSecret header just as in live operation.
The data sent with a new order is test data and randomly generated.
In the case of sending an order cancellation, the POST body
of the request, include in the JSON field items (in the same format as sent by the API), which will be validated by the testing interface and sent to the partner API
API will forward it in the same format.
New order
The request contains the data of a newly created order.
Orders always have a unique zlavomatId. If the API
a duplicate zlavomatId arrives , the request should be
ignore it (the first converted request was evaluated as failed by Discountomat and
so we repeat it) and respond also with HTTP 204.
created is a date in ISO 8601 format, so
YYYY-MM-DD'T'HH:mm:ss+zz:zz .
productId contains the event ID, variantId the ID
of the purchased variant.
The optional internalId denotes the internal ID entered when
variant of an action when it is created in the partner interface. Serves
to identify the product in the partner's system.
In billingAddress (billing address) only the name is mandatory
(name) of the customer.
In shippingAddress (delivery address) the company is optional
(company). In case of delivery to
shippingAddress contains the customer's address, in case of personal
delivery, the address of the establishment where the customer picks up the goods.
The key delivery.type may take on the values
address (delivery to address) or pickup (personal
collection). delivery.name contains the name of the transport or the name of the operation.
delivery.expectedShippingDate (expected
date of shipment) and delivery.expectedDeliveryDate
(estimated date of delivery) are data in the format
YYYY-MM-DD .
The key weight contains the weight of the order in kilograms.
In case we do not know the weight of all items in the order,
it takes the value null.
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 shipment dates
If the deals manager, at the request of the partner, pushes the bulk data shipping dates for selected orders, the system informs the partner API of this update.
The sent data contains the order ID field and the new expected date of dispatch.
POST /update-shipping-dates
{ "expectedShippingDate": "2021–09–06", "slevomatIds": [ "123456", "45454544" ] }Cancellations
Cancellations can be created on both the Discount and partner side system. This endpoint handles the creation of cancellations on the Zlavomat side and its transfer to the partner's system.
It creates a cancellation of order items in the specified quantity. If the the entire order is cancelled, all items are listed with the corresponding quantity.
Individual items can also be cancelled partially (e.g. 1 piece of two).
The 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 the order as "Delivered to customer" you we will request confirmation from the customer that they have actually received it. When the order is is marked as received, this endpoint will be called.
POST /order/$slevomatId/confirm-delivery
{}Refusal of acceptance
POST /order/$slevomatId/reject-delivery
{ "rejectionReason": "Důvod odmítnutí zákazníkem" }Change the status of the order to "Ready for collection"
This endpoint will be called if the previous endpoint has been
"Ready for personal collection" status was set
with autoMarkReadyForPickuptrue and on the Discount page
the order has been automatically switched to the "Ready
for personal collection"
POST /order/$slevomatId/delivery-ready-for-pickup
{}Change the order status to "Delivered to customer – waiting for customer confirmation"
This endpoint will be called if the previous
status "On the way", "Ready for personal collection" or "Ready
for personal collection" was set
with autoMarkDeliveredtrue and on the Discount page
the order has been automatically switched to the status "Delivered
to customer – awaiting customer confirmation".
POST /order/$slevomatId/mark-delivered
{}Communication Partner ⇒ Zľavomat
This part of the API is implemented on the Discountomat side and calls it partner system.
The root URL of the API is
https://www.zlavomat.sk/zbozi-api/v1PHP library
For the implementation of this side of the API it is possible to use the prepared PHP library. The library currently requires PHP version 5.4 or higher and assumes the use of the Composer tool.
Instructions for using the library and the source code are on GitHub.
Authorization requests
When the API is enabled, the partner receives partner_token and
api_secret , which are used to authenticate the Zlavomat API call.
These parameters are passed in the headers X-PartnerToken and
X-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 partner token and API secret) and the validity of incoming request bodies (JSON). In these respects, it behaves identically to the crisp API.
However, the test interface does not work with actual orders. Thus, it does not validate whether an order transitions between the correct states and whether contains items with given IDs. Once the authorization and validation passes forms of the request, the test interface always responds with a successful code 200 or 204.
Creating a cancellation
Create a cancellation of order items in the specified quantity. If it has the order is to be cancelled in its entirety, all items are listed with the corresponding quantity.
Individual items can also be cancelled partially (e.g. 1 item of two).
The cancellation note (note) is optional.
POST /order/$slevomatId/cancel
{ "items": [ { "slevomatId": 45454, "amount": 15 } ], "note": "nepovinná poznámka" }Change order status to "In process"
POST /order/$slevomatId/mark-pending
{}Change order status to "On my way"
When an order is placed, the autoMarkDelivered parameter is used to determine whether
after the set shipping period ("Time from shipment to delivery") should
automatically switch to the status "Delivered to customer – waiting for customer confirmation".
The response contains the updated estimated delivery date.
POST /order/$slevomatId/mark-en-route
{ "autoMarkDelivered": true }Response 200
{ "expectedDeliveryDate": "2021–08–25" }Change order status to "Ready for personal collection"
When the order goes through the autoMarkReadyForPickup parameter to specify,
whether the time from dispatch to delivery for the given type of collection point should be automatically switched to the "Ready for delivery" status.
for personal collection".
When ordering, the autoMarkDelivered parameter determines whether
after the set number of days for pick-up for a given type of collection point
collection point should be automatically switched from the "Ready for personal collection" status
to "Delivered to customer – awaiting confirmation
by the customer".
The combination of the parameters autoMarkReadyForPickup false and
autoMarkDelivered true is not allowed. In this case
error code 9 is returned.
The response contains an updated estimated delivery date.
POST /order/$slevomatId/mark-getting-ready-for-pickup
{ "autoMarkReadyForPickup": true, "autoMarkDelivered": true }Response 200
{ "expectedDeliveryDate": "2021–09–06" }Change order status to "Ready for pickup"
When an order is placed, the autoMarkDelivered parameter is used to determine whether
after a set number of days for pickup for a given pickup type
collection point should be automatically switched to the status "Delivered to customer –
awaiting customer confirmation".
POST /order/$slevomatId/mark-ready-for-pickup
{ "autoMarkDelivered": true }Change the order status to "Delivered to customer – awaiting customer confirmation"
POST /order/$slevomatId/mark-delivered
{}Change delivery address
The delivery address can only be changed on delivery to an address (i.e. You cannot change the place of collection).
All keys except company are required.
Valid values for the state key are cz (Czech
Republic) and sk (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" }