API сторонніх товарів

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

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

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

Доступність API

Ви можете отримати доступ до API на вкладці «Налаштування» вашого партнерського інтерфейсу. Щоб отримати дані, вам потрібно ввести кореневу URL-адресу партнерської частини API для використання в напрямку Zlavomat → Партнер, наприклад

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 реалізована на стороні партнера, і Zlavovamat викликає її.

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

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

Авторизація запитів

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

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

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

Дисконтний автомат включає функціональність для виклику API на стороні партнера та відображення відповіді. Коренева URL-адреса, вказана партнером під час надання доступу до API, додається до-test , тому в рамках тестування 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

   – Скасувати

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

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

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

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

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

Нове замовлення

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

Замовлення завжди унікальніzlavomatId Якщо дублікат надходить до APIzlavomatId , партнерський API має ігнорувати запит (перший запит, зроблений Zľavomat, був оцінений як невдалий, тому ми його повторюємо) та також відповідати HTTP 204.

created — це дата у форматі ISO 8601, тобтоYYYY-MM-DD'T'HH:mm:ss­+zz:zz .

productId містить ідентифікатор дії, variantId Ідентифікатор придбаного варіанту.

Необов'язково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 .

ПОШТА /замовлення/$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", "expectedShip­pingDate": "2021–09–08", "expectedDeli­veryDate": "2021–09–11", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

ПОШТА /замовлення/$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ě", "expectedShip­pingDate": "2021–09–07", "expectedDeli­veryDate": "2021–09–07", "price": 0.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

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

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

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

POST /update-shipping-dates

{ "expectedShip­pingDate": "2021–09–06", "slevomatIds": [ "123456", "45454544" ] }

Скасувати

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

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

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

Примітка про скасування (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 а на стороні Zlavomat замовлення автоматично перейшло у статус «Готово до особистого самовивозу»

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

{}

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

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

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

{}

Партнер з комунікації ⇒ Дисконтний автомат

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

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

https://www.zlavomat.sk/zbozi-api/v1

Бібліотека PHP

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

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

Авторизація запитів

Коли API увімкнено, партнер отримуєpartner_token іapi_secret , що використовується для підтвердження під час виклику API Zlavomat.

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

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

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

https://www.zlavomat.sk/zbozi-api/v1-test

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

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

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

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

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

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

Примітка про скасування (note ) необов'язковий.

POST /замовлення/$slevomatId/скасувати

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

Зміна статусу замовлення на «Обробляється»

POST /замовлення/$slevomatId/очікується позначка

{}

Зміна статусу замовлення на «У дорозі»

При замовленні параметрautoMarkDelivered визначити, чи має статус автоматично змінюватися на «Доставлено клієнту – очікується підтвердження клієнта» після встановленого періоду транспортування («Час від відправлення до доставки»)

У відповіді міститься оновлена ​​орієнтовна дата доставки.

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

{ "autoMarkDeli­vered": true }

Відповідь 200

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

Зміна статусу замовлення на «Підготовка до особистого самовивозу»

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

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

Комбінація параметрівautoMarkReady­ForPickup хибний таautoMarkDelivered Значення «true» не дозволено. У цьому випадку повертається код помилки 9.

У відповіді міститься оновлена ​​орієнтовна дата доставки.

ПОШТА /замовлення/$slevomatId/марка-готовності-до-видачі

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

Відповідь 200

{ "expectedDeli­veryDate": "2021–09–06" }

Зміна статусу замовлення на «Готово до особистого самовивозу»

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

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