Project

General

Profile

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

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

Версия 1.10 (18.06.21)

Основные понятия

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

Родительский заказ – это заказ, который был оформлен Покупателем, оплачен им вручную, и по которому была создана подписка.

Дочерний заказ – заказ на продление, который создаётся автоматически перед окончанием срока действия лицензии на основании родительского заказа.

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

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

Сервис предназначен для управления подписками Партнера на стороне Softline Ecommerce с помощью следующих запросов:

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

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"?>
<Request>
   <SubscriptionId>111111_222222</SubscriptionId>
   <Request>get_subscription_info</Request>
</Request>

Необходимо:

  1. Составить строку для генерации токена:
    secret0!test<?xml version="1.0" encoding="UTF-8"?><Request><SubscriptionId>111111_222222</SubscriptionId><Request>get_subscription_info</Request></Request>

     
  2. Сгенерировать токен md5-hash от полученной строки, например, с помощью сервиса https://www.md5hashgenerator.com.
     
  3. Передать в body параметры:
Параметр Значение
id test
token f769835324bf0dbe1613b19ac600ee0c
query
<?xml version="1.0" encoding="UTF-8"?><Request><SubscriptionId>111111_222222</SubscriptionId><Request>get_subscription_info</Request></Request>

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

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

Запрос позволяет получить информацию о существующей подписке на стороне Softline Ecommerce.

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

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

Параметр Обязательность Описание
SubscriptionId Да Идентификатор подписки в системе Softline Ecommerce.
Request Да Действие с подпиской:
get_subscription_info - получить информацию о подписке.

Пример:

<?xml version="1.0" encoding="UTF-8"?>
<Request>
   <SubscriptionId>111111_222222</SubscriptionId>
   <Request>get_subscription_info</Request>
</Request>

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

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

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

В ответ возвращается код HTTP/1.1 200 OK и данные подписки.

Параметр Описание
SubscriptionData Данные о подписке.
SubscriptionId Идентификатор подписки.
Status Статус подписки.
Возможные значения:
new – подписка создана, но не оплачена (родительский заказ не оплачен);
active – подписка оплачена, ожидается автоматическое создание следующего дочернего заказа;
not_paid – дочерний заказ создан, но пока не оплачен;
cancelled – продление отменено;
done – подписка завершена (автоматическое продление невозможно, технический статус).
InitialOrder Данные родительского заказа.
OrderId Идентификатор родительского заказа в системе Softline Ecommerce.
CreateDate Дата оплаты родительского заказа.
Формат даты: [год]-[месяц]-[день]
Часовой пояс: UTC+3:00
NextRenewalDate Дата следующего платежа.
Формат даты: [год]-[месяц]-[день]
Часовой пояс: UTC+3:00
NextCreateDate Дата, когда будет создан следующий дочерний заказ.
Формат даты: [год]-[месяц]-[день]
Часовой пояс: UTC+3:00
Interval Срок действия лицензии.
Формат: ISO 8601 code: P[число][ед.измерения].
Поддерживаемые единицы измерения: Y - год, M - месяц, D - день
Например, "P1Y" соответствует сроку "1 год".
URL Ссылка на страницу родительского заказа (содержит блок управления подпиской).
Пример
<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <SubscriptionId>111111_222222</SubscriptionId>
   <Request>get_subscription_info</Request>
   <Error>0</Error>
   <SubscriptionData>
      <InitialOrder>
         <OrderId>111111</OrderId>
         <CreateDate>2016-05-25</CreateDate>
      </InitialOrder>
      <Status>active</Status>
      <NextRenewalDate>2016-05-23</NextRenewalDate>
      <NextCreateDate>2016-05-09</NextCreateDate>
      <Interval>P1Y</Interval>
      <URL>https://basket.allsoft.ru/order/status/6737016/ebbfa9b62cb2269fdd4428a564a2b0ef</URL>
   </SubscriptionData>
</Response>

Ошибки

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

Если действие с подпиской невозможно выполнить, то вернется код HTTP/1.1 200 OK и xml с описанием ошибки:

Error ErrorMessage Описание
10 Subscription not found Подписка с этим идентификатором не найдена.
40 Could not fulfill the request with a subscription Не удалось выполнить запрос (технические проблемы, проблемы на стороне Softline Ecommerce).
Пример
<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <SubscriptionId>111111_222222</SubscriptionId>
   <Request>get_subscription_info</Request>
   <Error>10</Error>
   <ErrorMessage>Subscription not found</ErrorMessage>
</Response>

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

Запрос позволяет изменить название и стоимость продукта продления для определенной подписки.
После изменения, указанные название и стоимость будут действовать на всем протяжении жизни подписки, включая последующие дочерние заказы, или пока не будут переданы новые значения.
Влияет только на определенную подписку. Название продукта продления в каталоге и его стоимость - не изменяются.

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

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

Параметр Обязательность Описание
SubscriptionId Да Идентификатор подписки в системе Softline Ecommerce.
Request Да Действие с подпиской:
modify_subscription_info - изменить данные о продлении подписки.
RenewalProductPrice Стоимость продления в валюте заказа.
Формат: Число с 2 десятичными знаками, разделитель - точка.
RenewalProductPrice > 0
RenewalProductPriceCurrency Да, если передается
RenewalProductPrice
Код валюты заказа.
Формат: ISO 4217.
RenewalProductName Наименование продукта для продления подписки.
Формат: Текст без тегов HTML.
Пример
<?xml version="1.0" encoding="UTF-8"?>
<Request>
   <SubscriptionId>111111_222222</SubscriptionId>
   <Request>modify_subscription_info</Request>
   <RenewalProductPrice>774.00</RenewalProductPrice>
   <RenewalProductPriceCurrency>RUB</RenewalProductPriceCurrency>
   <RenewalProductName>Subscription for 3 months</RenewalProductName>
</Request>

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

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

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

В ответ возвращается код HTTP/1.1 200 OK и данные подписки (идентификатор, название запроса, количество ошибок равное нулю).

Пример
<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <SubscriptionId>111111_222222</SubscriptionId>
   <Request>modify_subscription_info</Request>
   <Error>0</Error>
</Response>

Ошибки

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

Если действие с подпиской невозможно выполнить, то вернется код ошибки HTTP/1.1 200 OK и xml с описанием ошибки:

Error ErrorMessage Описание
10 Subscription not found Подписка с этим идентификатором не найдена.
20 Subscription status is cancelled Запрос не может быть выполнен, так как подписка отменена.
25 Subscription status is not_paid Запрос не может быть выполнен, потому что следующий заказ создан, ожидается автоматический платеж.
26 Subscription status is done Запрос не может быть выполнен, так как подписка завершена.
40 Could not fulfill the request with a subscription Не удалось выполнить запрос (технические проблемы, проблемы на стороне Softline Ecommerce).
50 Invalid data format Значение RenewalProductPrice или RenewalProductName не соответствует заданному формату.
60 Invalid order currency Возможные причины:
• Значение RenewalProductPriceCurrency не совпало с валютой родительского заказа.
• Значение RenewalProductPriceCurrency не было передано вместе с RenewalProductPrice;
• Неверный формат RenewalProductPriceCurrency.
Пример
<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <SubscriptionId>111111_222222</SubscriptionId>
   <Request>cancel_subscription</Request>
   <Error>20</Error>
   <ErrorMessage>Subscription status is cancelled</ErrorMessage>
</Response>

Изменение даты окончания срока действия лицензии

Запрос позволяет изменить дату окончания срока действия определенной лицензии на стороне Softline Ecommerce.
Влияет только на один (следующий) дочерний заказ. На основании новой даты обновляются дата создания следующего дочернего заказа и дата его оплаты.

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

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

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

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

Параметр Обязательность Описание
SubscriptionId Да Идентификатор подписки в системе Softline Ecommerce.
Request Да Действие:
modify_renewal_date - изменить дату окончания срока действия лицензии.
RenewalDate Да Дата окончания срока действия лицензии.
Формат: [год]-[месяц]-[день].
Часовой пояс: UTC+3:00
Пример
<?xml version="1.0" encoding="UTF-8"?>
<Request>
   <SubscriptionId>111111_222222</SubscriptionId>
   <Request>modify_renewal_date</Request>
   <RenewalDate>2025-01-17</RenewalDate>
</Request>

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

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

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

В ответ возвращается код HTTP/1.1 200 OK и данные подписки (идентификатор, название запроса, количество ошибок равное нулю).

Пример
<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <SubscriptionId>111111_222222</SubscriptionId>
   <Request>modify_renewal_date</Request>
   <Error>0</Error>
</Response>

Ошибки

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

Если действие с подпиской невозможно выполнить, то вернется код ошибки HTTP/1.1 200 OK и xml с описанием ошибки:

Error ErrorMessage Описание
10 Subscription not found Подписка с этим идентификатором не найдена.
20 Subscription status is cancelled Запрос не может быть выполнен, так как подписка отменена.
30 You can not update the expiration date of the license Возможные причины:
• Для подписки существует дочерний заказ, который не был оплачен. Нельзя изменить дату окончания срока действия лицензии, так как покупатель уже получил уведомление о предстоящей дате списания средств.
• Полученная дата создания следующего дочернего заказа и рассчитанные даты повторных попыток меньше или равны текущий. Дочерний заказ не может быть создан.
40 Could not fulfill the request with a subscription Не удалось выполнить запрос (технические проблемы, проблемы на стороне Softline Ecommerce).
Пример
<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <SubscriptionId>111111_222222</SubscriptionId>
   <Request>modify_renewal_date</Request>
   <Error>10</Error>
   <ErrorMessage>Subscription not found</ErrorMessage>
</Response>

Отмена подписки

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

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

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

Параметр Обязательность Описание
SubscriptionId Да Идентификатор подписки в системе Softline Ecommerce.
Request Да Действие с подпиской:
cancel_subscription - отменить подписку.
SuppressCustomerNotification Запрещать или нет отправку письма покупателю об отмене подписки:
true - отправка письма запрещена, письмо не будет отправлено.
false - отправка письма разрешена.
 
По умолчанию false.
Пример
<?xml version="1.0" encoding="UTF-8"?>
<Request>
   <SubscriptionId>111111_222222</SubscriptionId>
   <Request>cancel_subscription</Request>
   <SuppressCustomerNotification>false</SuppressCustomerNotification>
</Request>

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

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

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

В ответ возвращается код HTTP/1.1 200 OK и данные подписки (идентификатор, название запроса, количество ошибок равное нулю).

Пример
<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <SubscriptionId>111111_222222</SubscriptionId>
   <Request>cancel_subscription</Request>
   <Error>0</Error>
</Response>

Ошибки

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

Если действие с подпиской невозможно выполнить, то вернется код ошибки HTTP/1.1 200 OK и xml с описанием ошибки:

Error ErrorMessage Описание
10 Subscription not found Подписка с этим идентификатором не найдена.
20 Subscription status is cancelled Запрос не может быть выполнен, так как подписка отменена.
40 Could not fulfill the request with a subscription Не удалось выполнить запрос (технические проблемы, проблемы на стороне Softline Ecommerce).
Пример
<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <SubscriptionId>111111_222222</SubscriptionId>
   <Request>cancel_subscription</Request>
   <Error>10</Error>
   <ErrorMessage>Subscription not found</ErrorMessage>
</Response>

Восстановление подписки

Запрос позволяет восстановить подписку на стороне Softline Ecommerce. Для успешного выполнения запроса восстановление должно быть доступно для подписки.
Подробнее об отмене и возобновлении подписки см. в отдельной документации.

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

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

Параметр Обязательность Описание
SubscriptionId Да Идентификатор подписки в системе Softline Ecommerce.
Request Да Действие с подпиской:
reactivate_subscription - восстановить подписку.
SuppressCustomerNotification Запрещать или нет отправку письма Покупателю о возобновлении подписки:
true - отправка письма запрещена, письмо не будет отправлено.
false - отправка письма разрешена.
 
По умолчанию false.
Пример
<?xml version="1.0" encoding="UTF-8"?>
<Request>
   <SubscriptionId>111111_222222</SubscriptionId>
   <Request>reactivate_subscription</Request>
   <SuppressCustomerNotification>false</SuppressCustomerNotification>
</Request>

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

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

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

В ответ возвращается код HTTP/1.1 200 OK и данные подписки (идентификатор, название запроса, количество ошибок равное нулю).

Пример
<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <SubscriptionId>111111_222222</SubscriptionId>
   <Request>reactivate_subscription</Request>
   <Error>0</Error>
</Response>

Ошибки

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

Если действие с подпиской невозможно выполнить, то вернется код ошибки HTTP/1.1 200 OK и xml с описанием ошибки:

Error ErrorMessage Описание
10 Subscription not found Подписка с этим идентификатором не найдена.
40 Could not fulfill the request with a subscription Не удалось выполнить запрос (технические проблемы, проблемы на стороне Softline Ecommerce).
70 The subscription cannot be restored Запрос не может быть выполнен, так как для подписки не доступно восстановление.
Пример
<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <SubscriptionId>111111_222222</SubscriptionId>
   <Request>reactivate_subscription</Request>
   <Error>10</Error>
   <ErrorMessage>Subscription not found</ErrorMessage>
</Response>

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

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

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

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