[POST] Создание продукта
Описание запроса
POST /v1/product
Запрос позволяет создать продукт, который затем можно добавить в корзину по ссылке на покупку.
В запросе передаются:
- Данные для авторизации (токен)
- Основные свойства продукта
- Цены
- (Опционально) Настройки продления (AR/PMR/Email)
- (Опционально) Данные для локализации
- (Опционально) Настройки отображения продукта
- (Опционально) Данные для электронной доставки продукта
- (Опционально) Данные о наличии продукта в реестре российского ПО
- Маркетинговые инструменты:
Данные для отправки запроса
- Endpoint URL:
- Боевая среда: https://api.ecommerce.softline.com/v1/product
- Тестовая среда: https://api.ecommerce.softline.com.demoslweb.com/v1/product
- Метод: POST
- Формат: JSON
- Авторизация: с помощью токена
Авторизационный токен
- Формат значения:
Bearer [token]
- Вместо [token] подставьте значение token, полученное в ответ на запрос к Authentication API
Пояснение к названию продукта
Отображается покупателю в корзине (пример). Вы можете скрыть пояснение с помощью параметра display_settings.hide_name.
Не более 255 символов.
Отображается покупателю в корзине (пример). Вы можете скрыть пояснение с помощью параметра display_settings.hide_name.
Не более 255 символов.
Доступность продукта для добавления в корзину
Если параметр равен false, то покупатель не сможет добавить продукт в корзину.
Варианты значения:
Если параметр равен false, то покупатель не сможет добавить продукт в корзину.
Варианты значения:
- true - продукт доступен для добавления в корзину
- false - продукт снят с публикации и не доступен для добавления в корзину
URL изображения продукта (картинка, логотип продукта)
Отображается покупателю в корзине (пример).
В случае, если изображение не было загружено, никаких уведомлений об ошибке не отправляется.
Отображается покупателю в корзине (пример).
- Валидный URL, который указывает на файл изображения продукта на вашей стороне
- Не более 255 символов
- Вес файла по ссылке: 1B - 512KB
- Допустимые форматы изображения: *.gif, *.jpg, *,jpeg, *.png
- mimeTypes: 'image/gif', 'image/jpg', 'image/jpeg', 'image/pjpeg', 'image/png', 'image/x-png'
В случае, если изображение не было загружено, никаких уведомлений об ошибке не отправляется.
Описание продукта
Отображается покупателю в корзине (пример) в отдельном всплывающем окне.
Можно использовать html-теги.
Отображается покупателю в корзине (пример) в отдельном всплывающем окне.
Можно использовать html-теги.
Комментарий для службы поддержки
Предназначен для внутреннего использования и не будет отображен покупателю.
Предназначен для внутреннего использования и не будет отображен покупателю.
URL страницы с инструкцией по установке продукта
Ссылка может быть выведена в письме с лицензионной информацией для покупателя. Инструкция должна быть размещена на внешнем адресе (например, на вашем сайте) и доступна покупателю по ссылке.
Ссылка может быть выведена в письме с лицензионной информацией для покупателя. Инструкция должна быть размещена на внешнем адресе (например, на вашем сайте) и доступна покупателю по ссылке.
- Валидный URL или пустое значение (url_to_instruction:"").
- Не более 255 символов
- По умолчанию: не заполнено
- Если передано пустое значение (url_to_instruction:""), то ранее заполненный URL будет удален
URL ссылки на скачивание продукта
Ссылка может быть выведена в письме с лицензионной информацией для покупателя. Дистрибутив продукта должен быть размещен на внешнем адресе (например, на вашем сайте) и доступен покупателю по ссылке.
Ссылка может быть выведена в письме с лицензионной информацией для покупателя. Дистрибутив продукта должен быть размещен на внешнем адресе (например, на вашем сайте) и доступен покупателю по ссылке.
- Валидный URL или пустое значение (url_to_download:"")
- Не более 255 символов
- Если передано пустое значение (url_to_download:""), то ранее заполненный URL будет удален
Бизнес сегмент продажи продукта
Варианты значения:
Например, если хотя бы у одного продукта в корзине b2b сегмент, то покупателю по умолчанию будет отображена форма заполнения данных для юридических лиц.
Параметр не накладывает ограничения на продажу продукта.
Варианты значения:
- b2c - продукт предназначен для физических лиц
- b2b - продукт предназначен для юридичесих лиц
- mobile - мобильное приложение
Например, если хотя бы у одного продукта в корзине b2b сегмент, то покупателю по умолчанию будет отображена форма заполнения данных для юридических лиц.
Параметр не накладывает ограничения на продажу продукта.
Доступность продукта для сегмента (типа) покупателей
Покупатель может выбрать при оформлении заказа только тот тип (физическое или юридическое лицо), для которого доступен продукт.
Варианты значения:
Покупатель может выбрать при оформлении заказа только тот тип (физическое или юридическое лицо), для которого доступен продукт.
Варианты значения:
- all - продукт доступен всем типа покупателей
- physical - продукт доступен физическим лицам
- juridical - продукт доступен юридическим лицам
Тип продукта (Initial or Renewal)
Используется в отчетах продажи, доступных через Merchant Portal, а также передается в переменные для электронной торговли.
Варианты значения:
Используется в отчетах продажи, доступных через Merchant Portal, а также передается в переменные для электронной торговли.
Варианты значения:
- new - начальный продукт (initial)
- renew - продление (renewal)
Срок действия продукта
* - Обязательный параметр, если это продукт с продлением, то есть хотя бы один из параметров renew_settings.renew_ar, renew_settings.renew_pmr, renew_settings.renew_email равен true. В этом случае:
Варианты значения параметра:
* - Обязательный параметр, если это продукт с продлением, то есть хотя бы один из параметров renew_settings.renew_ar, renew_settings.renew_pmr, renew_settings.renew_email равен true. В этом случае:
- Срок действия должен быть > 0
- Минимальный срок действия зависит от типа продления
Варианты значения параметра:
- 0 - срок действия неограничен
- P[число][ед.измерения] - ограниченный срок действия, где:
- [ед.измерения] - единицы измерения срока действия: Y - год, M - месяц, D - день
- [число] - число переданных единиц
Количество устройств
Информационное свойство, которое не влияет на ограничение количества продукта для покупки. Не отображается покупателю в корзине. Может быть отображено в письмах по заказу (в описании свойств продукта в заказе). По умолчанию не отображается, если вы хотите показывать количество устройств в письмах, то обратитесь в службу поддержки для настройки.
Варианты значения:
Информационное свойство, которое не влияет на ограничение количества продукта для покупки. Не отображается покупателю в корзине. Может быть отображено в письмах по заказу (в описании свойств продукта в заказе). По умолчанию не отображается, если вы хотите показывать количество устройств в письмах, то обратитесь в службу поддержки для настройки.
Варианты значения:
- null - в письме строка с количеством устройств не будет отображаться для продукта
- 0 - в письме для продукта будет отображаться текст, обозначающий отсутствие ограничения на количество устройств (значение текста может быть настроено)
- Любое другое целое число - в письме для продукта будет отображаться, как доступное количество устройств, на которое рассчитан продукт; должно быть меньше 999999999 (если буде передано большее число, то вернется ошибка 1010)
Настройки продления продукта
- Узнайте подробнее о продаже продлений
- Посмотрите примеры заполнения для разных вариантов настройки продления
Идентификаторы продуктов для продления
* - Обязательный параметр, если передано true хотя бы в одном из параметров: Посмотрите примеры заполнения для разных вариантов настройки продления.
* - Обязательный параметр, если передано true хотя бы в одном из параметров: Посмотрите примеры заполнения для разных вариантов настройки продления.
Настройки подписки с автоматическим продлением (AR, AR Trial)
Внимание! Если вы передаете этот параметр при обновлении продукта, то значения всех вложенных параметров будут обновлены. В том числе, если какой-либо вложенный параметр не будет передан, то ему будет присвоено значение по умолчанию. Подробнее о запросе на обновление продукта.
Внимание! Если вы передаете этот параметр при обновлении продукта, то значения всех вложенных параметров будут обновлены. В том числе, если какой-либо вложенный параметр не будет передан, то ему будет присвоено значение по умолчанию. Подробнее о запросе на обновление продукта.
Включение для продукта подписки с автоматическим продлением (AR, AR Trial)
Варианты значения:
Варианты значения:
- true - включено, продукт может быть инициатором подписки.
В этом случае в запросе должны быть также обязательно переданы параметры: Посмотрите примеры заполнения для разных вариантов настройки продления. - false - выключено, продукт может продаваться без подписки или использоваться для продления подписки
Обязательность автоматического продления
* - Обязательный параметр, если продукт должен быть инициатором подписки с бесплатным пробным периодом (AR Trial). В этом случае значение параметра должно быть равно true. В иных случаях параметр должен быть равен false.
Посмотрите примеры заполнения для разных вариантов настройки продления.
Варианты значения:
* - Обязательный параметр, если продукт должен быть инициатором подписки с бесплатным пробным периодом (AR Trial). В этом случае значение параметра должно быть равно true. В иных случаях параметр должен быть равен false.
Посмотрите примеры заполнения для разных вариантов настройки продления.
Варианты значения:
- true - подписка является обязательной. В этом случае, при оформлении заказа у покупателя не запрашивается согласие на подписку с автоматическим продлением (AR). Подписка создается автоматически при покупке.
- false - подписка является необязательной. В этом случае при оформлении заказа покупатель может включить / выключить согласие на создание подписки. Подписка будет создана при покупке только если покупатель согласился.
Включение для продукта подписки с продлением вручную (PMR)
Варианты значения:
Варианты значения:
- true - включено, продукт может быть инициатором подписки.
В этом случае в запросе должны быть также обязательно переданы параметры: Посмотрите примеры заполнения для разных вариантов настройки продления. - false - выключено, продукт может продаваться без подписки или использоваться для продления подписки
Включение для продукта письма с предложением купить продление
Варианты значения:
Варианты значения:
- true - включено
В этом случае в запросе должны быть также обязательно переданы параметры: Посмотрите примеры заполнения для разных вариантов настройки продления. - false - выключено
Данные для продукта на определенных языках
Внимание! Если вы передаете этот параметр при обновлении продукта, то значения всех вложенных параметров будут обновлены. В том числе, если какой-либо вложенный параметр не будет передан, то ему будет присвоено значение по умолчанию. Подробнее о запросе на обновление продукта.
Внимание! Если вы передаете этот параметр при обновлении продукта, то значения всех вложенных параметров будут обновлены. В том числе, если какой-либо вложенный параметр не будет передан, то ему будет присвоено значение по умолчанию. Подробнее о запросе на обновление продукта.
Код языка, на котором переданы значения внутри объекта.
- Список доступных языков определяется при подключении
- Формат: четырехбуквенный код вида xx_XX. Варианты значений см. в справочнике
Название продукта на соответствующем языке
- Не более 255 символов
- Если не передано, то будет отображаться так, как задано в параметре family_name
Пояснение к названию продукта на соответствующем языке
- Не более 255 символов
- Если не передано, то будет отображаться так, как задано в параметре name
Описание продукта на соответствующем языке
- Можно использовать html-теги
- Если не передано, то будет отображаться так, как задано в параметре description
Верхний комментарий к продукту на соответствующем языке
Комментарии выводятся после пояснения к названию продукта. Узнайте подробнее об отображении комментариев к продукту
Комментарии выводятся после пояснения к названию продукта. Узнайте подробнее об отображении комментариев к продукту
- * - Параметр должен быть передан для каждого языка, доступного в корзине, если он передан хотя бы для одного из них
- Если нужно скрыть комментарий на каком-либо языке, то передайте его с пустым значением для этого языка
- Можно использовать html-теги
Средний комментарий к продукту на соответствующем языке
Комментарии выводятся после пояснения к названию продукта. Узнайте подробнее об отображении комментариев к продукту
Комментарии выводятся после пояснения к названию продукта. Узнайте подробнее об отображении комментариев к продукту
- * - Параметр должен быть передан для каждого языка, доступного в корзине, если он передан хотя бы для одного из них
- Если нужно скрыть комментарий на каком-либо языке, то передайте его с пустым значением для этого языка
- Можно использовать html-теги
Комментарий к продукту для автопродления на соответствующем языке
Комментарии выводятся после пояснения к названию продукта. Узнайте подробнее об отображении комментариев к продукту
Комментарии выводятся после пояснения к названию продукта. Узнайте подробнее об отображении комментариев к продукту
- * - Параметр должен быть передан для каждого языка, доступного в корзине, если он передан хотя бы для одного из них
- Если нужно скрыть комментарий на каком-либо языке, то передайте его с пустым значением для этого языка
- Можно использовать html-теги
Комментарий к продукту для продления вручную на соответствующем языке
Комментарии выводятся после пояснения к названию продукта. Узнайте подробнее об отображении комментариев к продукту
Комментарии выводятся после пояснения к названию продукта. Узнайте подробнее об отображении комментариев к продукту
- * - Параметр должен быть передан для каждого языка, доступного в корзине, если он передан хотя бы для одного из них
- Если нужно скрыть комментарий на каком-либо языке, то передайте его с пустым значением для этого языка
- Можно использовать html-теги
Нижний комментарий к продукту на соответствующем языке
Комментарии выводятся после пояснения к названию продукта. Узнайте подробнее об отображении комментариев к продукту
Комментарии выводятся после пояснения к названию продукта. Узнайте подробнее об отображении комментариев к продукту
- * - Параметр должен быть передан для каждого языка, доступного в корзине, если он передан хотя бы для одного из них
- Если нужно скрыть комментарий на каком-либо языке, то передайте его с пустым значением для этого языка
- Можно использовать html-теги
Комментарий к продукту в нижней части корзины на соответствующем языке.
Узнайте подробнее об отображении комментариев к продукту
Узнайте подробнее об отображении комментариев к продукту
- * - Параметр должен быть передан для каждого языка, доступного в корзине, если он передан хотя бы для одного из них
- Если нужно скрыть комментарий на каком-либо языке, то передайте его с пустым значением для этого языка
- Можно использовать html-теги
Настройки отображения продукта
Внимание! Если вы передаете этот параметр при обновлении продукта, то значения всех вложенных параметров будут обновлены. В том числе, если какой-либо вложенный параметр не будет передан, то ему будет присвоено значение по умолчанию. Подробнее о запросе на обновление продукта.
Внимание! Если вы передаете этот параметр при обновлении продукта, то значения всех вложенных параметров будут обновлены. В том числе, если какой-либо вложенный параметр не будет передан, то ему будет присвоено значение по умолчанию. Подробнее о запросе на обновление продукта.
Скрытие подзаголовка (name) для продукта в корзине
Варианты значения:
Варианты значения:
- true - подзаголовок скрыт
- false - подзаголовок отображается
Скрытие количества продукта в корзине
Если количество скрыто, то:
Варианты значения:
Если количество скрыто, то:
- В корзину будет добавлено минимально возможное для покупки количество продукта, которое передается в variants.from
- Покупатель не будет видеть, сколько единиц продукта добавлено в корзину, и не сможет изменить значение
Варианты значения:
- true - скрыть
- false - показать
Цены продукта
Может содержать несколько объектов, в которых определена цена (variants.price) в зависимости от количества единиц продукта в корзине (variants.from, variants.to).
Внимание! Если вы передаете этот параметр при обновлении продукта, то значения всех вложенных параметров будут обновлены. В том числе, если какой-либо вложенный параметр не будет передан, то ему будет присвоено значение по умолчанию. Подробнее о запросе на обновление продукта.
Может содержать несколько объектов, в которых определена цена (variants.price) в зависимости от количества единиц продукта в корзине (variants.from, variants.to).
Внимание! Если вы передаете этот параметр при обновлении продукта, то значения всех вложенных параметров будут обновлены. В том числе, если какой-либо вложенный параметр не будет передан, то ему будет присвоено значение по умолчанию. Подробнее о запросе на обновление продукта.
Ваш артикул продукта при покупке подписки
Это значение будет сохранено в заказе вместо variants.sku, если при покупке продукта будет создана подписка с автоматическим продлением (AR, AR Trial).
Не более 255 символов.
Это значение будет сохранено в заказе вместо variants.sku, если при покупке продукта будет создана подписка с автоматическим продлением (AR, AR Trial).
Не более 255 символов.
Минимальное количество продукта, доступное к покупке за указанную в variants.price цену
- Может быть равно целому числу или нулю (0)
- Если не передано или равно нулю, то цена будет действовать при покупке от одной единицы продукта
- Должно быть больше нуля, если variants.to передано и больше нуля
Максимальное количество продукта, доступное к покупке за указанную в variants.price цену.
- Может быть равно целому числу или нулю (0)
- Если не передано или равно нулю, то цена будет действовать при покупке любого количества продукта (от одного до бесконечности)
- Если variants.from и variants.to переданы, то должно выполняться условие to ≥ from
- Интервалы from - to для одного продукта не должны пересекаться
- У продукта не должно быть интервалов количества, для которых не определена цена
Цены на продукт для переданных значений количества (variants.from, variants.to)
* - Обязательный параметр, если передан массив variants.
Поддерживается два варианта настройки цен:
Внимание! В ценах на один продукт может использоваться только один из вариантов настройки цены. Т.е. все цены продукта должны быть заданы или через одну цену в базовой валюте или через индивидуальные цены.
* - Обязательный параметр, если передан массив variants.
Поддерживается два варианта настройки цен:
- Одна цена в базовой валюте (для ценовых моделей One price, Volume pricing).
В этом случае передайте один вложенный объект с названием common. - Индивидуальные цены для каждой валюты продажи (для ценовых моделей One price for each currency, Volume pricing and options).
В этом случае передайте отдельные вложенные объекты, названия которых соответствуют валютам продажи. Если для какой-либо валюты продажи не будут переданы данные, то все цены в ней будут удалены и продукт станет не доступен для продажи в этой валюте.
Внимание! В ценах на один продукт может использоваться только один из вариантов настройки цены. Т.е. все цены продукта должны быть заданы или через одну цену в базовой валюте или через индивидуальные цены.
Цена на продукт
Объект, который содержит данные индивидуальной цены (для продажи в определенной валюте) или данные одной цены в базовой валюте (на основании которой будут рассчитаны цены для доступных валют продаж). Название объекта определяет, какая это цена – индивидуальная цена для валюты продажи или цена в базовой валюте.
Узнайте подробнее о том, как настроить цены по разным ценовым моделям, и посмотрите примеры настройки.
Объект, который содержит данные индивидуальной цены (для продажи в определенной валюте) или данные одной цены в базовой валюте (на основании которой будут рассчитаны цены для доступных валют продаж). Название объекта определяет, какая это цена – индивидуальная цена для валюты продажи или цена в базовой валюте.
Узнайте подробнее о том, как настроить цены по разным ценовым моделям, и посмотрите примеры настройки.
- * - Обязательный параметр, если передан объект variants.price
- Чтобы задать только одну цену в базовой валюте, передайте название объекта: common.
- Чтобы задать индивидуальные цены для каждой валюты продажи:
- Передайте в качестве названия объекта код валюты продажи в формате ISO 4217 alpha-3
- Не более 3 символов
- Варианты значений см. в справочнике
- В одном продукте вы можете использовать только валюты, которые доступны в соответствии с вашим договором (одним из договоров)
- Если у вас несколько договоров для продаж в разных валютах, то вы должны создавать отдельные продукты для продаж по этим договорам
Код валюты
Это валюта, в которой передана цена в параметре variants.price.price). Вы можете задать цену на продукт в валюте, которая отличается от валюты продажи. В этом случае, при покупке продукта цена будет переконвертирована.
Это валюта, в которой передана цена в параметре variants.price.price). Вы можете задать цену на продукт в валюте, которая отличается от валюты продажи. В этом случае, при покупке продукта цена будет переконвертирована.
- * - Обязательный параметр, если передан объект variants.price
- Допустимые варианты валюты:
- При использовании одной цены в базовой валюте: RUB, USD, EUR
- При использовании индивидуальных цен для каждой валюты продажи: RUB, USD, EUR или [валюта продажи]. Вы можете использовать только валюты, которые доступны в соответствии с вашим договором
- Формат: ISO 4217 alpha-3
- Не более 3 символов
- Варианты значений см. в справочнике
Цена на продукт в валюте variants.price.currency
- * - Обязательный параметр, если передан объект variants.price
- Формат: число с 2 десятичными знаками, разделитель - точка, передается как строка
- Цена может быть равна нулю (0.00) только для продуктов с бесплатным пробным периодом или подарков
- В зависимости от условий вашего договора включите сумму VAT в цену или передайте цену без учета VAT
Настройки предложения дополнительных продуктов в корзине (cross-sell)
Узнайте подробнее о том, как работают дополнительные продукты.
Передавайте этот параметр для дополнительного продукта, который должен быть предложен, если в корзине находится основной продукт. Для основного продукта передавать этот параметр не нужно.
Внимание! Если вы передаете этот параметр при обновлении продукта, то значения всех вложенных параметров будут обновлены. В том числе, если какой-либо вложенный параметр не будет передан, то ему будет присвоено значение по умолчанию. Подробнее о запросе на обновление продукта.
Узнайте подробнее о том, как работают дополнительные продукты.
Передавайте этот параметр для дополнительного продукта, который должен быть предложен, если в корзине находится основной продукт. Для основного продукта передавать этот параметр не нужно.
Внимание! Если вы передаете этот параметр при обновлении продукта, то значения всех вложенных параметров будут обновлены. В том числе, если какой-либо вложенный параметр не будет передан, то ему будет присвоено значение по умолчанию. Подробнее о запросе на обновление продукта.
Тип дополнительного продукта
* - Обязательный параметр, если передан параметр cross_sell.
Варианты значения:
* - Обязательный параметр, если передан параметр cross_sell.
Варианты значения:
- candy_rack - рекомендуемый дополнительный продукт
- add_to_basket - обязательный дополнительный продукт
Статус cross-sell предложения
Варианты значения:
Варианты значения:
- true - предложение доступно покупателю
- false - предложение выключено
Дата начала действия cross-sell предложения
- * - Обязательный параметр, если передан параметр cross_sell
- Формат даты: YYYY-MM-DD HH:MI:SS
- Часовой пояс: UTC+3
- date_from ≤ date_to
Дата окончания действия cross-sell предложения
- * - Обязательный параметр, если передан параметр cross_sell
- Формат даты: YYYY-MM-DD HH:MI:SS
- Часовой пояс: UTC+3
- date_from ≤ date_to
(Только для обязательных дополнительных продуктов)
Доступность удаления дополнительного продукта в корзине отдельно от основного.
Варианты значения:
Доступность удаления дополнительного продукта в корзине отдельно от основного.
Варианты значения:
- true - можно удалить
- false - нельзя удалить
(Только для обязательных дополнительных продуктов)
Доступность изменения количества дополнительного продукта в корзине отдельно от основного.
Варианты значения:
Доступность изменения количества дополнительного продукта в корзине отдельно от основного.
Варианты значения:
- true - можно изменить количество
- false - нельзя изменить количество
Идентификаторы основных продуктов
При добавлении в корзину хотя бы одного из этих продуктов, покупателю будет предложен дополнительный продукт.
* - Обязательный параметр, если передан параметр cross_sell.
При добавлении в корзину хотя бы одного из этих продуктов, покупателю будет предложен дополнительный продукт.
* - Обязательный параметр, если передан параметр cross_sell.
Настройки предложения дополнительного продукта на странице оплаченного заказа (TYPO)
Узнайте, как работает это предложение.
Передавайте этот параметр для дополнительного продукта, который должен быть предложен, если в оплаченном заказе находится основной продукт. Для основного продукта передавать этот параметр не нужно.
Если вы хотите, чтобы на продукт в TYPO действовала особенная цена со скидкой, то:
Узнайте, как работает это предложение.
Передавайте этот параметр для дополнительного продукта, который должен быть предложен, если в оплаченном заказе находится основной продукт. Для основного продукта передавать этот параметр не нужно.
Если вы хотите, чтобы на продукт в TYPO действовала особенная цена со скидкой, то:
- Создайте отдельный продукт и промоакцию со скидкой для него
- Настройте TYPO для этого продукта
- Не размещайте ссылку на покупку этого продукта на своей стороне, чтобы покупатель не мог добавить продукт в корзину обычным образом и видел его только в специальном предложении TYPO
Статус TYPO предложения
Варианты значения:
Варианты значения:
- true - предложение доступно покупателю
- false - предложение выключено
Дата начала действия TYPO предложения
- * - Обязательный параметр, если передан параметр typo
- Формат даты: YYYY-MM-DD HH:MI:SS
- Часовой пояс: UTC+3
- date_from ≤ date_to
Дата окончания действия TYPO предложения
- * - Обязательный параметр, если передан параметр typo
- Формат даты: YYYY-MM-DD HH:MI:SS
- Часовой пояс: UTC+3
- date_from ≤ date_to
Идентификаторы основных продуктов
При наличии в оплаченном заказе хотя бы одного из этих продуктов, покупателю будет показано TYPO на странице оплаченного заказа.
При наличии в оплаченном заказе хотя бы одного из этих продуктов, покупателю будет показано TYPO на странице оплаченного заказа.
- * - Обязательный параметр, если передан параметр typo
- Основной продукт не может быть продуктом с бесплатным пробным периодом
Данные для TYPO на определенных языках
- Если параметр не передан, то:
- Будет использован стандартный текст, например, "В качестве благодарности предлагаем вам скидку %DISCOUNT% % на еще один продукт"
- Внимание! Если для продукта не настроена скидка через промоакцию, то вместо %DISCOUNT% в тексте отобразится "0".
- Если параметр передан, то в нем должны быть переданы значения для каждого языка, подключенного к корзине
- Если вы хотите скрыть данные для какого-либо языка, то передайте typo.localization_values.comment_for_typo с пустым значением для этого языка
Код языка, на котором переданы значения внутри объекта.
- Список доступных языков определяется при подключении
- Формат: четырехбуквенный код вида xx_XX. Варианты значений см. в справочнике
Текст для описания предложения на соответствующем языке.
- Можно использовать html-теги
- Чтобы подставить в текст значение скидки, настроенной для продукта, можно использовать тег подстановки %DISCOUNT%.
Внимание! Если для продукта не настроена скидка, то вместо %DISCOUNT% в тексте отобразится "0%".
Идентификатор способа генерации лицензии
Если параметр передан, то к продукту будет подключен соответствующий способ генерации лицензии. В ином случае будет подключен способ по умолчанию (если настроено), или для продукта будет использоваться самостоятельная отправка продукта.
Чтобы узнать идентификатор способа генерации лицензии обратитесь в службу поддержки.
Узнайте подробнее о том, как работает электронная доставка продуктов.
Обратите внимание, обновление привязки к способу генерации лицензии происходит в случае, если в запросе передан параметр variants.
Если параметр передан, то к продукту будет подключен соответствующий способ генерации лицензии. В ином случае будет подключен способ по умолчанию (если настроено), или для продукта будет использоваться самостоятельная отправка продукта.
Чтобы узнать идентификатор способа генерации лицензии обратитесь в службу поддержки.
Узнайте подробнее о том, как работает электронная доставка продуктов.
Обратите внимание, обновление привязки к способу генерации лицензии происходит в случае, если в запросе передан параметр variants.
Настройки для автоматической электронной доставки продукта покупателю
Используется, если к продукту подключен один из наших способов автоотправки продукта. Узнайте подробнее о том, как это работает.
Используется, если к продукту подключен один из наших способов автоотправки продукта. Узнайте подробнее о том, как это работает.
- Если параметр не передан, то будет использовано значение по умолчанию. При использовании автоотправки лицензии через веб-сервис значение по умолчанию можно настроить через Merchant Portal. В остальные случаях настройка выполняется через техподдержку
- Если параметр передан, то его значение будет использоваться только для соответствующего продукта вместо значения по умолчанию. При этом в нем должны быть переданы значения для каждого языка, подключенного к корзине (нельзя заполнить данные только для части языков)
- Внимание! Если вы передаете этот параметр при обновлении продукта, то значения всех вложенных параметров будут обновлены. Подробнее о запросе на обновление продукта
- Если для продукта нужно полностью удалить ранее переданное значение параметра (чтобы вернуться к использованию значения по умолчанию), то обратитесь в службу поддержки
Код языка, на котором переданы значения внутри объекта.
- Список доступных языков определяется при подключении
- Формат: четырехбуквенный код вида xx_XX. Варианты значений см. в справочнике
Текст для подстановки в шаблон письма с лицензионной информацией для покупателя. Используется вместо значения по умолчанию.
- Можно использовать html-теги и теги подстановки
- Обратите внимание, если ваши продукты используют автоотправку через веб-сервис или пул, то текст должен обязательно содержать тег подстановки {KEY}
Наличие продукта в реестре российского ПО (https://reestr.digital.gov.ru/reestr/)
Влияет на начисление НДС, если продукт продается в российских рублях.
Влияет на начисление НДС, если продукт продается в российских рублях.
Продукт включен в реестр российского ПО
* - Обязательный параметр, если параметр software_registry передан.
Варианты значений:
Обратите внимание, если продукт находился в реестре и у него были продажи, то его нельзя оттуда "вывести" с определенной даты просто передав статус false. Это приведет к неправильному учету вашей доли от продажи за тот период, когда продукт еще был в реестре.
Если нужно отключить наличие в реестре с определенной даты, то:
- оставьте текущий продукт с включенным статусом наличия в реестре,
- и создайте новый продукт, у которого software_registry.status = false, для дальнейших продаж.
* - Обязательный параметр, если параметр software_registry передан.
Варианты значений:
- true - продукт включен в реестр. Передайте это значение, если:
- Продукт продается в российских рублях
- И вы являетесь резидентом РФ и не являетесь плательщиком НДС (используете УСН), или являетесь плательщиком НДС (используете ОСН)
- И программа внесена в реестр российского ПО (https://reestr.digital.gov.ru/reestr/)
- false - передайте это значение во всех остальных случаях. При этом продукт будет облагаться НДС 20%
Обратите внимание, если продукт находился в реестре и у него были продажи, то его нельзя оттуда "вывести" с определенной даты просто передав статус false. Это приведет к неправильному учету вашей доли от продажи за тот период, когда продукт еще был в реестре.
Если нужно отключить наличие в реестре с определенной даты, то:
- оставьте текущий продукт с включенным статусом наличия в реестре,
- и создайте новый продукт, у которого software_registry.status = false, для дальнейших продаж.
Дата внесения продукта в реестр российского ПО
* - Обязательный параметр, если параметр software_registry.status передан и равен true.
* - Обязательный параметр, если параметр software_registry.status передан и равен true.
- Формат даты: YYYY-MM-DD
- Часовой пояс: UTC+3
- Не может быть передан пустым (""). Если продукт не включен в реестр (software_registry.status = false), то не передавайте этот параметр
Ссылка на программу в реестре российского ПО
* - Обязательный параметр, если параметр software_registry.status передан и равен true.
* - Обязательный параметр, если параметр software_registry.status передан и равен true.
- Валидный URL, который указывает на страницу программы на сайте https://reestr.digital.gov.ru/reestr/)
- Не может быть передан пустым (""). Если продукт не включен в реестр (software_registry.status = false), то не передавайте этот параметр
Регистрационный номер программы в реестре российского ПО
* - Обязательный параметр, если параметр software_registry.status передан и равен true.
Не может быть передан пустым (null). Если продукт не включен в реестр (software_registry.status = false), то не передавайте этот параметр
* - Обязательный параметр, если параметр software_registry.status передан и равен true.
Не может быть передан пустым (null). Если продукт не включен в реестр (software_registry.status = false), то не передавайте этот параметр
Пример запроса
{
"family_name": "Демо-продукт",
"name": "Лицензия на 1 год",
"is_publish": true,
"image_url": "https://my-shop.com/images/product-1234.png",
"description": "<p><strong>Тестовый продукт</strong></p>",
"comment_for_manager": "Комментарий для менеджера",
"url_to_instructions": "https://www.google.com",
"url_to_download": "https://www.google.com",
"business_segment": "b2c",
"available_for_sale": "all",
"is_service": true,
"license_type": "new",
"licence_term": "P1Y",
"device_quantity": 1,
"fulfillment_id":1234,
"renew_settings": {
"product_id_for_renew": [
4645130,
4645131,
4645131
],
"renew_ar": {
"enable": true,
"required": false
},
"renew_pmr": true,
"renew_email": false
},
"localization_values": {
"en_EN": {
"family_name": "Test product",
"name": "1 PC/1 year",
"description": "<p><strong>Test product</strong> for test purchase</p>",
"comment_for_cart": "This is a test purchase.",
"comment_for_product_top": "The license is valid for 1 year.",
"comment_for_product_middle": "New version of the test product.",
"comment_for_product_for_AR": "The license is renewed automatically.",
"comment_for_product_for_MR": "You will need to manually renew your license after 1 year.",
"comment_for_product_bottom": "This license is not for sale or activation outside of the country."
}
},
"display_settings": {
"hide_name": true,
"hide_item_quantity": true
},
"variants": [
{
"vendor_code": "1",
"sku": "111",
"from": 1,
"to": 5,
"price": {
"RUB": {
"currency": "USD",
"price": "99.99"
}
}
},
{
"vendor_code": "1",
"sku": "111",
"from": 6,
"price": {
"RUB": {
"currency": "USD",
"price": "80.99"
}
}
}
],
"cross_sell": {
"type": "add_to_basket",
"status": true,
"date_from": "2020-10-15 14:18:00",
"date_to": "2020-10-25 14:18:00",
"removal_available": true,
"quantity_change_available": false,
"product_id": [
4645130,
4645131
]
},
"typo": {
"status": true,
"date_from": "2020-10-15 14:18:40",
"date_to": "2020-10-25 14:18:40",
"localization_values": {
"ru_RU": {
"comment_for_typo": "Специальное предложение"
},
"en_EN": {
"comment_for_typo": "Special offer"
}
},
"product_id": [
4645130,
4645131
]
},
"license_data": {
"ru_RU": {
"customer_notification": "Ключ активации: {KEY}"
},
"en_EN": {
"customer_notification": "Key: {KEY}"
}
},
"software_registry": {
"status": true,
"date": "2020-10-15",
"url": "https://reestr.digital.gov.ru/reestr/111",
"registration_number": 111
}
}
Ответ на запрос
В ответ на запрос вы получите код ответа сервера, соответствующий результату обработки.
В зависимости от кода в теле ответа могут присутствовать дополнительные параметры.
Положительный ответ
При успешной обработке запроса вы получите код ответа сервера HTTP/1.1 200 OK. В теле ответа будет передан идентификатор продукта.
Положительный ответ
{
"id": 111122233
}
Ответ об ошибке
В случае ошибки при обработке запроса вы получите код ответа сервера, соответствующий результату обработки.
В зависимости от кода в теле ответа могут присутствовать дополнительные параметры.
Справочник HTTP-кодов ответа сервера при ошибке
Код ответа сервера | Описание |
HTTP/1.1 400 Bad Request | Запрос не валиден (ошибка в параметрах; не переданы необходимые данные и т.п.). В теле ответа будет передан дополнительный код ошибки (один или несколько). |
HTTP/1.1 401 Unauthorized | Неуспешная аутентификация. В теле ответа будет передан дополнительный код ошибки (один или несколько). |
HTTP/1.1 404 Not found | Неверный URL запроса. Проверьте адрес запроса. |
HTTP/1.1 500 Request Error | Ошибка на стороне сервера. Повторите запрос позднее или обратитесь в службу поддержки. |
Справочник дополнительных кодов ошибок для HTTP 400
Error | Message | Описание |
Если хотя бы одна ошибка из списка ниже найдена, то она возвращается в ответе на запрос, остальные ошибки не проверяются. | ||
110 | JSON is not valid. | Структура полей запроса не валидна. Проверьте поля в теле запроса на соответствие формату JSON. |
111 | Invalid data format (Content-type). | Неправильный заголовок запроса. Content-type должен быть равен application/json. |
1020 | Could not identify product settings for this currency. Please contact technical support. | Не получилось определить настройки вашего аккаунта. Проверьте, что в запросе правильно передана валюта в поле variants.price.[валюта]. В случае, если проблема сохраняется, обратитесь в службу поддержки. |
1040 | According to the Agreement, this product cannot be sold in this currency. For more information, please contact the Content Department. | Невозможно создать продукт в переданной валюте (variants.price.[валюта]). |
Если хотя бы одна ошибка из списка ниже найдена, то проверка запроса не прерывается. В ответе может быть возвращено несколько ошибок. |
||
3010 | Invalid field value: [наименование поля] | Запрос не валиден, например, не заполнено обязательное поле, неверно указано название поля, значение поля не соответствует указанному типу данных, неверный формат значения. В том числе ошибка будет возвращена, если в поле передано null, и этот вариант значения не указан как допустимый в описании поля. |
1050 | Locale not found. | Передан неправильный код языка (localization_values.[local-name], typo.localization_values.[local-name], license_data.[local-name]). |
1060 | Auto-renewal cannot be enabled (renew_ar). No data: [список полей, которые не были переданы]. | В запросе передано включение подписки AR (renew_settings.renew_ar.enable = true), но отсутствуют обязательные данные. Необходимые данные будут перечислены в тексте ошибки. |
1070 | "Mandatory auto-renewal" condition (renew_ar.required) can only be enabled if auto-renewal is enabled (renew_ar.enable). | В запросе передано включение обязательности подписки AR (renew_settings.renew_ar.required = true), но при этом доступность подписки AR выключена (renew_settings.renew_ar.enable = false). |
1080 | Pre-filled manual renewal cannot be enabled (renew_pmr). No data: [список полей, которые не были переданы]. | В запросе передано включение PMR подписки (renew_settings.renew_pmr = true), но отсутствуют обязательные данные. Необходимые данные будут перечислены в тексте ошибки. |
1090 | Function to send an email containing a license renewal buy link cannot be enabled (renew_email). No data: [список полей, которые не были переданы]. | В запросе передано включение отправки письма с предложением купить продление (renew_settings.renew_email = true), но отсутствуют обязательные данные. Необходимые данные будут перечислены в тексте ошибки. |
1100 | Invalid renewal products for product_id_for_renew. No products found: [список id продуктов, которые не прошли проверку]. | В переданном списке продуктов продления (renew_settings.product_id_for_renew) хотя бы один продукт не прошел проверку. В тексте ошибки будут указаны продукты, которые не прошли проверку. |
1110 | Invalid configuration of renewal products for product_id_for_renew. The products must be listed in the same order as the renewal process will be performed. The last product must renew itself. | Нарушены правила составления цепочки продуктов продления. |
1120 | Invalid price list currency (currency). The price in the price list can be set only in one of these currencies: RUB, USD, EUR or sales currency. | Неправильная валюта, в которой указана индивидуальная для валюты продажи цена (variants.price.[валюта продажи].currency:[валюта прайса]). В тексте ошибки будут перечислены допустимые валюты. |
1125 | Invalid price list currency (currency). The common price in the price list can be set only in one of the following currencies: RUB, USD, EUR. | Неправильная валюта, в которой указана цена в валюте прайс-листа (variants.price.common.currency:[валюта прайса]). В тексте ошибки будут перечислены допустимые валюты. |
1130 | Invalid price range (variants.from, variants.to). | Ошибка в минимальном (variants.from) и(или) максимальном (variants.to) количестве продукта, для которого задана цена. |
1135 | Invalid price list currency (currency). The "common" attribute and any other sales currency cannot be used at the same time. | Неправильно заданы цены (variants.price). В одном продукте нельзя одновременно использовать отдельные цены для каждой валюты продажи и единые цены. |
1140 | Products for cross_sell.product_id are incorrect. Products not found: [список id продуктов, которые не прошли проверку]. | В списке основных продуктов для дополнительного (cross_sell.product_id) хотя бы один продукт не прошел проверку. |
1150 | Parameters for cross_sell: date_from, date_to are incorrect. | Даты для дополнительных продуктов (cross_sell.date_from, cross_sell.date_to) не прошли проверку. |
1160 | Products for typo.product_id are incorrect. Products not found: [список id продуктов, которые не прошли проверку]. | В списке идентификаторов родительских продуктов для TYPO (typo.product_id) хотя бы один продукт не прошел проверку. |
1170 | Parameters for typo: date_from, date_to are incorrect. | Даты для TYPO (typo.date_from, typo.date_to) не прошли проверку. |
1300 | Fulfillment not found. | Сервис генерации лицензии (fulfillment_id) не найден или не доступен для использования. |
Справочник кодов ошибок для HTTP 401
Справочник этих ошибок одинаковый для всех API, которые используют авторизацию по токену.
Пример ответа об ошибке
{
"errors": [{
"error": 1010,
"message": "Invalid field value: family_name"
}, {
"error": 1050,
"message": "Locale not found."
}
]
}