Автоотправка лицензий через веб-сервис

Веб-сервис – это способ генерации лицензий для электронной доставки продуктов покупателям.

При этом способе доставки на вашей стороне должен быть разработан веб-сервис, который будет по запросу с нашей стороны генерировать лицензию на продукт и возвращать ее в ответе. Мы отправим полученную лицензию на почту покупателю.

Поддерживается:

• Метод передачи данных: POST или GET
• Формат лицензий: текст
  Если лицензия является файлом, то она должна быть сохранена на вашей стороне и быть доступна по ссылке. В качестве лицензии вы передаете ссылку на файл с ней

Безопасность взаимодействия обеспечивается с помощью проверки подписи в заголовке каждого запроса.

• Покупатель успешно оплачивает заказ
• Ваш веб-сервис получает запрос на лицензию для продукта заказа. Запрос может содержать дополнительные данные о заказе/продукте/покупателе
• Ваш веб-сервис генерирует лицензию на основании полученных данных и отвечает на запрос (синхронное взаимодействие)
• Далее лицензия будет:
  • Сохранена в заказ (далее это может использоваться для повторной отправки покупателю при необходимости)
  • Отправлена покупателю по почте
  • (Опционально) Показана покупателю на странице заказа
• На нашей стороне выполняется стандартная обработка успешной доставки заказа

Шаг отправки письма с лицензией покупателю можно отключить. В этом случае:

• Ваш веб-сервис получит запрос на генерацию лицензии и должен вернуть ответ об успешной обработке запроса (HTTP/1.1 200 OK)
• На нашей стороне выполнится стандартная обработка успешной доставки заказа
• Вы должны самостоятельно отправить лицензию покупателю (лицензия не будет сохранена на нашей стороне)

Если при взаимодействии с вашим веб-сервисом произошла ошибка, то она может быть воспринята как временная или фатальная:

• Временной ошибкой считаются ситуации:
  • Ваш веб-сервис был недоступен
  • Ваш веб-сервис вернул ответ, который совпал с шаблоном временной ошибки в настройках веб-сервиса
  В этих случаях будут автоматически выполняться повторные запросы к вашему веб-сервису:
  • Число повторных попыток: 4
  • Периодичность попыток: через 1 минуту, 30 минут, 2 часа, 24 часа с момента оплаты заказа
• Фатальной ошибкой считаются ситуации:
  • Ваш веб-сервис вернул ответ, который совпал с шаблоном фатальной ошибки в настройках веб-сервиса

Каждый запрос к вашему веб-сервису содержит подпись в заголовке запроса. Используйте проверку подписи, чтобы подтвердить, что запрос отправлен именно нами.

Формат подписи:

• Hash от строки, в которой перечислены:
  • секретный ключ - значение задается в настройках веб-сервиса на нашей стороне
  • значения всех параметров в запросе, отсортированные в алфавитном порядке по названию параметра
• Разделитель значений: ;
• Алгоритм генерации: SHA-512

Пример генерации подписи для данных:

• Секретный ключ = secret0!
• Параметры запроса (метод GET): ?Order=19583505&ID=19583478&Quantity=1

Формирование подписи:

• Определяем порядок следования параметров по названию (сортировка в алфавитном порядке): ID, Order Quantity
• Составляем строку значений параметров: 19583478;19583505;1
• Добавляем в строку секретный ключ: secret0!;19583478;19583505;1
• Получаем SHA-512 от строки: secret0!;19583478;19583505;1

Итоговое значение подписи в заголовке запроса:

• signature: "f9ed72bc7006a047f15a7cb62556342bff5463defd14f3b0dabdcebf757b33620eb8a4a0d08c512fcda20de926e37819865ea5f511070ab130d374dd1820ded5"

Вы можете управлять данными, которые будут переданы в запросе к вашему веб-сервису. По умолчанию запрос не содержит каких-либо данных.

• Формат передачи данных для метода POST: JSON
• Кодировка: UTF-8

Предположим:

• Ваш веб-сервис доступен по адресу: https://you-company.com/license
• Вы хотите, чтобы в запросе были переданы:
  • Номер заказа
  • ID продукта
  • Количество продукта в заказе
  • Валюта заказа
  • Значение дополнительного параметра Referer1
• Покупатель оплатил заказ № 19583505 на 1 шт. продукта с идентификатором 19583478 (валюта: рубли, значение Referer1: 123)

В этом случае:

• При использовании метода GET:
  • Мы отправим запрос на лицензию к вашему веб-сервису на адрес:

• При использовании метода POST:
  • Мы отправим запрос на лицензию к вашему веб-сервису на адрес: https://you-company.com/license
  • Тело запроса будет содержать параметры: 

Ваш веб-сервис должен ответить на наш запрос следующим образом:

• В случае успешной обработки запроса ответ должен содержать:
  • HTTP/1.1 200 OK
  • Лицензию на продукт в теле письма 
    Может отсутствовать, если отправка нашего письма с лицензией отключена
• В случае неуспешной обработки:
  • HTTP статус отличающийся от статуса успешной обработки
  • (Опционально) Текст ошибки - настройки веб-сервиса позволяют задать тексты временных и фатальных ошибок для гибкой обработки этих ситуаций, подробнее см. в описании настроек веб-сервиса

После того, как лицензия получена от вашего веб-сервиса, система формирует письмо с лицензией и отправляет его покупателю по почте. Отправку письма можно отключить, в этом случае вы должны самостоятельно доставить лицензию покупателю.

Сценарии работы:

• Письмо с лицензией отправляем мы (рекомендуемый вариант)
• Письмо с лицензией отправляете вы

В этом сценарии мы получаем лицензию от вашего веб-сервиса, после чего формируем письмо с лицензией и отправляем его покупателю. Помимо этого, на нашей стороне будет выполнена стандартная обработка успешной доставки заказа.

Вы можете управлять блоком текста, с помощью которого лицензия подставляется в письмо.
Управление доступно через:

• Merchant Portal - для получения лицензии через веб-сервис; этот текст используется в качестве текста по умолчанию для всех продуктов 
• Product API - для получения лицензии через любой способ генерации; если этот текст заполнен, то он используется вместо текста по умолчанию; настраивается индивидуально для определенного продукта и каждого языка интерфейса
• По запросу в техподдержку

Особенности настройки текста:

• В тексте обязательно используйте тег {KEY} - вместо него будет подставлена лицензия, полученная от вашего веб-сервиса
• Вы можете использовать дополнительные теги подстановки, чтобы добавить в письмо информацию о заказе, продукте, покупателе
• Обратите внимание, текст, который вы заполните, будет подставлен в наш шаблон письма с приветствием и подписью, данными о заказе, поэтому вам не нужно включать эти данные в блок с лицензией. Посмотрите пример письма. Если вы хотите отредактировать части шаблона, которые управляются на нашей стороне, то обратитесь в техподдержку

Вы можете отключить отправку нашего письма с лицензией покупателю в настройках веб-сервиса через Merchant Portal или по запросу в техподдержку.

В этом случае:

• Ваш веб-сервис должен вернуть HTTP/1.1 200 OK
• На нашей стороне будет выполнена стандартная обработка успешной доставки заказа
• Отправка лицензии покупателю должна быть выполнена на вашей стороне

Подключение веб-сервиса к продуктам зависит от способа управления продуктами:

• Merchant Portal - настройка доставки выполняется также через Merchant Portal, можно настроить один общий веб-сервис для всех ваших продуктов
• Product API - возможные варианты:
  • Автоматическая привязка к способу генерации по умолчанию.
  • Индивидуальная привязка продукта к определенному способу генерации лицензии при помощи передачи параметра fulfillment_id.
• Dynamic Product Checkout API:
  • Вы можете управлять базовым продуктом через Merchant Portal или Product API, как описано выше.
  • Или обратиться в службу поддержки.
• Другие способы управления продуктами - настройка доставки выполняется по запросу в службу поддержки.

С помощью Merchant Portal вы можете совершить покупку в тестовой среде без оплаты заказа реальными средствами.

Для этого:

• Переключите портал в тестовый режим работы
• Создайте хотя бы один продукт
  Вы также можете использовать Product API, подключенное через Ключи API, или создать продукт, который затем используете в качестве базового для работы через Dynamic Product Checkout API
• Подключите доставку через веб-сервис к вашим продуктам (для всех способов создания продукта)
• Добавьте продукт в корзину с помощью ссылки на покупку
  Ссылку на покупку вы можете составить вручную, получить через Merchant Portal или Dynamic Product Checkout API (в зависимости от вашего сценария работы)
• Совершите покупку через корзину:
  • Заполните данные покупателя, при этом укажите свой email в качестве почты покупателя, чтобы в дальнейшем получить на него письмо с лицензией
  • Подтвердите согласие с условиями продажи (если требуется) и нажмите кнопку Продолжить, чтобы подтвердить создание заказа
  • Оплатите заказ с помощью тестовых платежных средств
• После этого система выполнит запрос к вашему веб-сервису для получения лицензии
• В случае успешного получения лицензии:
  • (Опционально) Вы увидите лицензию на странице оплаченного заказа в корзине
  • (Опционально) Вы получите письмо с лицензией на почту, указанную в данных покупателя
  • (Опционально) Ваш веб-сервис получит webhook-оповещение об успешной доставке (product.delivered)
  • В портале ESupport дополнительный статус заказа изменится на Delivered (вы можете перейти в портал ESupport через раздел Оплаты в Merchant Portal)
• В случае ошибки никаких дополнительных действий не предусмотрено. Если вы не получили письма с лицензионной информацией:
  • Проверьте папку для спама в почтовом приложении, возможно письмо с лицензией попало туда
  • Проверьте логи взаимодействия вашего веб-сервиса, чтобы установить причину, по которой лицензия не была отправлена в ответ на наш запрос
  • При необходимости обратитесь в нашу техподдержку для проверки логов на нашей стороне
• Если вы совершили покупку в тестовом режиме, то дальнейшие действия не требуются
• Если ваш веб-сервис выдал действующую лицензию (не тестовую), то аннулируйте ее на своей стороне

Если вы хотите протестировать доставку лицензий в боевом режиме, то:

• При использовании Merchant Portal отключите тестовый режим работы
• Создайте хотя бы один продукт
  Вы также можете использовать Product API, подключенное через Ключи API, или создать продукт, который затем используете в качестве базового для работы через Dynamic Product Checkout API
• Подключите доставку через веб-сервис в вашим продуктам (в зависимости от того, какой способ создания продуктов вы используете)
• Добавьте продукт в корзину с помощью ссылки на покупку
  Ссылку на покупку вы можете составить вручную, получить через Merchant Portal или Dynamic Product Checkout API (в зависимости от вашего сценария работы)
• Создайте заказ через корзину:
  • Заполните данные покупателя, при этом укажите свой email в качестве почты покупателя, чтобы в дальнейшем получить на него письмо с лицензией
  • Подтвердите согласие с условиями продажи (если требуется) и нажмите кнопку Продолжить
• Оплатите заказ реальными денежными средствами или обратитесь в поддержку для смены статуса заказа вручную
• После этого система выполнит запрос к вашему веб-сервису для получения лицензии
• В случае успешного получения лицензии:
  • (Опционально) Вы увидите лицензию на странице оплаченного заказа в корзине
  • (Опционально) Вы получите письмо с лицензией на почту, указанную в данных покупателя
  • (Опционально) Ваш веб-сервис получит webhook-оповещение об успешной доставке (product.delivered)
  • В портале ESupport дополнительный статус заказа изменится на Delivered (вы можете перейти в портал ESupport через раздел Оплаты в Merchant Portal)
• В случае ошибки никаких дополнительных действий не предусмотрено. Если вы не получили письма с лицензионной информацией:
  • Проверьте папку для спама в почтовом приложении, возможно письмо с лицензией попало туда
  • Проверьте логи взаимодействия вашего веб-сервиса, чтобы установить причину, по которой лицензия не была отправлена в ответ на наш запрос
  • При необходимости обратитесь в нашу техподдержку для проверки логов на нашей стороне
• Перейдите на портал ESupport и отправьте заявку на возврат по заказу. В качестве причины заказа укажите "Тестовый заказ" и опишите каким образом была выполнена оплата заказа (реальными денежными средствами или с помощью техподдержки)

Если доставка подключена через Merchant Portal, то вы можете воспользоваться функцией отправки тестового запроса к вашему веб-сервису. Это не требует совершения покупки через корзину.

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

Для этого:

• Создайте тестовый веб-сервис (Mock Server), например, с помощью Postman (см. инструкцию по настройке на сайте Postman)
• При создании вы получите URL веб-сервиса
• Используйте этот URL при настройке подключения к веб-сервису
• Инициируйте тестовый запрос или совершите тестовую покупку
• Проверьте тестовый веб-сервис (на том сайте, где вы его создавали). Вы сможете увидеть содержание полученного запроса

Если вы хотите протестировать обработку доставки (например, получение вебхук-оповещения, письма с лицензией и т.п.), но у вас еще нет веб-сервиса и вы не хотите настраивать эмулятор на своей стороне, то вы можете подключить нашу эмуляцию веб-сервиса через Merchant Portal.

Это наш веб-сервис, который выдает тестовые лицензии по запросу. Узнайте подробнее, как это сделать.