Продажи на маркетплейсе AllsoftУправление каталогомДоставка продуктов

Веб-сервис

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

Обзор возможностей

Веб-сервис это способ получения ключа (лицензии) для электронной доставки продукта покупателю.

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

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

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

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

Как это работает

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

Управление веб-сервисами

Для управления веб-сервисами:

Откройте Кабинет разработчика:
- Авторизуйтесь на сайте https://allsoft.ru/.
- Перейдите в личный кабинет (нажмите на свой e-mail в верхней части страницы сайта).
- В меню слева выберите пункт Кабинет разработчика (доступен после заключения договора).
Перейдите в раздел Управление веб-сервисами (https://secure.ecommerce.softline.com/author_keys_new.php?mode=webservices).

Далее вы можете:

Создать новый веб-сервис - для этого:
- Нажмите на ссылку [+] Создание нового запроса к веб-сервису.
- Заполните поля формы.
Отредактировать веб-сервис - для этого нажмите на его название в таблице (поля формы редактирования такие же как и при создании веб-сервиса).
Удалить веб-сервис - для этого включите чекбокс напротив его названия в таблице и нажмите кнопку Удалить.

Свойства веб-сервиса

Название

Название веб-сервиса
Любое значение на ваш выбор. Не отображается покупателю.

url

Адрес веб-сервиса на вашей стороне
На этот адрес будут приходить запросы на генерацию лицензии. URL должен быть доступен по протоколу HTTPS.

Активность

Активность
Обработка доставки лицензий будет выполняться через веб-сервис, только если он активный.

Шаблон уведомления с лицензионной информацией

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

Отправлять столько ключей, сколько копий программы заказано

Настройка отправки лицензий в зависимости от количества продукта в заказе

Включено - отправляется 1 лицензия для каждой единицы продукта в заказе. То есть при покупке нескольких штук одного и того же продукта, нужно отправить покупателю такое же количество лицензий (например, если в заказе 5 штук одного продукта, то будет отправлено 5 лицензий). Все полученные лицензии будут отправлены покупателю на почту в одном письме.
Выключено - отправляется 1 лицензия на продукт, независимо от количества приобретенных единиц (например, если в заказе 5 штук одного продукта, то будет отправлена одна общая лицензия).

Метод отправки данных

Метод взаимодействия

GET - параметры будут переданы вашему веб-сервису в адресной строке в виде: http://[url-вашего-веб-сервиса]?=[название_параметра1]=[значение_параметра1]&[название_параметра2]=[значение_параметра2] и т.д.
POST form data - параметры будут переданы в теле запроса в виде массива данных.
POST form JSON - параметры будут переданы в теле запроса в формате JSON.

Кодировка данных windows-1251 в запросе

Кодировка данных в запросе
Включите, если в запросе необходимо передать данные в формате win-1251. Для JSON формата кодировка win-1251 не поддерживается. Если не включать, то данные будут переданы веб-сервису в utf-8.

Не высылать письмо с ключом

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

postpone

Отложенное получение ключей

Используется для специфичных сценариев получения и отправки ключей. Если Вы не знаете, что означает данный параметр – оставьте поле пустым.

Имя пользователя

Логин для авторизации при обращении к веб-сервису
Заполните, если при обращении к вашему веб-сервису необходима авторизация.

Пароль

Пароль для авторизации при обращении к веб-сервису
Заполните, если при обращении к вашему веб-сервису необходима авторизация.

Шаблон(ы) фатальной ошибки

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

Полученный ответ не будет отправлен покупателю.
Продукт не будет считаться доставленным.
Повторых попыток получить лицензию не будет выполнено.

Шаблон(ы) временной ошибки

Шаблоны временных ошибок
Строка, наличие которой в ответе вашего веб-сервиса обозначает, что веб-сервис не может временно ответить на запрос. При этом:

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

Параметры запроса

Данные в запросе
Данные, которые необходимо передать в запросе к вашему веб-сервису для получения лиценнзии. Задаются в виде пар "Поле", "Значение". Можно использовать коды подстановки, которые будут замещены реальными данными при отправке запроса. Список доступных тегов подстановки см. справа от формы добавления параметров.

Параметры запроса

{ORDER}

Идентификатор заказа

{CREATE_DATE}

Дата создания заказа (по МСК).
Формат: гггг-мм-дд

{ITEM}

Идентификатор позиции заказа.
Это наш внутренний идентификатор, присваиваемый продуктам внутри заказа при его создании, на текущий момент не используется в других API. Не является идентификатором ценовой группы.

{ID_PROG}

Идентификатор программы

{ID_VER}

Идентификатор версии

{ID}

Идентификатор ценовой группы (идентификатор продукта)

{PROGRAM}

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

{PR_SHORT}

Название программы

{CODE}

Ваш внутренний код продукта, который можно задать на уровне ценовой группы (Код).

{FULLNAME}

Фамилия и имя покупателя

{FNAME}

Имя покупателя

{LNAME}

Фамилия покупателя

{EMAIL}

Email покупателя

{ZIPCODE}

Почтовый индекс покупателя

{COUNTRY}

Страна покупателя

{CITY}

Город покупателя

{ADDRESS}

Адрес покупателя

{PHONE}

Телефон покупателя

{COMPANY}

Компания покупателя (заполняется, если заказ оформлен на юр.лицо).

{INN}

ИНН (заполняется, если заказ оформлен на юр.лицо).

{LICENCE}

Данные лицензиата (краткие).
Могут отличаться от данных покупателя, если при оформлении заказа была выбрана опция оформить лицензию на другое лицо. В этом случае:

Если заказ оформлен на физ.лицо, то в параметре передаются Имя и Фамилия лицензиата
Если заказ оформлен на юр.лицо, то в параметре передаются Название Компании лицензиата

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

{LICENCE_FULL}

Данные лицензиата (полные данные).
Могут отличаться от данных покупателя, если при оформлении заказа была выбрана опция оформить лицензию на другое лицо. Если опция "оформить лицензию на другое лицо" не была выбрана, то в полях будут переданы соответствующие данные покупателя.

{QUANTITY}

Количество продукта в заказе

{SUMMA}

Итоговая стоимость продукта в руб.

Передается в рублях. Если валюта заказа отличается от рублей, то осуществляется конвертация
Учитывает количество продукта в заказе, НДС, скидку
Формат: число с 2 десятичными знаками, разделитель - точка, передается как строка

{SUMMA_ORDER_CURRENCY}

Итоговая стоимость продукта в валюте заказа

Передается в валюте заказа
Учитывает количество продукта в заказе, НДС, скидку
Формат: число с 2 десятичными знаками, разделитель - точка, передается как строка

{SUMMA_WITHOUT_VAT_ORDER_CURRENCY}

Итоговая стоимость продукта без НДС в валюте заказа

Передается в валюте заказа
Учитывает количество продукта в заказе, скидку
Формат: число с 2 десятичными знаками, разделитель - точка, передается как строка

{SHARE}

Процент вашей доли от продажи продукта

{SHARE_ORDER_CURRENCY}

Сумма вашей доли от продажи продукта в валюте заказа.
Формат: число с 2 десятичными знаками, разделитель - точка, передается как строка.

{CURRENCY}

Код валюты заказа.
Формат: ISO 4217 alpha-3, 3 символа.

{MARGIN}

Сумма вашей доли от продажи продукта в валюте взаиморасчетов. Рассчитывается аналогично тому, как описано в экспорте заказов.
Формат: число с 2 десятичными знаками, разделитель - точка, передается как строка.

{MARGIN_CURRENCY}

Код валюты взаиморасчетов.
Формат: ISO 4217 alpha-3, 3 символа.

{ZONE}

Код зоны заказа (определяется по валюте продажи), например, RU.

{DAY}

Число из текущей даты (МСК).

{MONTH}

Месяц из текущей даты (МСК).

{YEAR}

Год из текущей даты (МСК).

{HOUR}

Час из текущего времени (МСК)

{MIN}

Минута из текущего времени (МСК)

{SEC}

Секунда из текущего времени (МСК)

{RND}

Случайное число

{AF}

Данные из дополнительного поля, если оно было настроено для ценовой группы.

{REFERER1}-{REFERER6}

Дополнительный параметр заказа.
Служебный параметр заказа с соответствующим названием (referer1, referer2 и т.д.). Узнайте подробнее о дополнительных параметрах. Обратите внимание, срок хранения дополнительных параметров в заказе ограничен.

{API.REFERER7}-{API.REFERER12}

Дополнительный параметр заказа.
Служебный параметр заказа с соответствующим названием (referer7, referer8 и т.д.). Узнайте подробнее о дополнительных параметрах. Обратите внимание, срок хранения дополнительных параметров в заказе ограничен.

{SUBSCRIPTION_ID}

Идентификатор подписки.
Заполняется только если на продукт есть активная подписка. Учитвает AR и PMR подписки.

{SUBSCRIPTION_PERIOD}

Срок действия продукта из подписки.

Формат: ISO 8601 code: P[число][ед.измерения].
Поддерживаемые единицы измерения: Y - год, M - месяц, D - день. Например, "P1Y" соответствует сроку "1 год".

{KEY_FIRST_RENEW}

Лицензия на продукт (ключ), инициирующий подписку. Для продуктов с подпиской - лицензия на продукт, который был инициатором подписки. Например, если отправляется запрос на получение лицензии по заказу на продление (дочерний заказ), то в этом параметре будет отправлена лицензия из родительского заказа (первый заказ в подписке).

{KEY_LAST_RENEW}

Последняя выданная лицензия в рамках подписки. Для продуктов с подпиской - лицензия на продукт, выданная в предыдущем заказе в рамках подписки. Например:

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

{LOCALE}

Код языка интерфейса корзины. Варианты значений см. в справочнике.

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

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

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

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

При использовании метода GET:
Мы отправим запрос на лицензию к вашему веб-сервису на адрес:
https://you-company.com/license?Order=19583505&ID=19583478&Quantity=1&Currency=RUB&Referer1=123
При использовании метода POST и формата JSON:
Мы отправим запрос на лицензию к вашему веб-сервису на адрес: https://you-company.com/license
Тело запроса будет содержать параметры:

{
  "Order": "19583505",
  "ID": "19583478",
  "Quantity": "1",
  "Currency": "RUB",
  "Referer1": "123"
}

Тестирование веб-сервиса

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

Для этого:

Оформите тестовый заказ на программу (для которой выполнили настройку веб-сервиса).
При оформлении заказа на этапе подтверждения заполните поле Комментарий к заказу, указав в нем, что производится тестовый заказ.
Сообщите номер заказа в службу поддержки.
Мы переведем заказ в статус "оплачен" вручную. При этом будет инициированы получение и отправка лицензионной информации через веб-сервис.

Блокировка лицензий

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