ПАРТНЕРСЬКИЙ ПОСІБНИК
Čeština Němčina Angličtina Chorvatština Maďarština Italština Polština Ruština Slovenština Slovinština Ukrajinština Vietnamština
Вступ Корисні посібники ІТ підтримка Партнерський API Slevomat.cz

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

Ця стаття була перекладена електронним перекладачем.

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

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

  • Клієнт купує ваучер, де для надання послуги при оформленні замовлення потрібно ввести код на сайті партнера. Завдяки API дійсність ваучера перевіряється одразу після введення коду. Його вартість потім віднімається у кошику партнера і одночасно ваучер автоматично погашається у Zľavomat.
  • Дійсність ваучерів також можна перевіряти у системі бронювання партнера аналогічним чином, або куплений кредит певної вартості може бути зарахований безпосередньо на рахунок клієнта на сайті партнера.

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

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

Кінцева точка API знаходиться за адресою /api.

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

<API endpoint URL>/<action>[<parameters>]

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

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

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

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

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

Значення елемента result — true (у разі успіху) або false (у разі помилки). У разі помилки елемент error містить код помилки (code) та її опис (message). Окрім вказівки у полі error, система також повертає відповідний HTTP статус-код (400, 401, 403, 404) у разі помилки.

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

Всі дати у форматі YYYY-MM-DDTHH:MM:SSZ (ISO8601; напр., 2011⁠–⁠01⁠–⁠01T10:10:10+0­2:00).

Перевірка дійсності ваучера

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

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

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

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

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

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

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

{
 "id": <voucher ID>,
 "orderId": <order ID>,
 "title": <voucher name>,
 "ordered": <order date and time; date and time>,
 "paidDate": <order payment date; date>
 "validFrom": <voucher validity start; date>,
 "validTo": <voucher validity end; date>,
 "key": <voucher code>,
 "code": <voucher code>,
 "product": <action ID>,
 "productName": <action name>,
 "variant": <action variant ID>,
 "variantName": <action variant name>,
 "imageUrl": <image URL>,
 "smallImageUrl": <thumbnail URL>,
 "productUrl": <action URL>
}

Елементи variant та variantName містять ID та назву замовленого варіанту дії, якщо дана дія містить варіанти. Якщо ні, обидва атрибути мають значення NULL.

Стан помилок

  • код 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): внутрішня помилка сервера

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

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

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

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <voucher name>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Погашення ваучера

  • action: voucherApply
  • parameters: token (обов'язково; унікальний токен партнера), code (обов'язково; код ваучера)

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

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

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

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

Стан помилок

  • код 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): внутрішня помилка сервера

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

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

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

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <voucher name>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Примітка: Для використання Партнерського API для віднімання вартості або товарів у кошику рекомендуємо включати більше атрибутів параметра voucherData. Це особливо важливо, якщо у вас кілька поточних дій з різними значеннями запропонованих товарів. Рекомендуємо використовувати особливо атрибути product або variant.

Повернутися до списку статей

Схожі статті

Вгору