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
• параметры: 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
• параметры: 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.