Project

General

Profile

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

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

Версия: 2.1 (27.08.2021)
  • Добавлены параметры к запросу: способ доставки (is_delivery_needed), начисление НДС для продаж в руб. (vat_included).

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

(/) Далее описана новая версия протокола (релиз от 22.06.21). Предыдущая версия является устаревшей и более не обновляется.
Если вы работаете через старый протокол, то рекомендуем обновить подключение.
Сервис позволяет продавать продукты, у которых:
  • Часть свойств продукта (например: наименование, цена) передается в запросе при генерации ссылку на покупку,
  • Другая часть свойств берется из базового продукта, предварительного настроенного в каталоге партнера на стороне Softline Ecommerce.

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

Схема работы:
  1. Партнер передает в запросе:
    • Список динамических продуктов, которые должны быть добавлены в корзину.
      По каждому продукту: идентификатор базового продукта, динамические характеристики (название, цена и др).
    • Данные покупателя (опционально).
      Если данные переданы, то покупателю не нужно будет их заполнять в корзине для оформления заказа. Он увидит уже предварительно заполненные поля и сможет их отредактировать.
       
  2. В ответ сервис возвращает ссылку на покупку, которую нужно предоставить покупателю для оформления заказа.
     
  3. При переходе по ссылке в корзину будут добавлены переданные продукты и предварительно заполнены данные покупателя.
     
  4. Далее покупатель может оформить заказ.
(!) Внимание! Ссылка является одноразовой, по ней можно оформить только один заказ. Динамические продукты не добавляются в каталог. Подробнее.

Примеры использования:
  • Продажа продуктов, у которых покупатель выбирает конфигурацию в каталоге партнера.
    Например, на стороне партнера есть "калькулятор", который позволяет покупателю настроить совокупность свойств продукта и рассчитать цену.
    Если таких свойств достаточно много, то быстрее получать ссылку на покупку через описываемый сервис, чем создавать в каталоге продукты для каждой возможной комбинации свойств.
  • Продажа часто изменяемых продуктов, которые партнер не хочет постоянно добавлять и редактировать через каталог на стороне Softline Ecommerce.
  • Предоставление специальных условий для определенных покупателей.
    Например: особая цена на продукт или особая комплектация, предварительное заполнение данных покупателя в корзине.

Начало работы

Для получения доступа к API обратитесь к своему аккаунту менеджеру.

Данные для подключения

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

Конфигурация базового продукта

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

Настройку базового продукта выполняет Отдел контента. Может быть настроено несколько базовых продуктов с разными значениями свойств.

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

Свойство Описание
Доступные регионы продажи Определяет валюты, в которых может продаваться продукт.
Изображение продукта Отображается для продукта в корзине.
Описание продукта Если задано, то для продукта в корзине отображается иконка, при нажатии на которую открывается описание.
Особенности налогообложения
Способ начисления VAT Определяет способ начисления VAT на цену продукта. Варианты значения:
• VAT включен в цену, то есть покупатель увидит в корзине ту цену, которая передана для продукта в запросе,
• VAT начисляется сверху цены при добавлении продукта в корзину, то есть в запросе передана одна цена, которая при добавлении в корзину увеличится на сумму налога.
 
Данное свойство заполняется в соответствии с договором и одинаковое для всех продуктов, которые продаются по этому договору.
Начисление НДС при продаже в руб. Только при продаже продукта в рублях. Варианты значения:
• начисляется (согласно выбранному способу),
• продукт не облагается НДС.
 
Данное свойство может быть переопределено в запросе.
 
Для продаж в других валютах VAT начисляется всегда. Ставка определяется автоматически и зависит от региона продажи.
Наличие программы в едином реестре Российского ПО Только если партнер является резидентом РФ и плательщиком НДС.
Варианты значения:
• программа внесена в реестр,
• программа не внесена в реестр.
 
Если программа не внесена в Реестр российского ПО (https://reestr.digital.gov.ru/), то при взаиморасчетах с партнером сумма НДС считается включенной в вознаграждение.
Особенности отображения продукта в корзине
Скрытие количества продукта в корзине Позволяет скрыть количество продукта в корзине.
Независимо от настройки: количество определяется из запроса к Сервису и не может быть изменено покупателем.
Комментарии для продукта в корзине Выводится рядом с названием продукта в корзине или внизу страницы корзины рядом с кнопкой продолжения оформления заказа.
Рядом с названием можно отобразить до 4х комментариев, в том числе 1 из них может отображаться только в случае, если согласие на автоматическое продление лицензии включено.
Особенности доставки продукта
Получение лицензионной информации по продукту Для продуктов с электронным способом доставки (на email).
Связь с способом автоматического получения и отправки ключей. Это те же самые способы, которые настраиваются в Кабинете разработчика.
Настройки продаж продления лицензии
Поддерживаются подписки с автоматическим продлением лицензии. Описание работы см. в отдельной документации.
Включение подписок с автоматическим продлением лицензии Если включено, то для продукта могут быть переданы данные по подписке в запросе.
Срок действия лицензии Период, в течение которого лицензия на продукт активна (покупатель может использовать приобретенный продукт).
Значение из базового продукта используется для продукта продления (дочерний продукт).

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

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

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

Другие особенности оформления заказа по полученной ссылке на покупку см. далее.

URL https://api.ecommerce.softline.com/v1/generate_buy_link
Метод передачи данных POST
Формат передачи данных JSON
Кодировка UTF-8
Авторизация С помощью токена

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

Параметры Обязательно Тип данных Описание
currency Да string (3) Валюта продажи.
Формат: ISO 4217 alpha-3.
products Да array Содержит список динамических продуктов, которые нужно добавить в корзину.
id Да number ID базового продукта. Если в запросе содержится несколько продуктов, то их id не могут совпадать. То есть в одном запросе не может быть два продукта с динамическими характеристиками на основе одного и того же базового продукта.
sku string (40) Рекомендуется использоваться для передачи артикула продукта по прайс-листу Партнера.
vendor_code string (255) ID продукта на стороне Партнера.
name Да string Наименование продукта.
name_for_invoice string Наименование продукта для закрывающих документов. Используется в закрывающих документах из 1С по заказу (например, счет-фактура, товарная накладная), которые покупатель получает в соответсвующим письме.
price Да string Цена за единицу продукта без учета скидки.
Формат: Число с 2 десятичными знаками, разделитель - точка. Передается как строка.
Может быть равна нулю, в этом случае в запросе должна быть хотя бы одна позиция с ненулевой стоимостью с учетом скидки. Нулевая цена используется для добавления подарка в корзину. Продажа продуктов с триальным периодом по нулевой цене на текущий момент не доступна через данный сервис.
discount_percent number Скидка на продукт в процентах.
Формат: Число, до 6 десятичных знаков, разделитель - точка.
0 < discount_percent <= 100.
Если discount_percent = 100, то в запросе должен быть хотя бы один продукт, у которого стоимость со скидкой больше нуля. Цена со скидкой 100% используется для добавления подарка в корзину.
quantity Да number Количество продукта в корзине. Покупатель не сможет изменить это количество.
is_delivery_needed boolean Способ доставки продукта:
 
Варианты значения:
true - физическая доставка,
false - электронная доставка (лицензионная информация отправляется покупателю на email).
 
По умолчанию false.
is_service boolean Техническое поле.
vat_included boolean Только для продажи продукта в рублях (currency = RUB):
переопределяет настройку способа начисления НДС, сделанную для базового продукта.
 
Варианты значения:
true - НДС начисляется,
false - продукт не облагается НДС.
 
Если значение не передано, то оно будет взято из настроек базового продукта.
subscription object Если поле передано и для базового продукта сделаны предварительные настройки, то на продукт можно будет оформить подписку с автоматическим продлением лицензии, подробнее.
period Да, если
передано поле subscription
string Срок действия лицензии для продукта, инициирующего подписку (родительского).
Формат: ISO 8601 code: P[число][ед.измерения].
Поддерживаемые единицы измерения: Y - год, M - месяц, D - день
Например, "P1Y" соответствует сроку "1 год".
name string Название продукта для продления подписки (дочернего).
Если не передано, то будет использовано название из продукта для продления, привязанного к базовому продукту.
price string Цена за единицу продукта для продления подписки (дочернего). См. подробнее о расчете окончательной цены за продление.
Формат: Число с 2 десятичными знаками, разделитель - точка. Передается как строка.
Если не передано, то будет использована цена из продукта для продления, привязанного к базовому продукту.
customer object Если поле передано, то в корзине будут предварительно заполнены данные покупателя, подробнее.
type string Тип покупателя.
Возможные варианты:
physical - физическое лицо;
juridical - юридическое лицо.
email string (72) E-mail покупателя.
first_name string (255) Имя покупателя.
last_name string (255) Фамилия покупателя.
phone string (64) Номер телефона покупателя.
vat_number stringr(255) Номер налогоплательщика. В том числе используется для заполнения ИНН при продажах в России.
company_name string (255) Наименование компании.
company_billing_address string (255) Юридический адрес.
company_delivery_address string (255) Фактический адрес.
country string (2) Код страны покупателя по ISO 3166-1.
На текущий момент переданное значение не используется при оформлении заказа. Покупатель должен будет выбрать страну самостоятельно, если это необходимо для оформления заказа.
additional_data object Содержит дополнительные параметры для заказа.
referer7 string (255) Могут быть переданы значения, которые будут сохранены в заказ как рефереры. Сохраняется и далее используется так же как при передаче рефереров в параметрах в ссылке на покупку.
referer8 string (255)
referer9 string (255)
referer10 string (255)
referer11 string (255)
referer12 string (255)

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

{"currency": "RUB",
"products":
  [
   {
     "id": 111222,
     "vendor_code": "API-1",
     "sku": "L1-1",
     "name": "Program The electronic version license for 3 year",
     "name_for_invoice": "Program 1 v1, 3",
     "price": "1120.50",
     "discount_percent": 10,
     "quantity": 1,
     "subscription":
      {
       "period": "P1Y",
       "name": "Program The electronic version license for 1 year",
       "price": "900" 
      }
     "is_delivery_needed": false,
     "is_service": false,
     "vat_included": true
   },
   {
     "id": 2223333,
     "vendor_code": "API-1",
     "sku": "L1-1",
     "name": "Program (box)",
     "price": "2000.50",
     "discount_percent": 20.555544,
      "quantity": 1
      }
     "is_delivery_needed": true,
     "is_service": false,
     "vat_included": true
  ],
"customer": 
  {
    "type": "juridical",
    "email": "test@test-allsoft.ru",
    "first_name": "Ivan",
    "last_name": "Petrov",
    "phone": "7999991111",
    "vat_number": "12345654321",
    "company_name": "Cats and owls",
    "company_billing_address": "St. Petersburg, Nevsky Prospect, 28. of. 1",
    "company_delivery_address": "St. Petersburg, Nevsky Prospect, 28. of. 1",
    "country": "RU" 
  },
"additional_data": 
  {
    "referer7": "product=test&project=test",
    "referer8": "testA",
    "referer9": "testB",
    "referer10": "testC",
    "referer11": "testD",
    "referer12": "testF" 
  }
}

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

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

В ответ возвращается код HTTP/1.1 200 OK и JSON с ссылкой на покупку (параметр buy_link).

Пример:

{"buy_link": "https://[домен корзины]/basket/flash/123456"}

В случае, если при переходе по ссылке открывается пустая корзина (продукт не был добавлен), то такая проблема возникает, если базовый продукт не доступен для продажи на стороне Softline Ecommerce. Проверьте id базового продукта в запросе.

Ошибки

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

Справочник ошибок
Ответ Описание
HTTP/1.1 401 Unauthorized Неуспешная авторизация.
В теле ответа будет передан json с внутренним кодом ошибки и описанием.
HTTP/1.1 500 Request Error Ошибка на стороне сервера.
HTTP/1.1 400 Bad Request Запрос не валиден (ошибка в параметрах; не переданы необходимые данные и т.п.).
В теле ответа будет передан json с внутренним кодом ошибки и описанием.
Дополнительные коды ошибок для ошибки 400
Code ErrorMessage Описание
Если хотя бы одна ошибка из списка ниже найдена, то она возвращается в ответе на запрос, остальные ошибки не проверяются.
3120 Unable to define cart settings for this currency. Please contact technical support. Не получилось определить корзину или продукт для переданной валюты продажи (currency).
Если хотя бы одна ошибка из списка ниже найдена, то проверка запроса не прерывается. В ответе может быть возвращено несколько ошибок.
3010 Invalid field value: [наименование поля] Формат поля не соответствует указанному.
3020 Order price cannot be equal to zero. Change product price (price, discount_percent) or add product having non-zero price. Стоимость продукта с учетом скидки равна нулю (price = 0 или discount_percent = 100), но в запросе нет другого продукта, у которого стоимость будет больше нуля.
3030 Incorrect discount value. Discount_percent value must be strictly greater than zero and less than or equal to 100. Не правильное значение скидки (discount_percent), значение должно отвечать условиям: 0 discount_percent <= 100.
3040 Purchase of this original product subscription is impossible. Change original product (id) or delete subscription data (subscription). В запросе переданы данные для подписки (subscription), но для базового продукта на стороне Softline Ecommerce не доступна подписка.
3050 Purchase of this original product is impossible. Change original product (id). В запросе передан базовый продукт (id), который не найден на стороне Softline Ecommerce.
3060 Email field is filled out incorrectly. Expected format: [name]@[domain].[zone] Передан не корректный email адрес (email).
3070 Single request must contain products with different products.id values. Передано более одного продукта с одинаковым id.
Пример ошибки
{"errors": [ 
  {
    "error": 3010, 
    "message": "Invalid field value: currency." 
  },
  {
    "error": 3010, 
    "message": "Invalid field value: name." 
  }
  ]
}

Особенности работы

Оформление заказа

При переходе по ссылке, полученной в ответ на запрос:

  • В корзине будут только те продукты, которые переданы в запросе.
    • Если покупатель ранее добавлял в корзину другой продукт, то он будет удален из корзины.
    • Если покупатель добавит другой продукт после того, как перешел по ссылке из запроса, то в корзине останется только последний продукт (продукты, переданные в запросе, будут удалены).
  • Цены на продукты:
    • Будут указаны в валюте, которая передана в currency.
      Если в корзине поддерживается несколько валют, то покупатель сможет выбрать другую валюту вручную.
    • Могут быть увеличены на сумму налога (VAT), если для продуктов настроено начисление VAT сверху цены и процент налога больше 0% для региона продажи.
  • Покупатель не может редактировать состав корзины (нет возможности изменить количество или удалить продукт).
  • К заказу может быть применен купон также, как и в обычной корзине.
    • При создании купона он должен быть привязан к ID базового продукта. Таким образом купон будет действовать на все динамические продукты, добавленные в корзину на основе соответствующего базового.
    • Если в запросе была передана скидка и далее активирован купон - то к продукту в корзине будет применена наибольшая из них.
    • Дополнительные параметры в ссылке на покупку для работы с купонами - не действуют.
  • Данные покупателя будут предварительно заполнены:
    • Если покупатель ранее оформлял заказ через корзину, и его данные сохранены в cookie, то они будут использованы для предварительного заполнения полей.
      Если в запросе при этом были переданы аналогичные поля customer, то они не будут использованы.
    • Если данных нет в cookie и были переданы поля customer в запросе, то они будут использованы для предварительного заполнения полей
    • Покупатель сможет изменить предварительно заполненные значения. В заказ будет сохранены данные, которые в итоге были указаны при оформлении заказа.
  • В ссылку могут быть добавлены дополнительные рефереры (кроме переданных в запросе) с помощью параметров.

Работа с подписками

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

Схема работы

  1. В базовом продукте должны быть сделаны предварительные настройки.
  2. В запросе к Сервису необходимо передать дополнительные параметры (subscription), которые определяют, что это продукт с автопродлением, и задают настройки подписки.
  3. Далее, как и при стандартной схеме работы, в ответ возвращается ссылка на покупку, Покупатель переходит по ней в корзину и может оформить заказ.
  4. В корзине для продукта выводится флаг согласия с автопродлением, с помощью которого покупатель может подтвердить согласие на подписку.
  5. Если покупатель соглашается и выбирает соответствующий способ оплаты заказа с поддержкой автопродления лицензии, то после оплаты заказа создается Подписка.
    • Заказ, который инициирует создание подписки является родительским.
    • Заказы, созданные автоматически, для продления подписки - являются дочерними.
  6. Дальнейшая работа Подписки осуществляется по стандартной схеме (см. отдельную статью), за исключением некоторых особенностей.
    В том числе по стандартной схеме:
    • Незадолго до завершения срока действия лицензии происходит автоматическое создание дочернего заказа для продления лицензии.
    • Созданный дочерний заказ оплачивается автоматически (деньги списываются со счета того же способа оплаты, который использовался для родительского заказа).

Особенности работы Подписок

Стандартные возможности работы с Подписками описаны в отдельной статье.

Особенности для динамических продуктов:

  • Срок действия лицензии продукта по разному определяется для родительского и дочернего заказа:
    • В родительском заказе срок действия лицензии передается в запросе к Сервису (subscription.period).
      Это позволяет задавать разный срок действия для одного и тоже же продукта в каждом запросе.
    • В дочернем заказе срок действия лицензии определяется из настроек базового продукта и является одинаковым для всех динамических продуктов, созданных на его основе.
    • Через отдельный Сервис управления подписками можно изменять дату окончания действия лицензии каждой конкретной Подписки.
  • Стоимость продления за 1 шт. продукта передается в запросе к Сервису (subscription.price) и далее используется на протяжении всей жизни Подписки. То есть в каждом дочернем заказе будет одинаковая стоимость продления.
    • При расчете стоимости продления:
      - цена будет умножена на кол-во единиц продукта, такое же как у родительского продукта,
      - может быть добавлена сумма VAT, по тем же правилам, что и к цене в корзине,
      - если в запросе была передана скидка для родительского продукта, то она не применится для продления.
       
    • Изменить стоимость продления можно через отдельный Сервис управления подписками.
  • Название продукта продления передается в запросе к Сервису (subscription.name) и далее используется на протяжении всей жизни Подписки. То есть в каждом дочернем заказе будет одинаковое название продукта продления.
    Изменить название можно через отдельный Сервис управления подписками.
Пример источников данных для работы подписки

Если в запросе не были переданы название и (или) цена продления, то эти данные будут определены из продукта продления, который привязан к базовому продукту

Тестирование подписок

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

Получение информации по заказам

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

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

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

Скачать коллекцию запросов
Пример заполненных значений в Postman

Пример настроенных переменных в Postman

Просмотр значений переменных, которые будут подставлены в запрос при отправке