Project

General

Profile

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

(!) Данная версия протокола (1.7) является устаревшей. Для нового подключения используйте новую версию протокола: 2.0 →

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

Версия сервиса: 1.7 (08.06.2021)

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

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

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

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

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

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

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

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

Данные Описание
Логин Логин Партера в Softline Ecommerce (тот же самый логин, который используется для входа в Кабинет Разработчика).
URL корзины URL корзины, на которой будет осуществляться продажа динамических продуктов.
IP-адрес Список IP-адресов, с которых будет приходить XML.
 
При получении XML на стороне Softline Ecommerce:
• Проверяется, входит ли IP-адрес, с которого получен XML, в список разрешенных.
• Если входит, то по IP адресу определяется, через какую корзину должна быть совершена покупка (какой адрес корзины будет подставлен в ссылку на покупку).
 
Если IP-адрес не входит в список разрешенных или по IP-адресу не определен адрес корзины, то будет возвращена ошибка.

Описание запроса

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

Параметры запроса, передаются в data.

Название параметра Обязательность Описание
product
preset_client_type Указывает, какой тип Покупателя должен быть выбран в корзине по умолчанию.
Возможные значения:
home - физическое лицо;
biz - юридическое лицо.
id Да Идентификатор продукта на стороне Партнера.
price Да Контейнер, содержащий описание цены продукта.
currency Да Код валюты, в которой будут отображены цены в корзине и оформлен заказ, например, RUB.
Должна быть передана одна из валют, доступных для корзины.
 
Если корзина поддерживает работу в нескольких валютах, то продукт будет добавлен в корзину в валюте, переданной в XML.
При этом покупатель сможет вручную изменить валюту заказа на другую допустимую, выбрав ее из выпадающего списка, если это ему необходимо.
sum Да Сумма заказа в валюте параметра currency.
discount Да Величина скидки в процентах.
Величина скидки не отображается в корзине, но будет применена к стоимости продукта.
Если скидки нет, то необходимо указать 0%.
discountsum Да Сумма заказа с учетом скидки в валюте параметра currency.
scu Код продукта в каталоге Партнера.
Может содержать несколько значений, разделенных запятой (для сложных позиций).
title Да Контейнер, содержащий наименование продукта.
ru Да Полное наименование продукта на языке корзины.
license Контейнер, содержащий данные по компонентам лицензии.
item Да
если контейнер license передается
Контейнер, содержащий информацию об одном компоненте лицензии.
id Да
если контейнер license передается
Идентификатор компонента лицензии.
description Да
если контейнер license передается
Описание компонента лицензии.
quantity Да
если контейнер license передается
Количество.
user Данные Покупателя. Используются для предзаполнения полей при оформлении заказа.
email E-mail Покупателя.
first_name Имя Покупателя.
last_name Фамилия Покупателя.
phone Телефон Покупателя.
company Данные Покупателя, являющегося юридическим лицом. Используются для предзаполнения полей при оформлении заказа.
name Наименование компании.
juridical_address Юридический адрес.
actual_address Фактический адрес.
inn ИНН (указывается только для продажи в зоне RU).
kpp КПП (указывается только для продажи в зоне RU).
subscription_renewable Предлагать или нет покупателю оформление подписки с автопродлением на данный продукт.
Возможные значения:
yes - предлагать.
no - не предлагать.
См. подробнее о подписках.
period Да
если subscription_renewable = yes
Срок действия лицензии.
Используется для продуктов с подпиской (subscription_renewable=yes) и определяет срок действия лицензии в родительском заказе, подробнее.
Минимальный срок действия лицензии может быть не менее 6 дней. Если нужен меньший срок - обратитесь в Отдел контента.
Формат: [количество единиц измерения][тип единиц измерения], где тип может быть: d - дней, m - месяцев, y - лет.
Например: 12m - соответствует 12 месяцам
subscription_product_name Название дочернего продукта для подписки
subscription_product_price Стоимость продления подписки. Указывается в той же валюте, что и стоимость основного продукта в запросе (отдельно валюта не передается).
На эту сумму будет оформлен дочерний заказ.

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

<?xml version="1.0" encoding="UTF-8"?>
<product>
   <preset_client_type>home</preset_client_type>
   <id>444</id>
   <price currency="RUB">
      <sum>1584.00</sum>
      <discount>0%</discount>
      <discountsum>1584.00</discountsum>
      <scu>FF000011</scu>
   </price>
   <title>
      <ru>Электронная версия на 2 ПК, 1 год</ru>
   </title>
   <license>
      <item>
         <id>1</id>
         <description>Рабочие станции</description>
         <quantity>1</quantity>
      </item>
   </license>
   <user>
      <email>usermail@example.com</email>
      <first_name>Ivan</first_name>
      <last_name>Petrov</last_name>
      <phone>+7 111 111 1111</phone>
   </user>
   <company>
      <name>Наша компания</name>
      <juridical_address>г. Нск ул. Ленина 1</juridical_address>
      <actual_address>г. Нск ул. Ленина 1</actual_address>
      <inn>1111111111</inn>
      <kpp>-</kpp>
   </company>
   <subscription_renewable>yes</subscription_renewable>
   <period>12m</period>
   <subscription_product_name>Электронная версия на 2 ПК, 1 год Продление</subscription_product_name>
   <subscription_product_price>1200.00</subscription_product_price>
</product>

Пример кода на PHP

<?php

       $url = 'https://ws-public.allsoft.ru/SlOuter_ComplexBasketWizard/';
       $data = '<?xml version="1.0" encoding="UTF-8"?>
<product>
  <preset_client_type>home</preset_client_type>
  <id>444</id>
  <price currency="RUB">
    <sum>1584.00</sum>
    <discount>0%</discount>
    <discountsum>1584.00</discountsum>
    <scu>FF000011</scu>
  </price>
  <title>
    <ru>Electronic version for 2 PCs, 1 year</ru>
  </title>
  <license>
    <item>
       <id>1</id>
       <description>Workstations</description>
       <quantity>1</quantity>
    </item>
  </license>
  <user>
     <email>usermail@example.com</email>
     <first_name>Ivan</first_name>
     <last_name>Petrov</last_name>
     <phone>+7 111 111 1111</phone>
  </user>
  <company>
     <name>Our company</name>
     <juridical_address>Ulitsa Lenina, 1, Novosibirsk</juridical_address>
     <actual_address>Ulitsa Lenina, 1, Novosibirsk</actual_address>
     <inn>1111111111</inn>
     <kpp>-</kpp>
  </company>
  <subscription_renewable>yes</subscription_renewable>
  <period>12m</period>
  <subscription_product_name>Электронная версия на 2 ПК, 1 год Продление</subscription_product_name>
  <subscription_product_price>1200.00</subscription_product_price>
</product>';

      if (($curl = curl_init())) {
        curl_setopt_array($curl,[
            CURLOPT_URL => $url, 
                        CURLOPT_RETURNTRANSFER => true, 
                        CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => http_build_query([
                'data' => $data,
            ]),
        ]);
        echo curl_exec($curl);
        curl_close($curl);
      }

?>

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

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

Параметр Содержание
link Ссылка на добавление в корзину продукта из запроса.
Параметр заполнен, если запрос был успешно обработан.
error Сообщение об ошибке.
Параметр заполнен, если при обработке запроса возникла ошибка.

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

Пример:

<?xml version="1.0" encoding="UTF-8"?>
        <response>
            <link><![CDATA[https://drweb.allsoft.ru/basket/complex/1682898]]></link>
            <error></error>
        </response>

Ошибки

Передаваемое значение Описание
Доступ с данного IP-адреса запрещен, [IP-адрес]. Входящий XML отправлен с IP адреса, который не указан как разрешенный.
XML имеет некорректный формат: String could not be parsed as XML. XML имеет некорректный формат.
XML имеет некорректный формат: <подробное описание, например: Отсутствует элемент xml: [элемент]> Входящий XML не прошел валидацию.
XML имеет некорректный формат. Входящий XML не прошел валидацию и содержит разные ошибки.
Указанная валюта не поддерживается. Во входящем XML передана валюта, не указанная в списке возможных значений.
Не переданы XML-данные для renewable. В запросе передан параметр subscription_renewable = yes, но отсутствуют другие параметры, которые являются обязательными, для этого случая.
Поле period не соответствует формату ^(\d+)([dmy])$: <переданное значение>. Неверный формат значения поля period для продукта с подпиской.
Прочие ошибки, например:
• Ошибка сохранения параметров;
• Ошибка получения URL-а корзины;
• Внутренняя ошибка сервиса;
• Неверная конфигурация xml парсера.
Техническая ошибка на стороне Softline Ecommerce.

Пример:

<?xml version="1.0" encoding="UTF-8"?>
        <response>
            <link></link>
            <error><![CDATA[Указанная валюта не поддерживается]]></error>
        </response>

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

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

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

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

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

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

Схема работы

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

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

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

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

  • Срок действия лицензии продукта по разному определяется для родительского и дочернего заказа:
    • В родительском заказе срок действия лицензии передается в запросе к Сервису (period).
      Это позволяет задавать разный срок действия для одного и тоже же продукта в каждом запросе.
    • В дочернем заказе срок действия лицензии определяется из настроек на стороне Softline Ecommerce и является одинаковым для всех подписок и продуктов Партнера.
    • Через отдельный Сервис управления подписками можно изменять дату окончания действия лицензии каждой конкретной Подписки.
  • Стоимость продления передается в запросе к Сервису (subscription_product_price) и далее используется на протяжении всей жизни Подписки. То есть в каждом дочернем заказе будет одинаковая стоимость продления.
    Изменить стоимость можно через отдельный Сервис управления подписками.
  • Название продукта продления передается в запросе к Сервису (subscription_product_name) и далее используется на протяжении всей жизни Подписки. То есть в каждом дочернем заказе будет одинаковое название продукта продления.
    Изменить название можно через отдельный Сервис управления подписками.

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

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

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

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

Пример заполненных значений в Postman:

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

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