Цей API призначений для надання Slevomat.cz коду ваучера після того, як клієнт оплатить замовлення на угоду. Зазвичай Slevomat.cz генерує власний код ваучера, але за допомогою цього API наш діловий партнер може повідомити про замовлення та створити власний код ваучера для клієнта.
Усі запити виконуються через протокол HTTPS (який вимагає, щоб сервер бізнес-партнера підтримував HTTPS і мав дійсний сертифікат), а всі дані мають бути відформатовані як JSON .
Журнал змін
01. 03. 2017 – додано розділ обробки недійсних запитів
10. 02. 2017 – початкова версія
Увімкнення API
Усі запити виконує додаток Slevomat.cz, надсилаючи запит на сервер партнера. Запит буде міститиX-RequestToken HTTP-заголовок із секретним рядком. Цей рядок повинен бути перевірений сервером партнера , щоб гарантувати безпеку. Цей секретний рядок відомий лише Slevomat.cz та партнеру.
Щоб увімкнути API, партнер повинен запитати Slevomat.cz і надати URL-адресу, де буде API, наприклад:
https://example.com/slevomat-external-voucher-code/generate
Після того, як Slevomat.cz увімкне API для партнера та надасть партнеруX-RequestToken значення, він лише в режимі тестування, тобто жодні реальні замовлення не виконуватимуть запит на отримання спеціального коду ваучера. Але це дозволяє партнеру розробляти та тестувати API на своєму сервері за допомогою наданогоX-RequestToken значення.
Після розробки та тестування API на сервері партнера Slevomat.cz переведе режим реальних замовлень. Замовлення для угод, які почали продаватися після переходу, запитуватимуть API партнера для спеціальних кодів ваучерів.
Генерація коду ваучера
Коли замовлення на угоду оплачено, Slevomat.cz надішле запит POST на сервер партнера для генерації коду ваучера та надасть партнеру певну інформацію про замовлення. Цей запит буде надіслано окремо для кожної проданої одиниці.
Запит містить необхідний префікс коду ваучера. Згенерований код ваучера має починатися з цього префікса .
Тіло запиту буде виглядати так:
{ "uuid": "91987a73-095c-4b94-bd38-f6ffd4ab86a7", "deal": { "product_id": 123, "product_name": "Aktivní dovolená: 4 až 6 dní s all inclusive v Rakousku. 2 děti do 8,9 let zdarma!", "variant_id": 456, "variant_name": "1 osoba | 4 dny (3 noci) | Období So 13. 5. – So 24. 6. 2017, Ne 27. 8. – Ne 5. 11. 2017" }, "customer": { "email": "cu******@ex*****.com" }, "voucherCodePrefix": "LIN", "repeatReason": 1 }Сервер має відповісти HTTP-кодом статусу 200, а тіло відповіді зі згенерованим кодом ваучера має виглядати так:
{ "voucherCode": "LIN1234567890" }Сервер повинен відповісти протягом 10 секунд , інакше запит позначається як невдалий. Згенерований код ваучера має починатися з заданого префікса та бути унікальним. Існують інші причини, чому ми можемо не прийняти згенерований код ваучера.
Якщо запит не виконується, він повторюється з причиною в поліrepeatReason поле, доки воно не буде успішним. Це поле міститиме одне з таких значень:
| Повторіть причину | опис |
|---|---|
| 1 | Перша спроба. |
| 2 | Підключення до сервера не вдалося. Це може означати недійсний сертифікат HTTPS або те, що мережа не працює. |
| 3 | Сервер не відповів вчасно. |
| 4 | Сервер відповів кодом статусу HTTP, відмінним від 200. |
| 5 | Сервер відповів HTTP 200, але тіло відповіді не містило JSON або JSON не містив ключа voucherCode. |
| 6 | Згенерований код ваучера не містить необхідного префіксу. |
| 7 | Згенерований код ваучера містив недійсні символи. Тільки допустимі символи:[a-zA-Z0-9-]+ . |
| 8 | Згенерований код ваучера не був унікальним. |
Тіло запиту завжди буде містити те самеuuid ідентифікатор як попередній запит на створення коду ваучера для того самого замовлення клієнта.
Обробка недійсного запиту
Коли виникне запит, який не відповідає вимогам безпеки, тобто містить недійсний запитX-RequestToken , сервер повинен відповісти HTTP-кодом 403 Forbidden.
Тестування реалізації API
Увійдіть як наш партнер, щоб побачити свій статус API, протестувати та перевірити впровадження API.