3rd Party API

The API is used to transfer order information between Slevomat and the system of our trading partner. The API requires the implementation of two-way communication – the Slevomat system calls the partner's API and the partner calls Slevomat's API.

Orders exported to the partner API can no longer be manipulated in the Slevomat partner interface, only viewed. Manipulation of exported orders can only take place via the API.

All requests must be made on HTTPS and all data is in JSON format.

API access

You can access the API credentials from the Settings tab in your partner interface. To get the data you need to provide the root URL of the partner part of the API for use in the direction Slevomat → Partner, e.g.

https://example­.com/slevomat-zbozi-api 

The access data will only be displayed once when you access the API, please save it carefully.

Once the API is accessed, the system will start exporting newly created orders to it.

Initial data export

To transfer existing orders at the moment of API access, you can use a one-time export to CSV in the partner interface.

If you 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 processed
  • 204 No Content – the request has been processed, the response has no content
  • 400 Bad Request – the request is not valid – there may be missing or invalid parameters against the specification
  • 403 Forbidden – client authorization failed
  • 404 Not Found – endpoint or required data not found
  • 405 Method Not Allowed – the endpoint does not support this HTTP method
  • 422 Unprocessable Entity – expected error during request processing (see section Error conditions)
  • 500 Internal Server Error – an error occurred on the server side
  • 502 Bad Gateway – a server-side error occurred
  • 503 Service Unavailable – the server is in maintenance mode (new version deployment may be in progress or planned downtime)
  • 504 Gateway Timeout – a server-side error has occurred

HTTP 5×x responses may not use JSON format.

In the case of 4xx errors, the outgoing request is at fault and needs to be corrected before retrying.

Errors 5xx indicate server errors and the request can be retried without changing it. In the case of 503, the caller should respect the Retry-After response header and retry only after the time specified in the header has elapsed.

Order statuses

An order is always in one of the following states:

State value Description
1 New paid order
Handled
Goods dispatched (only orders with shipping)
Preparing for personal collection – e.g. transport to a branch
Ready for personal collection
Delivered to customer – awaiting customer confirmation
Delivered and confirmed by customer
Customer refused to acknowledge receipt of order
Cancelled order

The customer is informed of any change in status by email.

The order does not necessarily have to go through all statuses for successful delivery, from "New order paid" it is possible to go straight to "Goods dispatched" / "Ready for personal collection" and then to "Delivered to customer – awaiting customer confirmation". The use of all statuses, however, leads to better customer information about the progress of the order and is recommended.

Error states

In the case of 4×x HTTP codes, the response always contains the key status (see the codebook below) and the field messages with text descriptions of the errors.

Status value Description
Non-valid request – missing or non-valid values
Invalid login details
Non-existent order
Non-existent order item
Transition of an order to an unauthorised state
Invalid cancellation – cancellation of more items than exist
Other error
The order has not yet been exported to the partner API – it cannot be manipulated via the API
To automatically set the "Goods delivered to customer" status, you need to have the shipment automatically set to "Goods ready for pickup"

Example:

{ "status": 3, "messages": [ "Order #1234 was not found." ] }

Data Types

The data types of each key in requests and responses 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 Slevomat ⇒ Partner

This part of the API is implemented on the partner side and Slevomat calls it.

The required API root URL is provided by the partner and should be in the form

 https://www.example.com/slevomat-zbozi-api/v1

Request Authorization

When the API is enabled, the partner receives partner_api_se­cret, which proves that incoming requests are indeed from Slevomat.

This parameter is passed in the HTTP header X-PartnerApiSecret.

Test interface

Slevomat includes functionality to call the API on the partner side and view the response. The root URL specified by the partner when the API is made available is appended to -test, so that in testing the API is called at e.g.

https://example­.com/slevomat-zbozi-api-test

to avoid mixing test data with live orders.

Testing of the partner API is done via POST requests to the following addresses:

  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/new-order
    - New Order
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/update-shipping-dates 
    - Bulk update of expected shipment dates
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/mark-delivered 
    - Change order status to "Delivered to customer – awaiting customer confirmation"
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/ready-for-pickup 
    - Change order status to "Ready for personal collection"
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/confirm-delivery 
    - Delivery confirmation
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/reject-delivery 
    - Refusal of acceptance
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/cancel 
    - Cancellation

Replace the <orderId> part of the URL 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 the headers X-PartnerToken and X-ApiSecret.

When making a test call to the partner API, the system sends the X-PartnerApiSecret header as it does in live operation.

The data sent with a new order is test data and randomly generated.

In the case of sending an order cancellation, you need to include the items field in the POST body of the request in JSON (in the same format as sent by the API), which the testing interface will validate and forward to the partner API in the same form.

New order

The request contains the data of the newly created order.

Orders always have a unique slevomatId. If the API receives a duplicate slevomatId, the request should be ignored by the partner API (the first request was evaluated as unsuccessful by Slevomat and therefore repeated) and the response should also be HTTP 204.

created is the date in ISO 8601 format, i.e. YYYY-MM-DD'T'HH:mm:ss­+zz:zz.

productId contains the event ID, variantId the ID of the purchased variant.

The optional internalId indicates the internal ID entered for the action variant when it is created in the partner interface. It is used to identify the product in the partner's system.

In billingAddress (billing address) only the customer name (name) is mandatory.

In shippingAddress (delivery address) the company (company) is optional. In the case of delivery to shippingAddress it contains the customer's address, in the case of personal collection the address of the establishment where the customer will collect the goods.

The key delivery.type can take the value address (delivery to address) or pickup (personal collection). delivery.name contains the name of the transport or the name of the establishment.

delivery.expec­tedShippingDa­te (estimated ship date) and delivery.expec­tedDeliveryDa­te (estimated delivery date) are data in the format YYYY-MM-DD.

The key weight contains the weight of the order in kilograms. If we do not know the weight of all items in the order, it takes the value null.

POST /order/$slevomatId

{ "slevomatId": "721896899157", "created": "2021–08–25T15:14:24+02:00", "items": [ { "slevomatId": "960", "productId": "22", "variantId": "105", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "7577400222", "productId": "1752", "variantId": "9855", "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": "Petr Novák", "company": null, "street": "Strašnická 8", "city": "Praha", "postalCode": "100 00", "phone": "+420777888999" }, "delivery": { "type": "address", "name": "PPL", "expectedShip­pingDate": "2021–08–27", "expectedDeli­veryDate": "2021–08–30", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

POST /order/$slevomatId

{ "slevomatId": "124146766678", "created": "2021–09–01T12:49:37+02:00", "items": [ { "slevomatId": "863", "productId": "64", "variantId": "14", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "2364201450", "productId": "7057", "variantId": "5802", "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ě", "expectedShip­pingDate": "2021–09–02", "expectedDeli­veryDate": "2021–09–02", "price": 0.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

Mass update of expected shipment dates

If the deals manager, at the partner's request, moves the shipping dates of selected orders, the system informs the partner API of this update.

The data sent contains the order ID field and the new expected ship date.

POST /update-shipping-dates
{ "expectedShip­pingDate": "2021–08–25", "slevomatIds": [ "123456", "45454544" ] }

Cancellation

Cancellations can be created both on the Slevomat side and on the partner system. This endpoint handles the creation of the cancellation on the Slevomat side and its transfer to the partner's system.

It creates a cancellation of order items in the specified quantity. If the entire order is to be cancelled, all items with the corresponding quantity are listed.

Individual items can also be cancelled partially (e.g. 1 of 2).

A cancellation note (note) is optional.

POST /order/$slevo­matId/cancel
{ "items": [ { "slevomatId": "1212", "amount": 1 }, { "slevomatId": "4545454", "amount": 2 } ], "note": "storno v zákonné lhůtě" }

Confirmation of delivery

After you mark the order as "Delivered to customer" we will ask the customer to confirm that they have actually received it. When the order is marked as received, this endpoint will be called.

POST /order/$slevo­matId/confirm-delivery
{}

Refusal of acceptance

POST /order/$slevo­matId/reject-delivery
{ "rejectionReason": "Důvod odmítnutí zákazníkem" }

Change order status to "Ready for personal collection"

This endpoint will be called if the previous status "Ready for personal collection" was set with autoMarkRea­dyForPickuptrue and the order was automatically switched to "Ready for personal collection" on the Slevomat side.

POST /order/$slevo­matId/delivery-ready-for-pickup
{}

Change the order status to "Delivered to customer – awaiting customer confirmation"

This endpoint is called if the previous status "On the way", "Ready for personal collection" or "Ready for personal collection" was set with autoMarkDeli­veredtrue and the order was automatically switched to the status "Delivered to customer – waiting for customer confirmation" on the Slevomat side.

POST /order/$slevo­matId/mark-delivered
{}

Communication Partner ⇒ Slevomat

This part of the API is implemented on the Slevomat side and is called by the partner system.

The root URL of the API is

 https://www.slevomat.cz/zbozi-api/v1

PHP library

To implement this side of the API, you can use the prepared PHP library. The library currently requires PHP 5.4 or higher and requires the use of Composer.

Instructions for using the library and source code are on GitHub.

Request Authorization

When the API is enabled, the partner receives partner_token and api_secret, which are used to authenticate themselves when calling the Slevomat API.

These parameters are passed in the X-PartnerToken and X-ApiSecret headers.

Test interface

The root URL of the test interface is

https://www.slevomat.cz/zbozi-api/v1-test

All actions can be called on it as on the live interface.

The test interface checks the authorization of requests (correctness of the partner token and API secret) and the validity of incoming request bodies (JSON). In these respects, it behaves identically to the live API.

However, the testing interface does not work with actual orders. Thus, it does not validate whether an order transitions between the correct states and whether it contains items with the given IDs. Once the authorization and form validation of the request passes, the test interface always matches a success code of 200 or 204. 

Creating a cancellation

Creates a cancellation of order items in the specified quantity. If the order is to be cancelled in its entirety, all items with the corresponding quantity are listed.

Individual items can also be cancelled partially (e.g. 1 of 2).

A cancellation note (note) is optional.

POST /order/$slevomatId/cancel

{ "items": [ { "slevomatId": 45454, "amount": 15 } ], "note": "nepovinná poznámka" }

Change order status to "Pending"

POST /order/$slevomatId/mark-pending

{}

Change order status to "Goods dispatched"

For an order, the autoMarkDelivered parameter can be used to specify whether it should automatically switch to the "Delivered to customer – awaiting customer confirmation" status after a set shipping time ("Time from shipment to delivery").

The response contains an updated estimated delivery date.

POST /order/$slevomatId/mark-en-route

{ "autoMarkDeli­vered": true }

Response 200

{ "expectedDeli­veryDate": "2021–08–25" }

Change order status to "Ready for personal collection"

You can use the parameter autoMarkReady­ForPickup to specify whether the order should be automatically switched to the "Ready for personal collection" status after the time from dispatch to delivery for a given type of collection point.

For an order, the autoMarkDelivered parameter can be used to specify whether it should automatically switch from the "Ready for personal collection" status to the "Delivered to customer – awaiting customer confirmation" status after a set number of days for collection at a given type of collection point.

The combination of the parameters autoMarkReady­ForPickup false and autoMarkDelivered true is not allowed. In this case, error code 9 will be returned.

The response contains an updated expected delivery date.

POST /order/$slevomatId/mark-getting-ready-for-pickup

{ "autoMarkReady­ForPickup": true, "autoMarkDeli­vered": true }

Response 200

{ "expectedDeli­veryDate": "2021–08–25" }

Change order status to "Ready for personal collection"

The autoMarkDelivered parameter can be used to specify whether the order should be automatically switched to the status "Delivered to customer – awaiting customer confirmation" after a set number of days for collection at a given type of collection point.

POST /order/$slevo­matId/mark-ready-for-pickup
{ "autoMarkDeli­vered": true }

Change the order status to "Delivered to customer – awaiting customer confirmation"

POST /order/$slevo­matId/mark-delivered
{}

Change delivery address

The delivery address can only be changed for delivery to an address (i.e. the place of personal collection cannot be changed).

All keys except company are required.

Valid values for the state key are cz (Czech Republic) and sk (Slovakia).

POST /order/$slevo­matId/update-shipping-address
{ "name": "Karel Novák", "street": "Pod horou 34", "city": "Pardubice", "postalCode": "530 00", "state": "CZ", "phone": "+420777888999", "company": "Knihkupectví Novák" }

Changelog

Back to the list of articles

Related articles


Nahoru