Project

General

Profile

Сервис для управления каталогом

История изменений

Версия сервиса: 1.4 (28.06.2021)

Основные определения

Продукт - отдельная позиция каталога, на которую можно оформить заказ.

Id продукта - Идентификатор позиции каталога (id ценовой группы, который также используется в ссылке на покупку).

Краткое описание

Сервис предназначен для управления каталогом продуктов для корзин Партнеров и позволяет: При управлении продуктом можно задать:
  • Основные свойства продукта.
  • Настройки продления лицензии (в том числе подписки с автоматическим продлением лицензии). См. подробнее в отдельной статье.
  • Локализация данных продукта для продажи в корзинах с поддержкой разных языков.
  • Настройки отображения продукта в корзине.
  • Комментарии к продукту в корзине.
  • Цены на продукт (в том числе в разных валютах для продажи в корзинах с поддержкой нескольких валют).
  • Настройка предложения дополнительных продуктов на странице корзины. См. подробнее в отдельной статье.
  • Настройка предложения продукта по выгодной цене на странице после оплаты заказа (TYPO). См. подробнее в отдельной статье.
  • Настройки для отправки лицензионной информации для продукта.

Управление продуктом через Сервис имеет отличия от управление через Кабинет разработчика.

Подключение к Сервису

Softline Ecommerce предоставляет данные для подключения:
  • Логин и пароль, для авторизации с помощью токена (если они не были предоставлены ранее при работе с другим сервисом, использующим данный вид авторизации).
Заполнение свойств продуктов должно происходить в соответствии с договором между Партнером и Softline Ecommerce.
Обратитесь к своему аккаунт менеджеру, чтобы получить данные для начала работы:
  • Список валют, в которых доступна продажа продуктов по договору.
  • Список локалей (языков), подключенных к корзине, через которую продается продукт.

Если продажи идут через несколько корзин, то данные настройки должны быть предоставлены для каждой корзины.

Также для подключения необходимо настроить автоотправку лицензионной информации для продуктов.
Подробнее об отправке лицензионной информации по приобретенным продуктам см. далее.
  • На стороне Партнера должен быть настроен отдельный веб-сервис, который будет по запросу выдавать лицензионную информацию для продукта в заказе.
  • На стороне Softline Ecommerce должен быть настроен запрос к веб-сервису. Это можно сделать через Кабинет Разработчика или по запросу в Отдел контента.

Авторизация при работе с сервисом

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

Получение и использование токена »

Запросы на создание и обновление продукта

URL • Создание продукта: https://api.ecommerce.softline.com/v1/product
• Обновление продукта:
[Идентификатор_продукта]
Тип запроса • Создание продукта: POST
• Обновление продукта: PATCH
Формат передачи данных • Создание продукта: JSON
• Обновление продукта: Параметр в URL и данные в JSON формате в теле запроса
Кодировка UTF-8
Авторизация С помощью токена

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

Параметр Обязательность Формат Описание
Создание Обновление
id Не передается Да integer Идентификатор продукта. Передается в URL запроса на обновление.
family_name Да string (255) Название программы (family_name) и ценовой группы продукта (name).
Используются при формировании названия продукта в корзине.
 
Рекомендуется в family_name передавать название семейства продуктов, в name - название определенного продукта из семейства. Без дублирования.
name Да string (255)
is_publish boolean (true, false) Признак опубликованности продукта.
Для продажи доступны только опубликованные продукты, у которых заполнена хотя бы одна цена (price).
 
Варианты значения:
true - опубликован,
false - снят с публикации.
 
По умолчанию true.
image_url string (Valid URL) URL изображения продукта.
Вес файла: 1B - 512KB.
Допустимые форматы изображения: *.gif, *.jpg, *,jpeg, *.png.
mimeTypes: 'image/gif', 'image/jpg', 'image/jpeg', 'image/pjpeg', 'image/png', 'image/x-png'
 
При обработке запроса изображение будет загружено и сохранено на сервер Softline Ecommerce.
Загрузка изображения выполняется отдельно от обработки запроса на добавление/обновление продукта и завершается позже, чем будет отправлен ответ на запрос.
Примерное время завершения загрузки: в течение нескольких секунд после обновления продукта.
В случае, если изображение не было загружено, никаких уведомлений об ошибке не отправляется.
description mediumtext Описание продукта.
Можно использовать html-теги.
comment_for_manager mediumtext Комментарий для Отдела контента.
Предназначен для внутреннего использования и не будет отображен покупателю.
url_to_instructions string(255, Valid URL) URL страницы с инструкцией по установке продукта.
Инструкция должна быть размещена на внешнем адресе (например, на сайте Партнера) и доступна покупателю по ссылке.
Ссылка может быть выведена в письме с лицензионной информацией для покупателя.
url_to_download string(255, Valid URL) URL ссылки на скачивание продукта.
Дистрибутив продукта должен быть размещен на внешнем адресе (например, на сайте Партнера) и доступен покупателю по ссылке.
Ссылка может быть выведена в письме с лицензионной информацией для покупателя.
business_segment string
enum (b2c, b2b, mobile)
Бизнес сегмент продажи продукта.
 
Варианты значения:
b2c - продукт предназначен для физических лиц (b2c),
b2b - продукт предназначен для юридичесих лиц (b2b),
mobile - мобильное приложение.
 
Используется для передачи в системы сбора статистики (например, GTM), а также для некоторых дополнительных
licence_term Да, если передано значение true хотя бы в одном из полей:
renew_ar
renew_pmr
renew_email
string (P [number] [unit]) Срок действия лицензии в формате P[число][ед.измерения] или 0 (бессрочная лицензия).
При этом:
• [ед.измерения] - единицы измерения срока действия лицензии: Y - год, M - месяц, D - день.
• [число] - число переданных единиц.
 

 
Должно быть заполнено для продуктов с обработкой продления лицензии (подпиской), подробнее. При этом лицензия не может быть бессрочной.
renew_settings object Данные для настройки обработки продления лицензии на продукт, подробнее.
 
Внимание! При передаче поля renew_settings происходит замена всех текущих настроек на переданные значения.
Если какое-либо вложенное поле отсутствует, то его ранее заданное значение будут удалено.
product_id_for_renew Да, если передано значение true хотя бы в одном из полей:
renew_ar
renew_pmr
renew_email
array (integer) Массив идентификаторов продуктов, которые используются для продления лицензии.
Должно быть заполнено для продуктов с обработкой продления лицензии (подпиской), подробнее.
renew_ar object Настройки подписки с автоматическим продлением (AR).
enable boolean (true, false) Включение для продукта подписки с автоматическим продлением.
Варианты значения:
true - включено.
false - выключено.
 
По умолчанию false.
 
Если renew_ar.enable = true, то в запросе должны быть обязательно заполнены поля: licence_term, product_id_for_renew и product_id_for_renew != 0
required boolean (true, false) Обязательность автоматического продления.
Варианты значения:
true - заказ оформляется с обязательным созданием подписки с автоматическим продлением лицензии (AR). У покупателя не запрашивается согласие на подписку.
false - при оформлении заказа покупатель может включить / выключить согласие с созданием подписки. Подписка будет создана только если покупатель согласился.
 
По умолчанию false.
 
Если renew_ar.required = true, то renew_ar.enable также должно быть равно true.
renew_pmr boolean (true, false) Включение PMR подписки для продукта.
Варианты значения:
true - включено.
false - выключено.
 
По умолчанию false.
renew_email boolean (true, false) Включение письма с предложением купить продукт для продления.
Варианты значения:
true - включено.
false - выключено.
 
По умолчанию false.
localization_values object Данные для продукта на определенных языках.
Можно использовать только языки, подключенные к корзине. Подключение нового языка выполняется Отделом контента.
 
Внимание! При передаче поля localization_values происходит замена всех текущих языковых настроек на переданные значения.
Если какое-либо вложенное поле отсутствует, то его ранее заданное значение будут удалено.
[локаль] Да,
если передано localization_values
string (5) Код языка интерфейса корзины, на котором переданы значения внутри объекта.
family_name string (255) Название программы на соответствующем языке.
Если не передано, то будет отображаться так, как задано в основной части запроса для продукта в целом.
name text Название ценовой группы на соответствующем языке.
Если не передано, то будет отображаться так, как задано в основной части запроса для продукта в целом.
description text Описание продукта на соответствующем языке. Можно использовать html-теги.
Если не передано, то будет отображаться так, как задано в основной части запроса для продукта в целом.
comment_for_cart Да,
если хотя бы для одного языка заполнено.
text Комментарий к продукту на соответствующем языке. Можно использовать html-теги.
В зависимости от названия поля выводится в соответствующем месте для продукта в корзине или внизу страницы корзины рядом с кнопкой продолжения оформления заказа.
 
Можно настроить комментарий, который будет выводиться только в случае, если включено согласие на подписку с автопродлением (или, который будет выводиться во всех остальных случаях).
 

 
Внимание! Если поле заполнено на одном из языков, то нужно передать его значение для всех остальных языков, подключенных к корзине.
При этом если для какого-либо языка нужно скрыть комментарий, то поле должно быть передано с пустым значением.
comment_for_product_top Да,
если хотя бы для одного языка заполнено.
comment_for_product_middle Да,
если хотя бы для одного языка заполнено.
comment_for_product_for_AR Да,
если хотя бы для одного языка заполнено.
comment_for_product_for_MR Да,
если хотя бы для одного языка заполнено.
comment_for_product_bottom Да,
если хотя бы для одного языка заполнено.
display_settings object Настройки отображения продукта в корзине.
 
Внимание! При передаче поля display_settings происходит замена всех текущих настроек на переданные значения.
Если какое-либо вложенное поле отсутствует, то его ранее заданное значение будут удалено.
hide_name boolean (true, false) Скрытие названия ценовой группы в корзине. Если название ценовой группы скрыто, то для продукта в корзине будет отображаться только название программы (family_name).
Варианты значения:
true - скрыть.
false - отобразить.
 
По умолчанию false.
hide_item_quantity boolean (true, false) Скрытие столбца Количество для продукта в корзине. Если столбец скрыт, то:
- В корзину будет добавлено минимально возможное для покупки количество продукта (передается в variants.from).
- Покупатель не будет видеть, сколько экземпляров продукта добавлено в корзину, и не сможет изменить значение.
 
Варианты значения:
true - скрыть.
false - отобразить.
 
По умолчанию false.
variants Да array Массив с информацией о ценах на продукт.
Может содержать несколько объектов, в которых определена цена (price) в зависимости от количества приобретаемых экземпляров продукта (from, to).
 
Внимание! При передаче массива variants происходит замена всех текущих цен на переданные значения.
Если какое-либо вложенное поле отсутствует, то его ранее заданное значение будут удалено.
То есть нельзя в разных запросах передать цены сначала в одной валюте, затем во второй.
Или передать в первом запросе vendor_code, а во втором это поле не передавать (тогда значение будет удалено).
Каждый объект определения цены содержит:
vendor_code string(40) Рекомендуется использовать для передачи внутреннего кода продукта в системе Партнера.
Далее это значение можно передать в веб-сервис для получения лицензионной информации по продукту.
sku string(255) Рекомендуется использоваться для передачи артикула продукта по прайс-листу Партнера.
sku_ar string(255) Используется вместо sku, если на продукт оформлена подписка с автоматическим продлением лицензии.
from integer Минимальное (from) и максимальное (to) количество продукта, доступное к покупке за указанную в price цену.
В значении может указано только целое число или ноль.
Если не передано или равно нулю, то без ограничений.
 
Правила заполнения:
• Если from > 0, то tofrom или to = 0 или не передано.
• Если to > 0, то fromto.
• Интервалы from - to разных цен не должны пересекаться.
• Не должно быть интервалов, для которых не определена цена.
 
to integer
price Да, если передан массив variants object Содержит поля, соответствующие валютам продажи.
В случае, для какой-либо валюты продажи не будут переданы данные, то все цены в ней будут удалены и продукт станет не доступен для продажи в этой валюте
[валюта продажи] Да, если передан объект price string(3) Код валюты продажи.
Формат: ISO 4217 alpha-3.
currency string(3) Код валюты цены в прайсе. Может отличаться от валюты продажи.
Формат: ISO 4217 alpha-3.
Варианты значения:
RUB
USD
EUR
• [валюта продажи]
price string
(numerals; value separating by point,
with two decimal places)
Цена продукта в валюте прайса.
 
Цена может быть равно нулю 0 для триальных продуктов или подарков.
cross_sell object Настройки предложения дополнительных продуктов при оформлении заказа на основной продукт в корзине (кросс-продажи).
Настройка передается для дополнительного продукта, который должен быть предложен, если в корзине находится основной продукт
См. подробнее о дополнительных продуктах в отдельной статье.
 
Внимание! При передаче массива cross_sell происходит замена всех текущих настроек дополнительного продукта на переданные значения.
Если какое-либо вложенное поле отсутствует, то его ранее заданное значение будут удалено.
type Да,
если передано cross_sell
string
enum (candy_rack, add_to_basket)
Тип дополнительных продуктов.
Варианты значения:
candy_rack - рекомендуемый дополнительный продукт.
add_to_basket - обязательный дополнительный продукт.
См. подробнее о дополнительных продуктах в отдельной статье.
status boolean ("true", "false") Включение предложения приобрести дополнительный продукт при добавлении в корзину основного.
Варианты значения:
true - включено.
false - выключено.
 
По умолчанию true.
date_from Да,
если передано cross_sell
date (YYYY-MM-DD HH:MI:SS)
UTC+3
Дата начала (date_from) и дата окончания (date_to) действия предложения приобрести дополнительный продукт.
 
Правила заполнения:
date_from <= date_to.
date_to Да,
если передано cross_sell
date (YYYY-MM-DD HH:MI:SS)
UTC+3
removal_available boolean ("true", "false") Только для обязательных дополнительных продуктов:
Доступность удаления дополнительного продукта в корзине отдельно от основного.
Варианты значения:
true - можно удалить.
false - нельзя удалить.
 
По умолчанию true.
quantity_change_available boolean ("true", "false") Только для обязательных дополнительных продуктов:
Доступность изменения количества дополнительного продукта в корзине отдельно от основного.
Варианты значения:
true - можно изменить количество.
false - нельзя изменить количество.
 
По умолчанию true.
product_id Да,
если передано cross_sell
array (integer) Массив идентификаторов продуктов, которые являются основными для данного дополнительного продукта.
То есть тот продукт, при наличии в корзине которого будет предложен дополнительный продукт.
Если передано несколько продуктов, то дополнительный будет предложен, если хотя бы один из переданных дополнительных продуктов находится в корзине.
typo object Настройки предложения купить продукт по выгодной цене на странице оплаченного заказа (TYPO).
Настройка передается для продукта, который должен быть предложен, если в корзине находится родительский продукт
См. подробнее о TYPO в отдельной статье.
 
Внимание! На текущий момент Сервис не поддерживает управление скидками на продукт.
 
Внимание! При передаче поля typo происходит замена всех текущих настроек TYPO на переданные значения.
Если какое-либо вложенное поле отсутствует, то его ранее заданное значение будут удалено.
status boolean ("true", "false") Включение TYPO.
Варианты значения:
true - включено.
false - выключено.
 
По умолчанию true.
date_from Да,
если передано typo
date (YYYY-MM-DD HH:MI:SS)
UTC+3
Дата начала (date_from) и дата окончания (date_to) действия предложения.
 
Правила заполнения:
date_from <= date_to.
date_to Да,
если передано typo
date (YYYY-MM-DD HH:MI:SS)
UTC+3
product_id Да,
если передано typo
array (integer) Массив идентификаторов продуктов, которые являются родительскими для данного продукта.
То есть тот продукт, при наличии в заказе которого будет отображаться TYPO.
Если передано несколько продуктов, то TYPO будет предложено, если хотя бы один из переданных продуктов находится в заказе.
localization_values Данные для TYPO на определенных языках.
Можно использовать только языки, подключенные к корзине. Подключение нового языка выполняется Отделом контента.
 
Внимание! Должны быть переданы данные для каждого языка, подключенного к корзине.
При этом если для какого-либо языка нужно скрыть текст, то поле должно быть передано с пустым значением.
[локаль] Да,
если передано localization_values
string (5) Код языка интерфейса корзины, на котором переданы значения внутри объекта.
comment_for_typo text Текст для описания акции на соответствующем языке.
Можно использовать html-теги. Чтобы подставить в текст значение скидки, настроенной для продукта, можно использовать тег подстановки %DISCOUNT%.
 
Если поле не передано, то будет использован стандартный текст, например, "В качестве благодарности предлагаем вам скидку %DISCOUNT% % на еще один продукт".
Внимание! Если для продукта не настроена скидка (создан отдельный продукт для TYPO, у которого сумма скидки включена в цену), то вместо %DISCOUNT% в тексте отобразится 0 %.
license_data object Настройки для отправки покупателю лицензионной информации для продукта, подробнее.
 
Внимание! При передаче поля license_data происходит замена всех текущих настроек для отправки покупателю лицензионной информации на переданные значения.
Если какое-либо вложенное поле отсутствует, то его ранее заданное значение будут удалено.
[локаль] string (5) Код языка, на котором переданы значения внутри объекта.
customer_notification text Текст для подстановки в шаблон письма с лицензионной информацией для покупателя.
Можно использовать html-теги и теги подстановки, подробнее.

Особенности обновления данных

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

Примеры:

Действия Результат
• При создании продукта было передано поле localization_values и в нем данные для локали ru_RU.
• В запросе на обновление было передано поле localization_values и в нем только данные для локали en_EN.
В продукте останутся только данные для en_EN.
Данные для ru_RU будут удалены.
• При создании продукта было передано поле localization_values и в нем данные для локали ru_RU.
• В запросе на обновление было передано поле localization_values и в нем данные для локалей ru_RU и en_EN.
В продукте будут данные для ru_RU и en_EN.
• При создании продукта было передано поле localization_values и в нем данные для локали ru_RU.
• В запросе на обновление поле localization_values не было передано.
В продукте будут данные для ru_RU.

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

Настройка продления лицензий (подписки)

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

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

Используемые термины и обзор вариантов обработки продления см. в отдельной статье:

Продажа продлений »

Порядок настройки продления

  1. Создайте все дочерние продукты, участвующие в подписке.
    В продуктах должно быть обязательно настроено:
    • Срок действия лицензии - licence_term.
       
  2. Создайте или обновите продукт, который инициирует продление.
    В одном запросе должны быть обязательно переданы данные:
    • Срок действия лицензии - licence_term.
    • Продукт для продления - product_id_for_renew.
    • Тип обработки продления - renew_ar, renew_pmr, renew_email.
      Для AR подписок может быть дополнительно включен признак обязательности.
Дополнительно можно настроить:
  • Артикул продукта для подписки с автоматическим продлением лицензии - sku_ar.
    Если заполнено и на продукт оформлена подписка с автоматическим продлением лицензии, то значение sku_ar используется вместо обычного sku, например в экспорте заказов через Кабинет разработчика.
Если подписка уже настроена:
  • Можно изменить licence_term в продуктах участниках без передачи всех остальных полей.
  • Для изменения списка продуктов продления передайте новый список продуктов через product_id_for_renew в родительском продукте, который инициирует подписку.
    Не изменяйте это свойство в продуктах для продления.

Особенности настройки продукта для продления

Настройка продуктов для продления производится через продукт, инициирующий подписку.

Продуктом продления может быть:
  • Тот же самый продукт, который инициирует подписку.
    В этом случае покупатель покупает один продукт, и далее для продления должен приобрести его же.
  • Другой продукт.
    В этом случае покупатель покупает один продукт, и далее для продления должен приобрести другой продукт.
  • Цепочка продуктов.
    В этом случае продукт один продлевается продуктом 2, продукт 2 - продуктом 3 и так далее.

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

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

Примеры кейсов и их настройка:

Кейс Пример настройки
1 Один продукт для создания подписки и продления 1.1. Создайте продукт без настроек подписки. В ответ вернется идентификатор продукта, например, 1.
1.2. Обновите созданный продукт, заполнив параметры включения подписки. В том числе, в product_id_for_renew укажите идентификатор того продукта, который обновляете. То есть при обновлении продукта с id = 1, должен быть указан product_id_for_renew = [1].
2 Разные продукты для создания и продления подписки 2.1. Создайте продукт для продления. В ответ вернется идентификатор продукта, например, 2.
2.2. Создайте продукт, который будет инициировать подписку. Заполните параметры для включения подписки, в том числе в product_id_for_renew = [2,2].
3 Продление подписки сначала одним, затем другим продуктом 3.1. Создайте продукты для продления. Предположим им присвоены идентификаторы 3 и 4.
3.2. Создайте продукт, который будет инициировать подписку. Заполните параметры для включения подписки, в том числе в product_id_for_renew = [3,4,4].
Примеры ошибок заполнения продуктов продления:
  • Для продукта 1 - product_id_for_renew = [1,2,2] - ошибка, при таких настройках для продления всегда будет использован продукт 1, и цепочка продления никогда не дойдет до продукта 2.
    Правильные варианты:
    • [1] - всегда использовать для продления первый продукт.
    • [2,2] - всегда использовать для продления второй продукт.
    • [2,1] - использовать для продления второй продукт, затем первый (и так по кругу).
  • Для продукта 1 - product_id_for_renew = [2] - ошибка, подписка продлится один раз продуктом 2, после этого продление остановится.
    Если нужно, чтобы подписка всегда продлевалась продуктом 2, то нужно указать [2,2].

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

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

Для продуктов, управляемых через Сервис, это осуществляется следующим образом:
  • При оплате заказа инициируется автоматическое получение лицензионной информации (ключа) через отдельный веб-сервис.
  • Если ключ получен, то формируется письмо с лицензионной информацией, которое отправляется на e-mail покупателя.

Настройка веб-сервиса

Отдельный веб-сервис для получения лицензионной информации настраивается через Кабинет Разработчика (также можно обратиться для настройки в Отдел контента).

Ограничения:
  • Для всех продуктов используется один и тот же веб-сервис для получения лицензионной информации.
  • Нельзя привязать отдельные продукты к разным веб-сервисам для лицензионной информации.
  • Если привязку продукта к веб-сервису отредактировать через Кабинет Разработчика, то при обновлении продукта через Сервис управления каталогом привязка будет перезаписана.

Настройка письма

При формировании письма с лицензионной информацией используется стандартный шаблон письма, см. подробнее в отдельной статье.

В него подставляется шаблон содержания письма, который может быть получен:
  • Из поля customer_notification, переданном для продукта.
    Используется значение для локали, которая соответствует локали заказа.
  • Или (если данные в поле customer_notification не были переданы) из шаблона, настроенного для веб-сервиса получения лицензионной информации в Кабинете Разработчика.

В тексте шаблона можно использовать html-теги и теги подстановки:

Тег подстановки Подставляемые данные
{KEY} Лицензионная информация, полученная для продукта в заказе через веб-сервис для получения лицензионной информации.
Обязательно используйте этот тег подстановки в шаблоне, чтобы покупатель получил лицензионную информацию в письма.
{PARENT_KEY} Лицензионная информация из родительского заказа (для дочерних заказов, созданных по подписке с автопродлением лицензии).
{ORDER_ID} Номер заказа.
{PRICEGROUP_ID} Id продукта.
{PROGRAM_NAME} Полное название продукта.
{PROGRAM_SHORT} Название программы (передается в поле family_name).
{QUANTITY} Количество экземпляров продукта в заказе.
{PRICE_ONE_DUPLICATE} Цена одной шт. продукта.
{PRICE_ALL_DUPLICATES} Цена за все экземпляры продукта в заказе.
{FULLNAME} Имя Фамилия покупателя
{FNAME} Имя покупателя
{LNAME} Фамилия покупателя
{LICENSE_FOR} Лицензиат
{EMAIL} E-mail покупателя
{COUNTRY} Страна доставки
{CITY} Город доставки
{ZIP} Почтовый индекс
{ADDRESS} Адрес покупателя
{PHONE} Телефон покупателя
{COMPANY} Компания покупателя
{VENDOR} Компания вендора
{URL} URL страницы с инструкцией по установке продукта (из поля url_to_instructions).
{URL_FULL} URL ссылки на скачивание продукта (из поля url_to_download).
{WEBSITE_P} Сайт программы
{WEBSITE_V} Сайт Партнера
{EMAIL_V} Е-mail Партнера
{DATE} Текущая дата
{ADDINFO_TEXT} Текст из добавочного поля (заполняет покупатель при оформлении заказа на продукт, настроить поле можно через Кабинет Разработчика или с помощью Отдела контента).

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

Добавление продукта:

POST https://api.ecommerce.softline.com/v1/product
{
  "family_name": "Demo Product",
  "name": "1 Pc / 1 year",
  "is_publish": true,
  "image_url": "https://authorcart.allsoft.ru/bundles/allsoftunicartauthorcart/images/no-image-40x40.png",
  "description": "<p><strong>Test product</strong></p>",
  "comment_for_manager": "There will be a full description later",
  "url_to_instructions": "https://www.google.ru",
  "url_to_download": "https://www.google.ru",
  "business_segment": "b2c",
  "licence_term": "P1Y",
  "renew_settings": {
        "product_id_for_renew":[4645130,4645131,4645131],
        "renew_ar":{
            "enable":true,
            "required":true
                   },
        "renew_pmr":true,
        "renew_email":false
      },
  "localization_values": 
    {
    "ru_RU": 
      {
       "family_name": "Тестовый продукт",
       "name": "1 ПК/1 год",
       "description": "<p><strong>Тестовый продукт</strong> для тестовой покупки</p>",
       "comment_for_cart": "Это тестовая покупка.",
       "comment_for_product_top": "Срок действия лицензии 1 год.",
       "comment_for_product_middle": "Новая версия тестового продукта.",
       "comment_for_product_for_AR": "Продление лицензии осуществляется автоматически.",
       "comment_for_product_for_MR": "Вам нужно будет продлить лицензию через 1 год вручную.",
       "comment_for_product_bottom": "Эта лицензия не для продажи или активации за пределами страны." 
      },
    "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",
        "sku_ar": "111AR",
        "from": 1,
        "to":5,
        "price": {
          "RUB": {"currency": "USD", "price": "99.99"},
          "UAH": {"currency": "USD", "price": "99.99"}
        }
      },
      {
        "vendor_code": "1",
        "sku": "111",
        "sku_ar": "111AR",
        "from": 6,
        "price": {
          "RUB": {"currency": "USD", "price": "80.99"},
          "UAH": {"currency": "USD", "price": "80.00"}
        }
      }
  ],
  "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": "This is a test purchase."}},
    "product_id": [4645130,4645131]
    },
  "license_data": 
    {
    "ru_RU": 
      {"customer_notification": "Ваш серийный номер: {KEY}"},
    "en_EN": 
      {"customer_notification": "Key: {KEY}"}
    }  

}

Обновление продукта:

PATCH https://api.ecommerce.softline.com/v1/product/123456
Параметры запроса аналогично запросу создания продукта.

Запросы на получение и удаление продукта

URL
[Идентификатор_продукта]
Тип запроса • Получение информации о продукте: GET
• Удаление продукта: DELETE
Формат передачи данных Параметр в URL
Авторизация С помощью токена

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

Параметр Формат Описание
id integer Идентификатор продукта. Передается в URL запроса.

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

Получение информации о продукте:

GET https://api.ecommerce.softline.com/v1/product/123456

Удаление продукта:

DELETE https://api.ecommerce.softline.com/v1/product/123456

Описание ответа

Положительный ответ

Параметры ответа

Код ответа 200 Для запросов: POST, GET, PATCH, DELETE
Параметры ответа id продукта Для запроса: POST
Данные продукта
В том же формате как при отправке запроса создания продукта.
Если какое-либо поле не было заполнено у продукта ранее, то его значение вернется пустым.
Например, для продукта не были сделаны настройки для обработки продления лицензии, в этом случае в ответе вернется:
"renew_settings": { "product_id_for_renew": [], "renew_ar": { "enable": false, "required": false }, "renew_pmr": false, "renew_email": false }
Для запроса: GET

Примеры ответа

Пример ответа на запрос создания продукта
Код ответа 200
Параметры ответа
{ "id": 111122233}
Пример ответа на запрос обновления и удаления продукта
Код ответа 200
Пример ответа на запрос получения информации о продукте
Код ответа 200
Параметры ответа
{
    "id": "4645906",
    "family_name": "Demo Product",
    "name": "1 Pc / 1 year",
    "is_publish": true,
    "image_url": "",
    "description": "<p><strong>Test product</strong></p>",
    "comment_for_manager": "There will be a full description later",
    "url_to_instructions": "https://www.google.ru",
    "url_to_download": "https://www.google.ru",
    "business_segment": "b2c",
    "licence_term": "P1Y",
    "localization_values": {
        "ru_RU": {
            "family_name": "Тестовый продукт",
            "description": "<p><strong>Тестовый продукт</strong> для тестовой покупки</p>",
            "name": "1 ПК/1 год",
            "comment_for_product_top": "Срок действия лицензии 1 год.",
            "comment_for_product_middle": "Новая версия тестового продукта.",
            "comment_for_product_for_AR": "Продление лицензии осуществляется автоматически.",
            "comment_for_product_for_MR": "Вам нужно будет продлить лицензию через 1 год вручную.",
            "comment_for_product_bottom": "Эта лицензия не для продажи или активации за пределами страны.",
            "comment_for_cart": "Это тестовая покупка." 
        },
        "en_EN": {
            "family_name": "Test product",
            "description": "<p> <strong> Test product </strong> for test purchase </p>",
            "name": "1 PC/1 year ",
            "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.",
            "comment_for_cart": "This is a test purchase." 
        }
    },
    "display_settings": {
        "hide_name": true,
        "hide_item_quantity": true
    },
    "renew_settings": {
        "product_id_for_renew": [],
        "renew_ar": {
            "enable": false,
            "required": false
        },
        "renew_pmr": false,
        "renew_email": false
    },
    "variants": [
        {
            "vendor_code": "1",
            "sku": "111",
            "sku_ar": "",
            "price": {
                "RUB": {
                    "currency": "USD",
                    "price": "99.99" 
                },
                "UAH": {
                    "currency": "USD",
                    "price": "99.99" 
                }
            },
            "from": "1",
            "to": "5" 
        },
        {
            "vendor_code": "1",
            "sku": "111",
            "sku_ar": "",
            "price": {
                "RUB": {
                    "currency": "USD",
                    "price": "80.99" 
                },
                "UAH": {
                    "currency": "USD",
                    "price": "80.00" 
                }
            },
            "from": "6" 
        }
    ],
    "typo": [],
    "cross_sell": [],
    "license_data": {
        "ru_RU": {
            "customer_notification": "Ваш серийный номер: {KEY}" 
        },
        "en_EN": {
            "customer_notification": "Key: {KEY}" 
        }
    }
}

Ошибки

В случае ошибки в ответ вернется код ответа и, в некоторых случаях, json с описанием ошибки.

Справочник ошибок

Ответ Для каких запросов Описание
HTTP/1.1 401 Unauthorized POST, GET, PATCH, DELETE Неуспешная авторизация.
В теле ответа будет передан json с внутренним кодом ошибки и описанием.
HTTP/1.1 500 Request Error POST, GET, PATCH, DELETE Ошибка на стороне сервера.
HTTP/1.1 400 Bad Request POST, GET, PATCH, DELETE Запрос не валиден (ошибка в параметрах; не переданы необходимые данные и т.п.).
В теле ответа будет передан json с внутренним кодом ошибки и описанием.
HTTP/404 Not Found GET, PATCH, DELETE Продукт не найден.
В теле ответа будет передан json с внутренним кодом ошибки и описанием.

Дополнительные коды ошибок для ошибки 400

Code ErrorMessage Для каких запросов Описание
Если хотя бы одна ошибка из списка ниже найдена, то она возвращается в ответе на запрос, остальные ошибки не проверяются.
1020 Could not identify product settings for this currency. Please contact technical support. POST, PATCH При создании ценовой группы не смогли однозначно определить логин Партнера и/или договор.
Проверьте, что в запросе правильно передана валюта в поле
variants.price.[валюта]. В случае, если проблема сохраняется, обратитесь в Отдел контента.
1040 According to the Agreement, this product cannot be sold in this currency. For more information, please contact the Content Department. POST, PATСH Невозможно создать продукт в указанной валюте.
Если хотя бы одна ошибка из списка ниже найдена, то проверка запроса не прерывается. В ответе может быть возвращено несколько ошибок.
1010 Invalid field value: [название поля] POST, GET, PATCH, DELETE Запрос не валиден (ошибка в параметрах; не переданы необходимые данные и т.п.).
1050 Locale not found. POST, PATСH Передан неправильный код языка (localization_values.[локаль], typo.localization_values.[локаль], license_data.[локаль]).
1060 Auto-renewal cannot be enabled (renew_ar). No data: [список полей, которые не были переданы]. POST, PATСH В запросе передано включение подписки AR (renew_ar = true), но отсутствуют обязательные данные. Необходимые данные будут перечислены в тексте ошибки.
1070 "Mandatory auto-renewal" condition (renew_ar.required) can only be enabled if auto-renewal is enabled (renew_ar.enable). POST, PATСH В запросе передано включение обязательности подписки AR (renew_ar.required = true), но при этом доступность подписки AR выключена (renew_ar.enable = false).
1080 Pre-filled manual renewal cannot be enabled (renew_pmr). No data: [список полей, которые не были переданы]. POST, PATСH В запросе передано включение PMR подписки (renew_pmr = true), но отсутствуют обязательные данные. Необходимые данные будут перечислены в тексте ошибки.
1090 Function to send an email containing a license renewal buy link cannot be enabled (renew_email). No data: [список полей, которые не были переданы]. POST, PATСH В запросе передано включение отправки письма с предложением купить продление (renew_email = true), но отсутствуют обязательные данные. Необходимые данные будут перечислены в тексте ошибки.
1100 Invalid renewal products for product_id_for_renew. No products found: [список id продуктов, которые не прошли проверку]. POST, PATСH В переданном списке продуктов продления (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. POST, PATСH Нарушены правила составления цепочки продуктов продления.
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. POST, PATСH Неправильная валюта, в которой указана цена продукта (variants.price.[валюта продажи].currency:[валюта прайса]). В тексте ошибки будут перечислены допустимые валюты.
1130 Invalid price range (variants.from, variants.to). POST, PATСH Ошибка в минимальном и(или) максимальном количестве продукта, для которого задана цена.
1140 Products for cross_sell.product_id are incorrect. Products not found: [список id продуктов, которые не прошли проверку]. POST, PATСH В списке основных продуктов для дополнительного (cross_sell.product_id) хотя бы один продукт не прошел проверку.
1150 Parameters for cross_sell: date_from, date_to are incorrect. POST, PATСH Даты для дополнительных продуктов не прошли проверку.
1160 Products for typo.product_id are incorrect. Products not found: [список id продуктов, которые не прошли проверку]. POST, PATСH В списке родительского продукта для TYPO (typo.product_id) хотя бы один продукт не прошел проверку.
1170 Parameters for typo: date_from, date_to are incorrect. POST, PATСH Даты для TYPO не прошли проверку.

Дополнительные коды ошибок для ошибки 401

Справочник ошибок при авторизации по токену »

Дополнительные коды ошибок для ошибки 404

Code ErrorMessage Для каких запросов Описание
1030 Product not found GET, PATCH, DELETE Если продукт в системе не найден, либо нет доступа к его обновлению.

Примеры ошибок

Одна ошибка Несколько ошибок
HTTP/404 Not Found
{"errors": [ 
  {
    "error": 1030, 
    "message": "Product not found" 
  }
  ]
}
HTTP/400 Bad Request
{"errors": [ 
  {
    "error": 1010,
    "message": "Invalid field value: family_name" 
  },
  {
    "error": 1050, 
    "message": "Locale not found." 
  },
 ...
  {
    "error": 1060, 
    "message": "Auto-renewal cannot be enabled (renew_ar). No data: licence_term, product_id_for_renew." 
  }
  ]
}

Примеры запросов в Postman

Скачать коллекцию запросов