API використовується для передачі інформації про замовлення між Дисконтоматом і системою торгового партнера. API вимагає впровадження двостороннього зв’язку – API партнера викликає система Discount, а партнер викликає API Discount.
Із замовленнями, експортованими до партнерського API, більше не можна керувати ними в інтерфейсі партнера, а лише переглядати. Маніпуляції з експортованими замовленнями можна виконувати лише через API.
Усі запити мають надсилатися через HTTPS, а всі дані – у форматі JSON.
Доступність API
Ви можете отримати доступ до API на вкладці «Налаштування» в інтерфейсі партнера. Щоб отримати дані, вам потрібно ввести URL-адресу кореневого коду партнерської частини API для використання в напрямку Zlevomat → Partner, наприклад
https://example.com/slevomat-zbozi-apiДані доступу відображатимуться лише під час доступу до API, уважно прочитайте їх, ретельно зберігайте їх.
Після доступу до API система почне експортувати замовлення в систему, щойно створені замовлення.
Експорт вихідних даних
Щоб переповнювати існуючі замовлення на момент, коли стає доступним API, можна використати одноразовий експорт у CSV в партнерському інтерфейсі.
У той момент, коли у вас у власній системі є наявні замовлення (створені до доступу до API) і ви хочете почати працювати з ними через API, скористайтеся функцією «Почати роботу з позначеними замовленнями через API» в меню «Масові дії з замовленнями». .
Опис типових відповідей HTTP
200 OK– запит успішно оброблено204 No Content– запит оброблено успішно, відповідь не має змісту400 Bad Request– запит недійсний – можуть бути відсутні або недійсні параметри в порівнянні зі специфікацією403 Forbidden– помилка авторизації клієнта404 Not Found– кінцева точка або запитувані дані не знайдені405 Method Not Allowed– кінцева точка не підтримує цей метод протоколу HTTP422 Unprocessable Entity– очікувана помилка під час обробки запиту (див. розділ Умови помилки )500 Internal Server Error– сталася помилка на сервері сторінки502 Bad Gateway– сталася помилка на стороні сервера503 Service Unavailable– сервер знаходиться в режимі обслуговування (можливо, триває розгортання нової версії або плановий простой)504 Gateway Timeout– сталася помилка на сервері на стороні сервера
Відповіді HTTP 5×x можуть не використовувати формат JSON.
У разі4xx помилки, помилка міститься у вихідному запиті, і її потрібно виправити перед повторною спробою.
Помилки5xx вказує на помилки сервера, і запит можна повторити, не змінюючи його. У разі503 , абонент повинен поважатиRetry-After заголовок відповіді та наступну спробу повторити лише після закінчення часу, зазначеного в заголовку.
Замовлення держав
Замовлення завжди знаходиться в одному з наступних станів:
| Значення статусу | опис |
| 1 | Нове оплачене замовлення |
| 2 | Обробляється |
| 3 | В дорозі (лише замовлення з доставкою) |
| 4 | Під час підготовки до особистого отримання – наприклад, під час транспортування до відділення |
| 5 | Готовий до особистого збору |
| 6 | Доставлено клієнту – очікується підтвердження від клієнта |
| 7 | Доставлено та підтверджено клієнтом |
| 8 | Клієнт відмовився підтвердити отримання замовлення |
| 9 | Замовлення скасовано |
Про будь-які зміни статусу клієнта повідомляють електронною поштою.
Замовленню не обов’язково проходити всі статуси, щоб бути успішною доставкою, можна перейти безпосередньо зі статусу «Нове оплачене замовлення» до «В дорозі» / «Готовий до отримання», а потім до «Доставлено клієнту – очікуємо підтвердження клієнта». Однак використання всіх статусів веде до кращого інформування клієнта про хід обробки замовлення, і ми рекомендуємо його.
Стани помилок
У випадку HTTP-кодів 4×x відповідь завжди містить ключstatus (див. список кодів нижче) і полеmessages з текстовим описом помилок.
| Значення статусу | опис |
| 1 | Недійсний запит – відсутні або недійсні значення |
| 2 | Недійсні облікові дані |
| 3 | Неіснуюче замовлення |
| 4 | Неіснуюча позиція замовлення |
| 5 | Перехід порядку в несанкціонований стан |
| 6 | Недійсне скасування – скасування більшої кількості елементів, ніж існує |
| 7 | Інша помилка |
| 8 | Замовлення ще не експортовано в партнерський API – ним не можна керувати через API |
| 9 | Для автоматичного встановлення статусу «Товар доставлено клієнту» необхідно, щоб відправлення було автоматично встановлено в статус «Товар готовий до отримання» |
приклад:
{ "status": 3, "messages": [ "Order #1234 was not found." ] }Типи даних
Типи даних окремих ключів у запитах і відповідях завжди описані для конкретних кінцевих точок. Якщо не вказано інше, значення в лапках"" завжди обов'язковий рядок. Якщо не вказано інше, числове значення завжди є обов’язковим цілим числом.
Комунікація Дисконтомат ⇒ Партнер
Ця частина API реалізована на стороні партнера і використовується викликами Zlevomat.
Потрібну кореневу URL-адресу API надає партнер, вона має мати форму
https://www.example.com/slevomat-zbozi-api/v1Запит авторизації
Коли API увімкнено, партнер отримуєpartner_api_secret , які перевіряють, що вхідні запити справді надходять від Discount.
Цей параметр передається в HTTP-заголовкуX-PartnerApiSecret .
Тестовий інтерфейс
Discountomat містить функцію виклику API на стороні партнера та відображення відповіді. До кореневої URL-адреси, вказаної партнером під час доступу до API-test приєднується до URL-адреси партнера, тому під час тестування він називається API за адресою, наприклад
https://example.com/slevomat-zbozi-api-testщоб уникнути змішування тестових даних із реальними замовленнями.
Тестування партнерського API виконується за допомогою запитів POST за такими адресами:
– Новий порядокhttps://www.zlavomat.sk/test-zbozi-partner-api/v1/new-order
– Масове оновлення очікуваних дат відвантаженняhttps://www.zlavomat.sk/test-zbozi-partner-api/v1/update-shipping-dates
– Змінити статус замовлення на "Доставлено клієнту – очікується підтвердження від клієнта"https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/mark-delivered
– Змінити статус замовлення на "Готовий до особистого забору"https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/ready-for-pickup
– Підтвердження доставкиhttps://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/confirm-delivery
– Відмова в акцептіhttps://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/reject-delivery
– Скасуванняhttps://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/cancel
Замініть<orderId> частина URL-адреси з будь-яким номером замовлення, із цим номером замовлення запити передаються партнеру API.
Запити до цього тестового інтерфейсу мають бути авторизовані за допомогою заголовківX-PartnerToken іX-ApiSecret .
Коли здійснюється тестовий виклик партнерського API, система надсилає заголовокX-PartnerApiSecret заголовок так само, як і в режимі реального часу.
Дані, надіслані з новим замовленням, є тестовими та генеруються випадковим чином.
У разі надсилання скасування замовлення, POST-тіло запиту вставте в поле JSONitems (у тому самому форматі, який надсилає API), який буде перевірено інтерфейсом тестування та надіслано API партнера, і API перешле його в тому самому форматі.
Новий порядок
Запит містить дані щойно створеного замовлення.
Замовлення завжди унікальніzlavomatId . Якщо API дублікатzlavomatId надходить, запит слід проігнорувати (перший перетворений запит Discountomat оцінив як невдалий, тому ми повторюємо його) і відповісти також HTTP 204.
created це дата у форматі ISO 8601, отжеYYYY-MM-DD'T'HH:mm:ss+zz:zz .
productId містить ідентифікатор події, variantId ID придбаного варіанту.
Необов'язковийinternalId позначає внутрішній ідентифікатор, який вводиться під час варіанту дії під час її створення в інтерфейсі партнера. Служить для ідентифікації товару в системі партнера.
вbillingAddress (платіжна адреса) тільки ім'я є обов'язковим (name ) замовника.
вshippingAddress (адреса доставки) компанія необов'язкова (company ). У разі доставки доshippingAddress містить адресу замовника, у разі особистої доставки – адресу закладу, де замовник отримує товар.
ключdelivery .type може приймати значенняaddress (доставка за адресою) абоpickup (особисте зібрання).delivery .name містить назву транспорту або назву операції.
delivery .expectedShippingDate (очікувана дата відправлення) іdelivery .expectedDeliveryDate (орієнтовна дата поставки) є дані у форматіYYYY-MM-DD .
ключweight містить вагу замовлення в кілограмах. Якщо ми не знаємо вагу всіх позицій у замовленні, вона приймає значення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 }Масове оновлення очікуваних дат відвантаження
Якщо менеджер із угод за запитом партнера висуває дати доставки масових даних для вибраних замовлень, система інформує партнерський API про це оновлення.
Надіслані дані містять поле ID замовлення та нову очікувану дату відправлення.
POST /update-shipping-dates
{ "expectedShippingDate": "2021–09–06", "slevomatIds": [ "123456", "45454544" ] }Скасування
Скасування можна створити як у системі Discount, так і в партнерській системі. Ця кінцева точка обслуговує створення скасувань на стороні Zlavomat і їх передачу в систему партнера.
Він створює скасування позицій замовлення у вказаній кількості. Якщо все замовлення скасовується, усі товари відображаються з відповідною кількістю.
Окремі позиції можна також частково скасувати (наприклад, 1 шт. з двох).
Відмітка про скасування (note ) є необов’язковим.
POST /order/$slevomatId/cancel
{ "items": [ { "slevomatId": "1212", "amount": 1 }, { "slevomatId": "4545454", "amount": 2 } ], "note": "storno v zákonné lhůtě" }Підтвердження доставки
Після того, як ви позначите замовлення як «Доставлено клієнту», ми запитаємо від клієнта підтвердження того, що він дійсно його отримав. Коли замовлення буде позначено як отримане, ця кінцева точка буде викликана.
POST /order/$slevomatId/confirm-delivery
{}Відмова в акцепті
POST /order/$slevomatId/reject-delivery
{ "rejectionReason": "Důvod odmítnutí zákazníkem" }Змінити статус замовлення на «Готовий до отримання»
Цю кінцеву точку буде викликано, якщо для попередньої кінцевої точки було встановлено статус «Готовий для особистого збору».autoMarkReadyForPickuptrue а на сторінці Знижка замовлення автоматично переведено на "Готов до особистого забору"
POST /order/$slevomatId/delivery-ready-for-pickup
{}Змінити статус замовлення на "Доставлено клієнту – очікується підтвердження клієнта"
Цю кінцеву точку буде викликано, якщо попередній статус «В дорозі», «Готовий до особистої передачі» або «Готовий до особистої передачі» було встановлено за допомогоюautoMarkDeliveredtrue а на сторінці «Знижка» замовлення автоматично переведено в статус «Доставлено клієнту — очікує підтвердження клієнта».
POST /order/$slevomatId/mark-delivered
{}Комунікаційний партнер ⇒ Zľavomat
Ця частина API реалізована на стороні Discountomat і називається партнерською системою.
Коренева URL-адреса API
https://www.zlavomat.sk/zbozi-api/v1Бібліотека PHP
Для реалізації цієї сторони API можна використовувати підготовлену бібліотеку PHP. Бібліотека наразі вимагає версії PHP 5.4 або новішої та передбачає використання інструменту Composer.
Інструкції з використання бібліотеки та вихідний код знаходяться на GitHub .
Запити авторизації
Коли API увімкнено, партнер отримуєpartner_token іapi_secret , які використовуються для автентифікації виклику Zlavomat API.
Ці параметри передаються в заголовкахX-PartnerToken іX-ApiSecret .
Тестовий інтерфейс
Коренева URL-адреса тестового інтерфейсу
https://www.zlavomat.sk/zbozi-api/v1-testНа ньому можна викликати всі дії, як на іншому інтерфейсі.
Тестовий інтерфейс перевіряє авторизацію запитів (коректність партнерського токена та секрету API) і валідність тіл вхідних запитів (JSON). У цьому відношенні він поводиться ідентично чіткому API.
Проте тестовий інтерфейс не працює з реальними замовленнями. Таким чином, він не перевіряє, чи замовлення переходить між правильними станами та чи містить елементи з заданими ідентифікаторами. Після того, як авторизація та перевірка проходять форми запиту, тестовий інтерфейс завжди відповідає успішним кодом 200 або 204.
Створення скасування
Створити скасування позицій замовлення у вказаній кількості. Якщо замовлення має бути скасовано повністю, усі товари вказуються з відповідною кількістю.
Окремі позиції також можна скасувати частково (наприклад, 1 з двох).
Відмітка про скасування (note ) є необов’язковим.
POST /order/$slevomatId/cancel
{ "items": [ { "slevomatId": 45454, "amount": 15 } ], "note": "nepovinná poznámka" }Змінити статус замовлення на "В процесі"
POST /order/$slevomatId/mark-pending
{}Змінити статус замовлення на "В дорозі"
Коли замовлення розміщено, autoMarkDelivered Параметр використовується для визначення того, чи слід після встановленого періоду доставки ("Час від відправлення до доставки") автоматично перейти в статус "Доставлено клієнту – очікується підтвердження клієнта".
Відповідь містить оновлену орієнтовну дату доставки.
POST /order/$slevomatId/mark-en-route
{ "autoMarkDelivered": true }Відповідь 200
{ "expectedDeliveryDate": "2021–08–25" }Змінити статус замовлення на "Готовий до особистого забору"
Коли замовлення проходить черезautoMarkReadyForPickup параметр, щоб вказати, чи повинен час від відправлення до доставки для даного типу пункту прийому автоматично перемикатися в статус «Готовий до доставки». для особистого збору».
При замовленніautoMarkDelivered Параметр визначає, чи після встановленої кількості днів для вивезення для даного типу пункту прийому пункт автоматично перемикається зі статусу «Готовий до особистого прийому» на «Доставлено клієнту – очікує підтвердження клієнтом».
Поєднання параметрівautoMarkReadyForPickup помилкові іautoMarkDelivered правда не допускається. У цьому випадку повертається код помилки 9.
Відповідь містить оновлену орієнтовну дату доставки.
POST /order/$slevomatId/mark-getting-ready-for-pickup
{ "autoMarkReadyForPickup": true, "autoMarkDelivered": true }Відповідь 200
{ "expectedDeliveryDate": "2021–09–06" }Змінити статус замовлення на "Готовий до отримання"
Коли замовлення розміщено, autoMarkDelivered Параметр використовується для визначення того, чи слід після встановленої кількості днів для самовивозу для даного типу самовивозу пункт збору автоматично перейти в статус «Доставлено клієнту — очікує підтвердження клієнта».
POST /order/$slevomatId/mark-ready-for-pickup
{ "autoMarkDelivered": true }Змінити статус замовлення на "Доставлено клієнту – очікується підтвердження клієнта"
POST /order/$slevomatId/mark-delivered
{}Змінити адресу доставки
Адресу доставки можна змінити лише під час доставки за адресою (тобто ви не можете змінити місце отримання).
Усі ключі, крімcompany потрібні.
Дійсні значення дляstate ключові єcz (Чехія) іsk (Словаччина).
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" }