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 (в случае ошибки). В случае ошибки запись об ошибке содержит код ошибки (code ) и ее описание (message ). Помимо указания в поле ошибки, система возвращает соответствующий код статуса 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
 }
}

Примечание: Чтобы использовать API партнера для вычета стоимости или продуктов в вашей корзине, рассмотрите возможность включения нескольких атрибутов параметра voucherData. Это особенно важно, если у вас есть несколько текущих акций с разной стоимостью предлагаемых продуктов. В частности, мы рекомендуем использовать атрибуты продукта или варианта.