API партнера Slevomat.cz

API используется для передачи информации о ваучерах между Zlavomat и системой бизнес-партнера. Он позволяет партнеру проверять действительность ваучеров в своей системе и использовать их. Партнеру не обязательно использовать для этого интерфейс партнера.

Возможные примеры использования:

• Клиент приобретает ваучер, условием предоставления услуги которого является ввод кода на сайте партнёра при оформлении заказа. Благодаря API, после ввода кода, действительность ваучера сразу же проверяется. Его стоимость списывается с корзины партнёра, а сам ваучер автоматически погашается в магазине Zlavomot.
• Аналогичным образом действительность ваучеров может быть проверена в системе бронирования партнера, или клиент может загрузить приобретенный кредит определенной стоимости непосредственно на сайт партнера.

Для использования партнерского API требуется токен, уникальный для каждого партнера и отправляемый с каждым запросом. Если вы хотите использовать партнерский API, обратитесь к вашему/нашему продавцу.

Формат запроса

Точка доступа API находится по адресу /api.

Формат запроса:

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

Все запросы являются стандартными 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
 }
}

Значение элемента результата — 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": <autentizační token>,
 "code": <kód voucheru>,
 "voucherData": <data voucheru>
}

Параметр voucherData содержит определение ваучера в следующем формате.

{
 "id": <ID voucheru>,
 "orderId": <ID objednávky>,
 "title": <název voucheru>,
 "ordered": <datum a čas objednávky; datum a čas>,
 "paidDate": <datum zaplacení objednávky; datum>
 "validFrom": <začátek platnosti voucheru; datum>,
 "validTo": <konec platnosti voucheru; datum>,
 "key": <kód voucheru>,
 "code": <kód voucheru>,
 "product": <ID akce>,
 "productName": <název akce>,
 "variant": <ID varianty akce>,
 "variantName": <název varianty akce>,
 "imageUrl": <URL obrázku>,
 "smallImageUrl": <URL náhledu>,
 "productUrl": <URL akce>
}

Элементы варианта или variantName содержат идентификатор или название заказанного варианта действия, если данное действие содержит варианты. В противном случае оба атрибута равны 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": <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): внутренняя ошибка сервера

Пример запроса

https://www.zlavomat.sk/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. Это особенно важно, если у вас запущено несколько кампаний с разной стоимостью предлагаемых товаров. Мы рекомендуем использовать в основном атрибуты товара или варианта.