Этот API предназначен для предоставления Slevomat.cz кода ваучера после оплаты клиентом заказа по сделке. Обычно Slevomat.cz генерирует свой собственный код ваучера, но с помощью этого API наш деловой партнер может быть уведомлен о заказе и сгенерировать свой собственный код ваучера для клиента.
Все запросы выполняются по протоколу HTTPS (для чего требуется, чтобы сервер делового партнера поддерживал HTTPS и имел действительный сертификат), а все данные должны быть отформатированы в формате JSON .
Журнал изменений
01. 03. 2017 – добавлен раздел обработки недействительных запросов
10. 02. 2017 – первоначальная версия
Включение API
Все запросы выполняются приложением Slevomat.cz, отправляющим запрос на сервер партнера. Запрос будет содержатьX-RequestToken HTTP-заголовок с секретной строкой. Эта строка должна быть проверена сервером партнера для гарантии безопасности. Эта секретная строка известна только Slevomat.cz и партнеру.
Чтобы включить API, партнер должен обратиться к Slevomat.cz и предоставить URL-адрес, по которому будет расположен API, например:
https://example.com/slevomat-external-voucher-code/generate
После того, как Slevomat.cz включит API для партнера и предоставит партнеруX-RequestToken значение, он находится только в режиме тестирования, то есть никакие реальные заказы не будут выполнять запрос на получение пользовательского кода ваучера. Но это позволяет партнеру разрабатывать и тестировать API на своем сервере с предоставленнымX-RequestToken ценить.
После разработки и тестирования API на сервере партнера Slevomat.cz переключит режим на реальные заказы. Заказы по сделкам, продажа которых началась после переключения, будут запрашивать API партнера для получения пользовательских кодов ваучеров.
Генерация кода ваучера
Когда заказ на сделку оплачен, Slevomat.cz отправит POST- запрос на сервер партнера для генерации кода ваучера и предоставит партнеру некоторую информацию о заказе. Этот запрос будет отправлен индивидуально для каждой проданной единицы.
Запрос содержит обязательный префикс кода ваучера. Сгенерированный код ваучера должен начинаться с этого префикса .
Текст запроса будет выглядеть следующим образом:
{ "uuid": "91987a73-095c-4b94-bd38-f6ffd4ab86a7", "deal": { "product_id": 123, "product_name": "Aktivní dovolená: 4 až 6 dní s all inclusive v Rakousku. 2 děti do 8,9 let zdarma!", "variant_id": 456, "variant_name": "1 osoba | 4 dny (3 noci) | Období So 13. 5. – So 24. 6. 2017, Ne 27. 8. – Ne 5. 11. 2017" }, "customer": { "email": "cu******@ex*****.com" }, "voucherCodePrefix": "LIN", "repeatReason": 1 }Сервер должен ответить кодом статуса HTTP 200, а тело ответа со сгенерированным кодом ваучера должно выглядеть следующим образом:
{ "voucherCode": "LIN1234567890" }Сервер должен ответить в течение 10 секунд , в противном случае запрос помечается как неуспешный. Сгенерированный код ваучера должен начинаться с заданного префикса и должен быть уникальным. Существуют и другие причины, по которым мы можем не принять сгенерированный код ваучера.
Если запрос не удался, он повторяется с указанием причины вrepeatReason поле, пока не будет успешно. Это поле будет содержать одно из следующих значений:
| Повторить причину | Описание |
|---|---|
| 1 | Первая попытка. |
| 2 | Подключение к серверу не удалось. Это может означать либо недействительный сертификат HTTPS, либо то, что сеть не работает. |
| 3 | Сервер не ответил вовремя. |
| 4 | Сервер ответил кодом статуса HTTP, отличным от 200. |
| 5 | Сервер ответил HTTP 200, но тело ответа не содержало JSON или JSON не содержал ключ voucherCode. |
| 6 | Сгенерированный код ваучера не содержал требуемого префикса. |
| 7 | Сгенерированный код ваучера содержал недопустимые символы. Допустимы только следующие символы:[a-zA-Z0-9-]+ . |
| 8 | Сгенерированный код ваучера не был уникальным. |
Тело запроса всегда будет содержать одно и то жеuuid идентификатор, как и предыдущий запрос на генерацию кода ваучера для того же заказа клиента.
Обработка недействительного запроса
Когда возникнет запрос, не отвечающий требованиям безопасности, т.е. содержащий недействительныеX-RequestToken , сервер должен ответить HTTP-кодом 403 Forbidden.
Тестирование реализации API
Войдите в систему как наш партнер, чтобы увидеть статус вашего API, а также протестировать и проверить реализацию вашего API.