API третьої сторони

API використовується для передачі інформації про замовлення між Slevomat і системою нашого торгового партнера. API вимагає впровадження двостороннього зв’язку – система Slevomat викликає API партнера, а партнер викликає API Slevomat.

Замовленнями, експортованими в партнерський API, більше не можна керувати в партнерському інтерфейсі Slevomat, а лише переглядати. Маніпуляції з експортованими замовленнями можуть відбуватися лише через API.

Усі запити мають надсилатися через HTTPS, а всі дані – у форматі JSON.

API доступу

Ви можете отримати доступ до облікових даних API на вкладці «Налаштування» в інтерфейсі партнера. Щоб отримати дані, вам потрібно надати кореневу URL-адресу партнерської частини API для використання в напрямку Slevomat → 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 – кінцева точка не підтримує цей метод HTTP
• 422 Unprocessable Entity – очікувана помилка під час обробки запиту (див. розділ Умови помилки )
• 500 Internal Server Error – сталася помилка на стороні сервера
• 502 Bad Gateway – сталася помилка на стороні сервера
• 503 Service Unavailable – сервер знаходиться в режимі обслуговування (можливо, триває розгортання нової версії або запланований простой)
• 504 Gateway Timeout – сталася помилка на стороні сервера

Відповіді HTTP 5×x можуть не використовувати формат JSON.

У разі4xx помилки, вихідний запит є помилковим і його потрібно виправити перед повторною спробою.

Помилки5xx вказує на помилки сервера, і запит можна повторити, не змінюючи його. У разі503 , абонент повинен поважатиRetry-After заголовок відповіді та повторіть спробу лише після закінчення часу, зазначеного в заголовку.

Статуси замовлень

Замовлення завжди знаходиться в одному з наступних станів:

Про будь-які зміни статусу клієнта повідомляють електронною поштою.

Замовленню не обов’язково проходити всі статуси для успішної доставки. З «Нове замовлення оплачено» можна перейти прямо до «Товар відправлено» / «Готовий для особистого отримання», а потім до «Доставлено клієнту — очікується підтвердження від клієнта». ". Однак використання всіх статусів веде до кращого інформування клієнта про хід виконання замовлення та є рекомендованим.

Стани помилок

У випадку HTTP-кодів 4×x відповідь завжди містить ключstatus (див. кодову книгу нижче) і полеmessages з текстовим описом помилок.

приклад:

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

Типи даних

Типи даних кожного ключа в запитах і відповідях завжди описані для конкретних кінцевих точок. Якщо не вказано інше, значення в лапках"" завжди обов'язковий рядок. Якщо не вказано інше, числове значення завжди є обов’язковим цілим числом.

Комунікаційний Слевомат ⇒ Партнер

Ця частина API реалізована на стороні партнера і називається Slevomat.

Потрібна коренева URL-адреса API надається партнером і має бути у формі

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

Запит авторизації

Коли API увімкнено, партнер отримуєpartner_api_se­cret , що доводить, що вхідні запити дійсно надходять від Slevomat.

Цей параметр передається в HTTP-заголовкуX-PartnerApiSecret .

Тестовий інтерфейс

Slevomat містить функцію виклику API на стороні партнера та перегляду відповіді. Коренева URL-адреса, указана партнером, коли API стає доступним, додається-test , так що під час тестування API викликається, наприклад

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

щоб уникнути змішування тестових даних із реальними замовленнями.

Тестування партнерського API здійснюється за допомогою POST-запитів на такі адреси:

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/new-order

   – Новий порядок

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/update-shipping-dates 

   – Масове оновлення очікуваних дат відвантаження

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/mark-delivered 

   – Змінити статус замовлення на "Доставлено клієнту – очікується підтвердження клієнта"

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/ready-for-pickup 

   – Змінити статус замовлення на "Готовий до особистого забору"

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/confirm-delivery 

   – Підтвердження доставки

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/reject-delivery 

   – Відмова в акцепті

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/cancel 

   – Скасування

Замініть<orderId> частина URL-адреси з будь-яким номером замовлення, запити до партнерського API виконуються з цим номером замовлення.

Запити до цього тестового інтерфейсу мають бути авторизовані за допомогою заголовківX-PartnerToken іX-ApiSecret .

Здійснюючи тестовий виклик партнерського API, система надсилаєX-PartnerApiSecret заголовок, як це відбувається в режимі реального часу.

Дані, надіслані з новим замовленням, є тестовими та генеруються випадковим чином.

У разі відправки скасування замовлення необхідно вказатиitems поле в тілі POST запиту в JSON (у тому самому форматі, який надсилає API), яке інтерфейс тестування перевірить і перешле партнерському API у тій самій формі.

Новий порядок

Запит містить дані новоствореного замовлення.

Замовлення завжди унікальніslevomatId . Якщо API отримує дублікатslevomatId , запит має бути проігнорований партнерським API (перший запит був оцінений Slevomat як невдалий і тому повторений), і відповідь також має бути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 .expec­tedShippingDa­te (орієнтовна дата відправлення) іdelivery .expec­tedDeliveryDa­te (орієнтовна дата поставки) – дані у форматіYYYY-MM-DD .

ключweight містить вагу замовлення в кілограмах. Якщо ми не знаємо вагу всіх позицій у замовленні, вона приймає значення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 }

Масове оновлення очікуваних дат відвантаження

Якщо менеджер із угод за запитом партнера переносить дати відвантаження вибраних замовлень, система інформує партнерський API про це оновлення.

Надіслані дані містять поле ідентифікатора замовлення та нову очікувану дату відправлення.

POST /update-shipping-dates

{ "expectedShip­pingDate": "2021–08–25", "slevomatIds": [ "123456", "45454544" ] }

Анулювання

Скасування можна створювати як на стороні Slevomat, так і в партнерській системі. Ця кінцева точка обробляє створення скасування на стороні Slevomat і його передачу в систему партнера.

Він створює скасування позицій замовлення у вказаній кількості. Якщо потрібно скасувати все замовлення, відображаються всі товари з відповідною кількістю.

Окремі позиції можна також частково скасувати (наприклад, 1 із 2).

Повідомлення про скасування (note ) є необов’язковим.

POST /order/$slevo­matId/cancel

{ "items": [ { "slevomatId": "1212", "amount": 1 }, { "slevomatId": "4545454", "amount": 2 } ], "note": "storno v zákonné lhůtě" }

Підтвердження доставки

Після того, як ви позначите замовлення як «Доставлено клієнту», ми попросимо клієнта підтвердити, що він дійсно отримав його. Коли замовлення буде позначено як отримане, ця кінцева точка буде викликана.

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

{}

Відмова в акцепті

POST /order/$slevo­matId/reject-delivery

{ "rejectionReason": "Důvod odmítnutí zákazníkem" }

Змінити статус замовлення на "Готовий до особистого забору"

Ця кінцева точка буде викликана, якщо було встановлено попередній статус «Готовий для особистого збору».autoMarkRea­dyForPickuptrue і на стороні Slevomat замовлення автоматично переведено на «Готовий до особистого забору».

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

{}

Змінити статус замовлення на "Доставлено клієнту – очікується підтвердження клієнта"

Ця кінцева точка викликається, якщо попередній статус «В дорозі», «Готовий до особистої передачі» або «Готовий до особистої передачі» було встановлено за допомогоюautoMarkDeli­veredtrue і замовлення автоматично переведено в статус «Доставлено замовнику – очікується підтвердження клієнта» на стороні Slevomat.

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

{}

Комунікаційний партнер ⇒ Slevomat

Ця частина API реалізована на стороні Slevomat і викликається партнерською системою.

Коренева URL-адреса API

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

Бібліотека PHP

Для реалізації цієї сторони API можна використовувати підготовлену бібліотеку PHP. Бібліотека наразі потребує PHP 5.4 або новішої версії та потребує використання Composer.

Інструкції з використання бібліотеки та вихідного коду є на GitHub .

Запит авторизації

Коли API увімкнено, партнер отримуєpartner_token іapi_secret , які використовуються для автентифікації під час виклику Slevomat API.

Ці параметри передаються вX-PartnerToken іX-ApiSecret заголовки.

Тестовий інтерфейс

Коренева URL-адреса тестового інтерфейсу

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

На ньому можна викликати всі дії, як на живому інтерфейсі.

Тестовий інтерфейс перевіряє авторизацію запитів (коректність партнерського токена та секрету API) і валідність тіл вхідних запитів (JSON). У цьому відношенні він поводиться ідентично живому API.

Однак інтерфейс тестування не працює з реальними замовленнями. Таким чином, він не перевіряє, чи замовлення переходить між правильними станами та чи містить воно елементи з заданими ідентифікаторами. Після проходження авторизації та перевірки форми запиту тестовий інтерфейс завжди відповідає коду успіху 200 або 204.

Створення скасування

Створює скасування позицій замовлення у вказаній кількості. Якщо замовлення має бути скасовано повністю, перераховуються всі товари з відповідною кількістю.

Окремі позиції можна також частково скасувати (наприклад, 1 із 2).

Повідомлення про скасування (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

{ "autoMarkDeli­vered": true }

Відповідь 200

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

Змінити статус замовлення на "Готовий до особистого забору"

Ви можете використовувати параметрautoMarkReady­ForPickup щоб указати, чи потрібно автоматично переводити замовлення в статус «Готовий для особистого отримання» після закінчення часу від відправлення до доставки для даного типу пункту прийому.

Для замовленняautoMarkDelivered Параметр можна використовувати, щоб вказати, чи повинен він автоматично перемикатися зі статусу «Готовий для особистого отримання» на статус «Доставлено клієнту — очікує підтвердження клієнта» після встановленої кількості днів для збору в певному типі пункту прийому.

Поєднання параметрівautoMarkReady­ForPickup помилкові іautoMarkDelivered правда не допускається. У цьому випадку буде повернено код помилки 9.

Відповідь містить оновлену очікувану дату доставки.

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

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

Відповідь 200

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

Змінити статус замовлення на "Готовий до особистого забору"

TheautoMarkDelivered Параметр можна використовувати для вказівки, чи потрібно автоматичне переведення замовлення в статус «Доставлено клієнту — очікує підтвердження клієнта» після встановленої кількості днів для збору в даному типі пункту прийому.

POST /order/$slevo­matId/mark-ready-for-pickup

{ "autoMarkDeli­vered": true }

Змінити статус замовлення на "Доставлено клієнту – очікується підтвердження клієнта"

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

{}

Змінити адресу доставки

Адреса доставки може бути змінена тільки для доставки за адресою (тобто місце особистого отримання не може бути змінено).

Усі ключі, крімcompany потрібні.

Дійсні значення дляstate ключові єcz (Чехія) іsk (Словаччина).

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" }

Журнал змін