Партнерський API Slevomat.cz

API використовується для передачі інформації про ваучери між Slevomat і системою бізнес-партнера. Це дозволяє партнеру перевірити дійсність ваучерів у своїй системі та викупити ваучери. Партнеру не потрібно використовувати для цього інтерфейс партнера.

Можливі приклади використання:

• Клієнт купує ваучер, послуга якого залежить від введення коду на сайті партнера під час створення замовлення. Завдяки API дійсність ваучера відразу перевіряється після цього введення. Потім вартість ваучера вираховується з кошика партнера, і ваучер автоматично погашається в Slevomat.
• Таким же чином можна також перевірити дійсність ваучерів у системі бронювання партнера або завантажити придбаний кредит на певну вартість безпосередньо на сайті партнера.

API партнера потребує маркера, який є унікальним для кожного партнера та надсилається як частина кожного запиту. Щоб скористатися партнерським API, зверніться до свого/нашого торгового представника.

Формат запиту

Точка доступу до API розташована за адресою /api.

Формат запиту такий

<URL přístupového bodu>/<akce>[<pa­rametry>]

Усі запити є стандартними HTTP-запитами GET, тобто запит на перевірку дійсності ваучера може виглядати так:

https://www.slevomat.cz/api/vouchercheck?code=1234-5677-77-111&token=123456789012345.

Формат відповіді

Відповідь сервера завжди надається у форматі JSON із відповідним заголовком Content-type. Основна структура відповіді така.

{
 "result": true,
 "data": {
 ...
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Значення результату – true (у разі успіху) або false (у разі помилки). У разі помилки запис про помилку містить код помилки (код ) та її опис (повідомлення ). Крім вказівки в полі помилки, у разі помилки система повертає відповідний код статусу HTTP (400, 401, 403, 404).

Елемент даних містить дані, які повертає викликана дія, і його вміст є індивідуальним.

Усі дані мають формат РРРР-ММ-ДДТГГ:ХМ:ССЗ (ISO8601; наприклад, 2011–01–01T10:10:10+02:00).

Підтвердження ваучера

• дія: voucherCheck
• параметри: токен (обов'язковий; унікальний партнерський токен), код (обов'язковий; код ваучера)

Є три коди тестових ваучерів:

• 1234–5677–77–111 (платний, невикористаний),
• 2234–5688–88–222 (платно, б/у),
• 3234–5699–99–333 (неоплачений, невикористаний).

Якщо програма використовує один із цих кодів, сервер поверне відповідну відповідь (у випадку оплаченого та невикористаного ваучера він також поверне зразок ваучера та дані про подію).

Формат даних відповіді

{
 "token": <auth token>,
 "code": <voucher code>,
 "voucherData": <voucher data>
}

Параметр voucherData містить визначення ваучера в такому форматі.

{
 "id": <Voucher ID>,
 "orderId": <Order ID>,
 "title": <voucher title>,
 "ordered": <order date and time; datetime>,
 "paidDate": <order paid date; date>
 "validFrom": <voucher validity start; date>,
 "validTo": <voucher validity end; date>,
 "key": <voucher code>,
 "code": <voucher code,
 "product": <promotion ID>,
 "productName": <promotion title>,
 "variant": <variant ID>,
 "variantName": <variant title>,
 "imageUrl": <URL image>,
 "smallImageUrl": <URL image>,
 "productUrl": <URL image>,
 "reservationTime": <Reservation time if voucher is reserved; datetime>
}

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

• Код 1101 (код статусу HTTP 400): маркер автентифікації або код ваучера не введено,
• Код 1102 (код статусу HTTP 403): маркера немає в базі даних,
• код 1103 (код статусу HTTP 404): ваучер із вказаним кодом не існує,
• код 1104 (код статусу HTTP 401): замовлення, за яким був виданий ваучер, не оплачено,
• код 1105 (код статусу HTTP 401): ваучер уже використано,
• код 1106 (код статусу HTTP 401): ваучер повернено,
• код 1107 (код статусу HTTP 401): замовлення або ваучер скасовано,
• код 1108 (код статусу HTTP 401): подія вже виставлена ​​партнеру; жодні інші ваучери не можуть бути заявлені,
• код 1109 (код статусу HTTP 401): ваучери на цю подію ще не почали діяти,
• код 1111 (код статусу HTTP 500): внутрішня помилка сервера,
• код 1112 (код статусу HTTP 403): ваучер потрібно використовувати лише через бронювання

Приклад запиту

https://www.slevomat.cz/api/vouchercheck?code=1234-5677-77-111&token=123456789012345

Приклад відповіді

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <název voucheru>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Викуп ваучера

• Дія: ваучерПодати заявку
• параметри: токен (обов'язковий; унікальний партнерський токен), код (обов'язковий; код ваучера)

Спроби викупити ваучер за вказаним кодом.

Номер тестового ваучера можна використовувати для тестування. У цьому випадку ваучер не буде погашений, але система поверне відповідь, ніби він був погашений.

Формат даних відповіді

Формат відповіді точно такий же, як і для перевірки дійсності ваучера.

Умови помилок

• Код 1201 (код статусу HTTP 400): маркер автентифікації чи код ваучера не введено,
• Код 1202 (код статусу HTTP 403): маркера немає в базі даних,
• код 1203 (код статусу HTTP 404): ваучер із вказаним кодом не існує,
• код 1204 (код статусу HTTP 401): замовлення, за яким було видано ваучер, не було оплачено,
• код 1205 (код статусу HTTP 401): ваучер уже використано,
• код 1206 (код статусу HTTP 401): ваучер повернено,
• код 1207 (код статусу HTTP 401): замовлення або ваучер скасовано,
• код 1208 (код статусу HTTP 401): подія вже виставлена ​​партнеру; жодні інші ваучери не можуть бути заявлені,
• код 1209 (код статусу HTTP 401): термін дії ваучерів на цю подію ще не закінчився,
• код 1211 (код статусу HTTP 500): внутрішня помилка сервера
• код 1212 (код статусу HTTP 403): ваучер можна використовувати лише через бронювання

Приклад запиту

https://www.slevomat.cz/api/voucherapply?code=1234-5677-77-111&token=123456789012345

Приклад відповіді

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <název voucheru>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Примітка. Щоб використовувати Partner API для відрахування вартості або продуктів у вашому кошику, спробуйте включити кілька атрибутів параметра voucherData. Це особливо важливо, коли у вас є кілька діючих акцій із різною вартістю пропонованих продуктів. Зокрема, ми рекомендуємо використовувати атрибути продукту або варіанту.