Project

General

Profile

Сервис для получения информации по заказам и создания заявки на возврат

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

Версия 1.5 (09.07.2021)
  • Вместо данных покупателя в заказе может выводиться deleted, если покупатель воспользовался правом на удаление персональных данных, подробнее.

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

Функции сервиса:

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

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

Softline Ecommerce предоставляет данные для подключения:

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

  • Тип запроса: POST,
  • Формат передачи данных: xml.

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

Параметр Значение
id Идентификатор Партнёра
token md5-hash от 'secret key + id + query',
Значения указываются в данной последовательности, не разделяются пробелами или другими символами.
query - указывается как строка без переносов и пробелов.
Подробнее см. пример.
query Содержит параметры запроса, преобразованные в одну строку (в том же формате, который был использован для генерации token).
<?xml version="1.0" encoding="UTF-8"?><Request>…</Request>

(!) Обратите внимание! Далее в описании приведены только примеры query (id и token передаются в каждом запросе по описанному выше правилу). В примерах параметры query приведены в структурированном виде, для использовании их в запросе необходимо преобразовать query в одну строку.

Пример тестового запроса

Допустим, данные для подключения:
  • id = test,
  • secret key = secret0!
Чтобы сделать запрос вида:
<?xml version="1.0" encoding="UTF-8"?>
<parameters>
  <filter>
      <id>
        <item>3562432</item>
        <item>4944728</item>
      </id>
  </filter>
</parameters>

Необходимо:

  1. составить строку для генерации токена.
    secret0!test<?xml version="1.0" encoding="UTF-8"?><parameters><filter><id><item>3562432</item><item>4944728</item></id></filter></parameters>
  2. сгенерировать токен md5-hash от полученной строки,
    например, с помощью сервиса https://www.md5hashgenerator.com
  3. передать в body параметры:
    id test
    token 09bf461e10e295bf6c90f94f3cb9162d
    query
    <?xml version="1.0" encoding="UTF-8"?><parameters><filter><id><item>3562432</item><item>4944728</item></id></filter></parameters>

См. также Примеры запросов в Postman.

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

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

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

Перечислены только параметры, которые передаются в query, см. полное описание запроса.

Параметр Обязательность Описание
parameters Да Содержит параметры запроса.
filter Да Список критериев, по которым должны быть выбраны заказы.
Поиск осуществляется по пересечению переданных критериев. Каждый критерий состоит из названия (см. далее) и значения, по которому должен быть выполнен поиск. ​
Возможные названия критериев поиска:
(!) По умолчанию доступен поиск только по номеру заказа (id) и email покупателя (user_email).
Если необходимо осуществлять запрос по другим параметрам, обратитесь к своему аккаунт менеджеру.
id Должен быть передан хотя бы один вариант id заказа
create_date Дата и время создания заказа (например, 2015-11-01 13:01:01). Часовой пояс: UTC+3.
Период в запросе указать нельзя, можно только указать несколько дат в качестве значений (item).
pay_date Дата и время оплаты заказа (например, 2015-11-01 13:01:01). Часовой пояс: UTC+3.
Период в запросе указать нельзя, можно только указать несколько дат в качестве значений (item).
order_status Статус заказа:
• 0 – создан,
• 2 – оплачен,
• 9 – удалён.
zone Зона, в которой сделан заказ (например: RU, UA, BY).
payment_system_id id выбранной платежной системы.
user_email E-mail пользователя.
Значения критериев:
item Да Значение критерия, по которому осуществляется поиск.
Может быть задано несколько значений, в этом случае поиск осуществляется по всем переданным значениям.
Если передано несколько filter, в которых есть несколько item, то каждый заказ в результатах поиска должен соответствовать хотя бы одному значению (item) для каждого переданного критерия (filter). См. примеры далее.
limit Настройки выдачи результатов.
offset Сдвиг: на какое количество записей (заказов) нужно сдвинуть выдачу результатов.
• Если не передано или равно 0, то список придет с 1-го найденного заказа.
• Если указать, например, 1, то список придет, начиная со 2-го заказа.
• Если указать, например, 10, то список придет, начиная с 11-го заказа.
 
Заказы в результатах поиска сортируются по номеру заказа от большего номера к меньшему номеру.
limit Количество записей (заказов), которое должно прийти.
Если не передано, то в ответе вернутся первые 100 найденных заказов.
Помимо этого каждый ответ содержит общее количество найденных заказов.

Примеры запросов для поиска заказов по e-mail покупателя и номеру заказа

Пример 1.
<?xml version="1.0" encoding="UTF-8"?>
<parameters>
 ​<filter>
     ​<user_email>
       ​<item>primer@ekf.ru</item>
       ​<item>primer2@ekf.ru</item>
     ​</user_email>
 ​</filter>
</parameters>
Пример 2.
<?xml version="1.0" encoding="UTF-8"?>
<parameters>
 ​<filter>
     ​<id>
       ​<item>3562432</item>
       ​<item>4944728</item>
     ​</id>
 ​</filter>
</parameters>
Пример 3.
<?xml version="1.0" encoding="UTF-8"?>
<parameters>
 ​<filter>
     ​<id>
       ​<item>3562432</item>
       ​<item>4944728</item>
     ​</id>
     ​<user_email>
       ​<item>primer@ekf.ru</item>
     ​</user_email>
 ​</filter>
</parameters>
Ожидаемый ответ
Все заказы, оформленные на primer@ekf.ru или primer2@ekf.ru. Заказы 3562432 и 4944728. Заказы 3562432 и 4944728, если они были оформлены на primer@ekf.ru.
Если заказы были оформлены на другой e-mail, то вернется пустой ответ.

Примеры запросов, с выдачей списка заказов по 10 записей

<?xml version="1.0" encoding="UTF-8"?>
<parameters>
  <filter>
      <user_email>
        <item>primer@ekf.ru</item>        
        <item>primer2@ekf.ru</item>
      </user_email>
  </filter>
  <limit>
      <offset>0</offset>
      <limit>10</limit>
  </limit>
</parameters>
<?xml version="1.0" encoding="UTF-8"?>
<parameters>
  <filter>
      <user_email>
        <item>primer@ekf.ru</item>
        <item>primer2@ekf.ru</item>
      </user_email>
  </filter>
  <limit>
      <offset>10</offset>
      <limit>10</limit>
  </limit>
</parameters>
<?xml version="1.0" encoding="UTF-8"?>
<parameters>
  <filter>
      <user_email>
        <item>primer@ekf.ru</item>
        <item>primer2@ekf.ru</item>
      </user_email>
  </filter>
  <limit>
      <offset>20</offset>
      <limit>10</limit>
  </limit>
</parameters>
Ожидаемый ответ
Заказы с 1 по 10, отвечающие условиям поиска. Заказы с 11 по 20, отвечающие условиям поиска. Заказы с 21 по 30, отвечающие условиям поиска.
См. также:

Пример php-кода запроса

$sUrl = 'https://ws-public-secured.allsoft.ru/SlOuter_Order/index.php';
$sSalt = 'СЕКРЕТНЫЙ_КЛЮЧ';
$sClient = 'ИДЕНТИФИКАТОР_ПАРТНЕРА';
$sQuery = '<?xml version="1.0" encoding="UTF-8"?>
<parameters>
  <filter>
      <user_email>
        <item>primer@ekf.ru</item>
        <item>primer2@ekf.ru</item>
      </user_email>
  </filter>
</parameters>';
$sPemFile = 'ПУТЬ_К_PEM_ФАЙЛУ';

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $sUrl);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, 'id=' . $sClient . '&token=' . md5($sSalt . $sClient . $sQuery) . '&query=' . urlencode($sQuery));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($ch, CURLOPT_SSLCERT, $sPemFile);

echo curl_exec($ch);

curl_close($ch);

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

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

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

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

Параметр Описание Пример данных
orders Список найденных заказов.
count_all Общее количество заказов, найденных согласно критериям
limit Количество заказов в выдаче
offset Сдвиг: на какое количество записей по списку заказов сдвинута выдача. Список заказов отсортирован от большего id к меньшему.
order Информация по каждому найденному заказу
id id заказа 1111111
user_id id пользователя, которому принадлежит заказ 2222222
create_date Дата создания заказа в формате YmdHis!
Часовой пояс: UTC+3
20150516131827
pay_date Дата оплаты заказа 2013-05-20 12:46:27
order_status Статус заказа:
• 0 – создан,
• 2 – оплачен,
• 9 – удалён.
0
order_status_name Словесное описание статуса заказа для отображения пользователю Заказ не оплачен.
zone Зона, в которой сделан заказ.
Например: RU, UA, BY
RU
country Страна покупателя, если заполнена Argentina
currency_id id валюты, в которой создан заказ и в которой записаны цены 1
currency_name Название валюты руб.
market_id id витрины, на которой сделан заказ 100031
name Наименование заказа ALLSOFT-1111111
total_price Полная цена заказа в валюте заказа.
Учитывается НДС, скидка, цена доставки и т.д.
2787.2
nds_sum Сумма НДС в валюте заказа 0
delivery_price_valut Стоимость доставки в валюте заказа 200
additional_info Дополнительная информация, комментарий к заказу Время доставки заказа должно быть только с 9 часов до 17 часов.
payment_system_id id выбранной платежной системы 7
payment_system_name Наименование выбранной платежной системы.
Если для данной корзины указано кастомное название - то передается кастомное.
Банковский платеж (для юр. лиц и ИП)
detail_url Ссылка на оплату заказа.
Передается в случае, если статус заказа = 0.
https://[адрес_корзины]/order/123123123123123123sdfsdf
cancel_url Ссылка на отмену заказа.
Передается в случае, если статус заказа = 0.
https://[адрес_корзины]/order/1231sdfsdfdsf3123123sdfsdf
Покупатель
Вместо данных покупателя в заказе может выводиться deleted, если покупатель воспользовался правом на удаление персональных данных, подробнее.
user_name Имя пользователя Иван
user_surname Фамилия Петров
user_email E-mail
user_zipcode Почтовый индекс пользователя 117648
delivery_address Адрес доставки
user_region Регион пользователя Москва
user_city Город Москва (в пределах МКАД)
user_street Улица мкр-он Северное Чертаново
user_house Дом 1
user_building Корпус 111
user_structure Строение
user_doorway Подъезд
user_doorway_code Код подъезда
user_phone Телефон пользователя, может быть два телефона через запятую +71111111111
company_name Наименование компании ООО "Диагностика"
user_apartment Номер офиса или квартиры ООО "Диагностика"
user_apartment_type Тип - kvartira или ofis kvartira
actual_address Фактический адрес 117648, г. Москва, мкр-он Северное Чертаново, дом 1, корп. 111
juridical_address Юридический адрес 117648, г. Москва, мкр-он Северное Чертаново, дом 1, корп. 111
company_rnn RU: пусто,
UA: ИНН
BY: ОКПО
user_fax Факс пользователя +71111111112
user_inn ИНН 7777999999
user_kpp КПП 777777777
user_rnn RU: пусто,
UA: пусто,
BY: УНН
nds_cert_number (UA) Номер свидетельства плательщика НДС
Дополнительные параметры заказа
additional_parameters Содержит список дополнительных параметров заказа, если они есть.
Сохранение дополнительных параметров для заказа индивидуально для корзины
key name Название дополнительного параметра ip_country_code
value Значение дополнительного параметра ru
Состав заказа
order_items Список позиций заказа
order_item Позиция заказа
price_group_id ИД ценовой группы 3333333
product_version_boxw eight Тип:
• 1- коробочная версия,
• 0 – электронная версия.
1.00
quantity Количество заказанной версии продукта 1
price_with_discount Стоимость позиции со скидкой в валюте заказа 2587.20
nds_percent Процент НДС 0.00
discount_percent % скидки 0.00
custom_product_name Пользовательское название продукта Продукт c лицензией на 1 год
key Ключ XXXX-54MU-PEQA-XXXX
Данные по подписке, поля передаются (добавляются в xml) только если оформлена подписка
subscription_id ID подписки на стороне Softline Ecommerce в формате [id родительского заказа]_[ID позиции в родительском заказе] 10908690_11222222
subscription_type Тип подписки:
ar - если на позицию есть подписка с автопродлением лицензии (AR),
fake - если на позицию есть PMR подписка.
Подробнее о видах подписки см. в отдельной документации.
ar
subscription_status Статус подписки:
active - оплачена, ожидаем следующее продление,
not_paid - инициировано продление, которое будет оплачено в указанную дату (после оплаты статус подписки сменится на active),
cancelled - продление отменено.
cancelled

Пример:

<?xml version="1.0" encoding="UTF-8"?>
<orders count_all="584" limit="1" offset="1">
    <order>
        <id>1111111</id>
        <user_id>2222222</user_id>
        <create_date>20150516131827</create_date>
        <pay_date>2013-05-20 12:46:27</pay_date>
        <order_status>0</order_status>
        <order_status_name>Заказ не оплачен.</order_status_name>
        <zone>RU</zone>
        <country/>
        <currency_id>1</currency_id>
        <currency_name>руб.</currency_name>
        <market_id>100031</market_id>
        <name>ALLSOFT-1111111</name>
        <total_price>2787.2</total_price>
        <nds_sum>0</nds_sum>
        <delivery_price_valut>200</delivery_price_valut>
        <additional_info>Время доставки заказа должно быть только с 9 часов до 17 часов.</additional_info>
        <payment_system_id>7</payment_system_id>
        <payment_system_name>Банковский платеж (для юр. лиц и ИП)</payment_system_name>
        <detail_url>https://пример_detail</detail_url>
        <cancel_url>https://пример_cancel</cancel_url>
        <user_name>Алексей</user_name>
        <user_surname>Артеменко</user_surname>
        <user_email>primer@ekf.ru</user_email>
        <user_zipcode>117648</user_zipcode>
        <delivery_address />
        <user_region>Москва</user_region>
        <user_city>Москва (в пределах МКАД)</user_city>
        <user_street>мкр-он Северное Чертаново</user_street>
        <user_house>1</user_house>
        <user_building>111</user_building>
        <user_structure />
        <user_doorway />
        <user_doorway_code />
        <user_phone>+71111111111</user_phone>
        <company_name>ООО «ЕКФ-диагностика»</company_name>
        <user_apartment>ООО «ЕКФ-диагностика»</user_apartment>
        <user_apartment_type>kvartira</user_apartment_type>
        <actual_address>117648, г. Москва мкр-он Северное Чертаново, дом 1, корп. 111</actual_address>
        <juridical_address>117648, г. Москва мкр-он Северное Чертаново, дом 1, корп. 111</juridical_address>
        <company_rnn />
        <user_fax>+71111111112</user_fax>
        <user_inn>7777999999</user_inn>
        <user_kpp>777777777</user_kpp>
        <user_rnn />
        <nds_cert_number />
        <additional_parameters>
            <key name="ip_country_code">
                <value>ru</value>
            </key>
            <key name="referer1">
                <value>remind renew redirect (1408972944)</value>
            </key>
        </additional_parameters>
        <order_items>
            <order_item>
                <price_group_id>3333333</price_group_id>
                <product_version_boxweight>1.00</product_version_boxweight>
                <quantity>1</quantity>
                <price_with_discount>2587.20</price_with_discount>
                <nds_percent>0.00</nds_percent>
                <discount_percent>0.00</discount_percent>
                <custom_product_name>Продукт c лицензией на 1 год</custom_product_name>
                <key>XXXX-54MU-PEQA-XXXX</key>
                <subscription_id>10908690_11985049</subscription_id>
                <subscription_type>ar</subscription_type>
                <subscription_status>cancelled</subscription_status>
            </order_item>
        </order_items>
    </order>
</orders>

Ошибки

Ошибка Описание
HTTP/1.1 401 Unauthorized Неуспешная авторизация
HTTP/1.1 400 Bad Request Не передано ни одного критерия поиска (filter), или использован недоступный критерий поиска.
HTTP/1.1 500 Request Error Запрос не валиден (ошибка в параметрах), или ошибка на стороне сервера.

Также в ответ может вернуться пустой список найденных заказов и код ответа HTTP/1.1 200 OK:

Ответ Описание
<?xml version="1.0" encoding="UTF-8"?>
<orders count_all="0" limit="100" offset="0"/>
Не найдены заказы (count_all="0") для заданных критериев поиска.
<?xml version="1.0" encoding="UTF-8"?>
<orders count_all="1" limit="100" offset="2"/>
Нет заказов для отображения, так как задан сдвиг, который больше или равен найденному количеству заказов.
В примере задан сдвиг 2 (offset="2"), тогда как всего найден 1 заказ (count_all="1").

Создание заявки на возврат по заказу

Особенности:
  • Возможность создания заявок на возврат подключается по запросу. Обратитесь к своему аккаунт менеджеру для подключения.
  • Один запрос может содержать только одну заявку на возврат.
  • После обработки заявки на стороне Softline Ecommerce заявка закрывается.
    Возможные результаты при закрытии заявки:
    • Выполнен полный возврат;
    • Выполнен частичный возврат;
    • Возврат не выполнен.
  • Для получения информации о закрытии заявок необходимо подключить получение уведомлений.

Запрос сделанный через Сервис равнозначен отправленному через портал для работы с заказами ESupport.

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

Перечислены только параметры, которые передаются в query, см. полное описание запроса.

Параметр Обязательность Описание
parameters.filter.id.item Да Номер заказа, по которому нужно сделать возврат. Передается без префикса.
В одном запросе может быть только 1 заказ. Если значение не передано / не в том формате, то возвращается 400 Bad Request. ​
parameters.action.description Описание причины возврата, особенностей запроса (возврат полный или частичный, возврат или урегулирование спора и т.п.).
Не более 500 символов. Поддерживаются UTF символы.
parameters.action.email Да Email для связи с партнером по заявке на возврат. (!) Это не email покупателя.

Пример:

<?xml version="1.0" encoding="utf-8"?>
<parameters>
  <filter>
    <id>
      <item>3562432</item>
    </id>
  </filter>
  <action type="refund">
  <description>Ошибка при выборе продукта</description>
  <email>primer2@vendor.ru</email>
  </action>
</parameters>
См. также:

Пример php-кода запроса

$sUrl = 'https://ws-public-secured.allsoft.ru/SlOuter_Order/index.php';
$sSalt = 'СЕКРЕТНЫЙ_КЛЮЧ';
$sClient = 'ИДЕНТИФИКАТОР_ПАРТНЕРА';
$sQuery = '<?xml version="1.0" encoding="utf-8"?>
<parameters>
    <filter>
        <id>
            <item>3562432</item>
        </id>
    </filter>
    <action type="refund">
        <description>Ошибка при выборе продукта</description>
        <email>primer2@vendor.ru</email>
    </action>
</parameters>';
$sPemFile = 'ПУТЬ_К_PEM_ФАЙЛУ';

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $sUrl);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, 'id=' . $sClient . '&token=' . md5($sSalt . $sClient . $sQuery) . '&query=' .
urlencode($sQuery));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($ch, CURLOPT_SSLCERT, $sPemFile);

echo curl_exec($ch);

curl_close($ch);

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

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

Если проверка данных в запросе пройдена успешно, то создается заявка на возврат по заказу. По факту создания заявки придет ответ HTTP/1.1 200 OK.

Пример:

<?xml version="1.0" encoding="UTF-8"?>
<response>
   <result>
      <error>0</error>
   </result>
</response>

Ошибки

В случае, если заявка не была создана при обработке запроса, то вернется код ответа HTTP/1.1 200 OK и первая найденная ошибка:

Ошибка Сообщение об ошибке Описание
10 Order not found Заказ с переданным номером не был найден в системе.
20 Refund for this order is not possible Создание заявки на возврат не доступно для заказа.
30 Refund request already exists for this order Заявка на возврат уже создана для данного заказа.

Пример:

<?xml version="1.0" encoding="UTF-8"?>
<response>
   <result>
      <error>10</error>
      <error_message>Order not found</error_message>
   </result>
</response>

Прочие ошибки:

Код ответа Описание
HTTP/1.1 401 Unauthorized Неуспешная авторизация
HTTP/1.1 400 Bad Request Не передан обязательный параметр, или неверный формат номера заказа, email для связи
HTTP/1.1 500 Request Error Возможные причины ошибки:
• Запрос не валиден (ошибка в параметрах; не переданы необходимые данные и т.п.).
• Ошибка на стороне сервера.
• Прочие ошибки

Уведомление о закрытии заявки на возврат

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

Подключение уведомлений

Партнер должен предоставить:
  • URL сервиса на своей стороне, который будет получать уведомления;
  • Секретный ключ.

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

  • Тип запроса: POST;
  • Формат передачи данных: xml.

Тело запроса:

Параметр Обязательность Описание
token Да md5-хэш от 'secret key + query'
query Да xml с указанными ниже параметрами.
Параметры в xml
request.return Да Содержит параметры уведомления.
order_id Да Номер заказа, по которому сформировано уведомление.
return_status Да Статус возврата:
• full refund completed – Выполнен полный возврат;
• partial refund completed – Выполнен частичный возврат;
• refund failed – Возврат не выполнен.

Пример:

<?xml version="1.0" encoding="UTF-8"?>
<request>
   <return>
      <order_id>536673</order_id>
      <return_status>full refund completed</return_status>
   </return>
</request>

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

На отправленное уведомление Сервис Softline Ecommerce ожидает ответ HTTP/1.1 200 OK.
Если будет получен любой другой код ответа, повторное уведомление отправляться не будет.

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

Скачать коллекцию запросов
Для отправки запросов из коллекции нужно:

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

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

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