Project

General

Profile

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

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

15.04.2021 ‒ Добавлена возможность удалить скидку на какой-либо продукт из купона.
‒ В справочник ошибок добавлено описание ответа: "HTTP/1.1 400 Bad Request. Double BuyLinkID" и ошибка с кодом 17.
‒ Добавлены примеры запросов в Postman.

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

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

Купоны - один из видов скидок на продукты. Для применения скидки необходимо активировать купон в корзине.

Обзор купонов, основные свойства и применение »

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

  • Серия купона - для купонов, состоящих только из серии.
    (!) В запросах, чтобы однозначно идентифицировать такой купон нужно передавать серию купона и пустые теги номеров купона.
  • Серия и Номера купона (от, до) - для купонов состоящих из серии и номера.
  • ID купона (внутренний идентификатор, присваивается на стороне 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>
   <Request>get_list</Request>
      <CouponStartDate>2019-01-10</CouponStartDate>
      <CouponStopDate>2078-10-10</CouponStopDate>
</Request>

Необходимо:

  1. Составить строку для генерации токена:
    secret0!test<?xml version="1.0" encoding="UTF-8"?><Request><Request>get_list</Request><CouponStartDate>2019-01-10</CouponStartDate><CouponStopDate>2078-10-10</CouponStopDate></Request>

     
  2. Сгенерировать токен md5-hash от полученной строки, например, с помощью сервиса https://www.md5hashgenerator.com.
     
  3. Передать в body параметры:
Параметр Значение
id test
token 551eeb201928b6d76b37dfcc4b47b435
query
<?xml version="1.0" encoding="UTF-8"?><Request><Request>get_list</Request><CouponStartDate>2019-01-10</CouponStartDate><CouponStopDate>2078-10-10</CouponStopDate></Request>

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

Получение списка купонов

Запрос get_list предназначен для получения данных по заведенным купонам.
Поиск осуществляется в пересечении параметров, указанных в запросе.

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

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

Параметр Обязательность Описание
Request Да Код запроса = get_list.
Для получения данных по всем заведенным купонам достаточно указать только один параметр Request.
Activity Активность купона:
1 - активный купон,
0 - неактивный купон.
CouponId Идентификатор купона. Cоздается на стороне Softline Ecommerce и возвращается в ответ на любой запрос по купону.
CouponCode Серия купона.
 
Не более 30 символов.
Разрешено: латинские буквы, цифры, тире, подчеркивание, точка.
 
Может быть указана только одна серия.
Для получения данных по всем купонам определенной серии (с любыми номерами или без номеров) необходимо передать только CouponCode (без CouponNumberFrom/Up).
CouponNumberFrom Период номеров купона, в виде:
CouponNumberFrom - начальный номер периода,
CouponNumberUp - последний номер периода.
 
Каждый номер не более 9 символов.
0 < CouponNumberFrom ≤ CouponNumberUp.
 
Передается для купонов, которые применяются по серии и номеру. При заполнении должны быть указаны оба значения (CouponNumberFrom, CouponNumberUp).
Для получения данных по купону, применяемому только по серии, параметры CouponNumberFrom/Up следует передать с пустыми значениями.
CouponNumberUp
CouponStartDate Период, во время которого купон является действующим, в виде:
CouponStartDate - дата начала периода,
CouponStopDate - дата окончания периода.
 
Формат: [год]-[месяц]-[день].
CouponStartDate ≤ CouponStopDate.
 
CouponStopDate
BuyLinkID Идентификатор продукта, на который действует скидка по купону (ID ценовой группы, который также используется в ссылке на покупку).
Может быть указан только один идентификатор.

Примеры:

<?xml version="1.0" encoding="UTF-8"?>
<Request>
   <Request>get_list</Request>
   <CouponCode>PROMO2</CouponCode>
   <CouponNumberFrom>1</CouponNumberFrom>
   <CouponNumberUp>10</CouponNumberUp>
</Request>
<?xml version="1.0" encoding="UTF-8"?>
<Request>
   <Request>get_list</Request>
   <CouponCode>PROMO2</CouponCode>
   <CouponNumberFrom></CouponNumberFrom>
   <CouponNumberUp></CouponNumberUp>
</Request>
<?xml version="1.0" encoding="UTF-8"?>
<Request>
   <Request>get_list</Request>
   <CouponCode>PROMO2</CouponCode>
</Request>
Ожидаемый результат
Купон, применяемый по серии PROMO2 и номерам от 1 до 10. Купон, применяемый только по серии PROMO2. Все купоны (с номерами и без), у которых серия = PROMO2.
<?xml version="1.0" encoding="UTF-8"?>
<Request>
   <Request>get_list</Request>
   <CouponStartDate>2020-01-01</CouponStartDate>
   <CouponStopDate>2021-01-01</CouponStopDate>
</Request>
<?xml version="1.0" encoding="UTF-8"?>
<Request>
   <Request>get_list</Request>
   <BuyLinkID>123456</BuyLinkID>
</Request>
<?xml version="1.0" encoding="UTF-8"?>
<Request>
   <Request>get_list</Request>
   <CouponStartDate>2021-01-01</CouponStartDate>
   <CouponStopDate>2021-01-01</CouponStopDate>
   <BuyLinkID>123456</BuyLinkID>
</Request>
Ожидаемый результат
Все купоны, действующие в периоде с 01.01.2020 по 01.01.2021. Все купоны, действующие когда-либо на продукт с id 123456. Все купоны, действующие на продукт с id 123456 на текущую дату (пример предполагает, что 01.01.2021 является текущей датой).

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

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

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

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

Параметр Обязательность Описание
Criteria Да Данные, по которым осуществлялся поиск.
<...> Да Параметры поиска из запроса.
Coupons Да Список найденных купонов.
Coupon Да Данные купона.
CampaignName Описание купона.
Данное поле является информационным и не используется для идентификации.
CouponId Да Идентификатор купона.
CouponCode Да Серия купона.
CouponNumberFrom Номер купона ОТ.
CouponNumberUp Номер купона ДО.
CouponStartDate Да Дата начала действия купона в формате [год]-[месяц]-[день].
CouponStopDate Да Дата окончания действия купона в формате [год]-[месяц]-[день].
CouponType Да one-time - одноразовый купон,
reusable - многоразовый купон.
CouponDiscountPercent Да Скидка, заданная для купона.
Используется в том случае, если к купону не привязаны продукты, или продукты привязаны, но для них не заданы индивидуальные скидки в купоне.
ExternalCode Код для внешних API. Техническое поле.
IsVisibleToAuthor 1 - отображается в Кабинете разработчика,
0 - не отображается в Кабинете разработчика.
Products Да Список продуктов, к которым привязан купон.
Product Да Данные о скидке по купону.
BuyLinkID Да Идентификатор продукта, к которому можно применить купон (ID ценовой группы, который также используется в ссылке на покупку).
DiscountPercent Да Скидка, заданная для продукта.

Примеры:

Ответ на запрос без дополнительных условий поиска Ответ на запрос по серии купона (CouponCode)
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Criteria>
        <Request>get_list</Request>
    </Criteria>
    <Coupons>
        <Coupon>
            <CouponId>980012</CouponId>
            <CampaignName>PROMORU</CampaignName>
            <CouponCode>PROMO_RU_1</CouponCode>
            <CouponNumberFrom>566544</CouponNumberFrom>
            <CouponNumberUp>566544</CouponNumberUp>
            <CouponStartDate>2020-01-01</CouponStartDate>
            <CouponStopDate>2021-01-01</CouponStopDate>
            <CouponType>reusable</CouponType>
            <CouponDiscountPercent>1.000000</CouponDiscountPercent>
            <ExternalCode>CodPromo1</ExternalCode>
            <Activity>1</Activity>
            <IsVisibleToAuthor>1</IsVisibleToAuthor>
            <Products>
                <Product>
                    <BuyLinkID>1400835</BuyLinkID>
                    <DiscountPercent>45.000000</DiscountPercent>
                </Product>
                <Product>
                    <BuyLinkID>4145393</BuyLinkID>
                    <DiscountPercent>98.000200</DiscountPercent>
                </Product>
            </Products>
        </Coupon>
        <Coupon>
            <CouponId>980013</CouponId>
            <CampaignName>PROMORU</CampaignName>
            <CouponCode>PROMO_RU_2</CouponCode>
            <CouponNumberFrom>537066</CouponNumberFrom>
            <CouponNumberUp>537066</CouponNumberUp>
            <CouponStartDate>2020-01-01</CouponStartDate>
            <CouponStopDate>2021-01-01</CouponStopDate>
            <CouponType>one-time</CouponType>
            <CouponDiscountPercent>1.000000</CouponDiscountPercent>
            <ExternalCode>TESTPromo1</ExternalCode>
            <Activity>0</Activity>
            <IsVisibleToAuthor>0</IsVisibleToAuthor>
            <Products>
                <Product>
                    <BuyLinkID>4614176</BuyLinkID>
                    <DiscountPercent>80.645161</DiscountPercent>
                </Product>
            </Products>
        </Coupon>
    </Coupons>
</Response>
<Response>
    <Criteria>
        <Request>get_list</Request>
        <CouponCode>PROMO_RU_1</CouponCode>
    </Criteria>
    <Coupons>
        <Coupon>
            <CouponId>980012</CouponId>
            <CampaignName>PROMORU</CampaignName>
            <CouponCode>PROMO_RU_1</CouponCode>
            <CouponNumberFrom>566544</CouponNumberFrom>
            <CouponNumberUp>566544</CouponNumberUp>
            <CouponStartDate>2020-01-01</CouponStartDate>
            <CouponStopDate>2021-01-01</CouponStopDate>
            <CouponType>reusable</CouponType>
            <CouponDiscountPercent>1.000000</CouponDiscountPercent>
            <ExternalCode>CodPromo1</ExternalCode>
            <Activity>1</Activity>
            <IsVisibleToAuthor>1</IsVisibleToAuthor>
            <Products>
                <Product>
                    <BuyLinkID>1400835</BuyLinkID>
                    <DiscountPercent>45.000000</DiscountPercent>
                </Product>
                <Product>
                    <BuyLinkID>4145393</BuyLinkID>
                    <DiscountPercent>98.000200</DiscountPercent>
                </Product>
            </Products>
        </Coupon>
    </Coupons>
</Response>

Ошибки

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

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

<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <Result />
</Response>

Действия с купонами

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

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

Параметр Обязательность Описание
create delete update replace
Request Да Да Да Да Действие, которое необходимо выполнить по запросу:
create - создать купон,
delete - удалить купон,
update - обновить купон,
replace - заменить купоны.
Coupon Да Да Да Да Контейнер с данными купона, для которого выполняется действие.
  CampaignName Не используется Описание купона. Информационный параметр, не используется для идентификации.
Activity Не используется Активность купона. Покупатель может применить только активный купон.
1 - активный купон;
0 - неактивный купон.
 
Если параметр не передан, то:
• При запросах create и replace будет создан активный купон,
• При запросе update активность купона не изменится.
CouponId Не используется Чтобы удалить определенный купон, должен быть передан один из вариантов идентификационных данных купона.
 
Чтобы удалить все купоны серии, нужно передать только серию (CouponCode).
Должен быть передан один из вариантов идентификационных данных купона. Не используется Идентификатор купона.
Создается на стороне Softline Ecommerce и возвращается в ответ на любой запрос по купону.
CouponCode Да Да Серия купона. У каждого купона может быть только одна серия.
Не более 30 символов.
Допустимы латинские буквы, цифры, тире, подчеркивание, точка.
CouponNumberFrom Период номеров купона. Заполняется для купонов, которые применяются по серии и номеру.
CouponNumberFrom - начальный номер периода (ОТ),
CouponNumberUp - последний номер периода (ДО).
 
Не более 9 символов.
0 < CouponNumberFrom ≤ CouponNumberUp.
При заполнении должны быть указаны оба значения.
CouponNumberUp
CouponStartDate Не используется Период действия купона:
CouponStartDate - дата начала действия купона (ОТ),
CouponStopDate - дата окончания действия купона (ДО).
 
Формат: [год]-[месяц]-[день].
Если CouponStartDate не передана, то в купоне будет указана текущая дата.
Если CouponStopDate не передана, то в купоне будет указана текущая дата + 10 лет.
Если переданы обе даты, то CouponStartDate ≤ CouponStopDate.
CouponStopDate Не используется
CouponType Не используется Тип купона:
one-time - одноразовый купон;
reusable - многоразовый купон.
 
Если значение не указать, то будет создан многоразовый купон.
ExternalCode Не используется Код для внешних API. Техническое поле.
Допустимо: латинские буквы и буквы кириллицы (заглавные и строчные), цифры и символы.
IsVisibleToAuthor Не используется Признак отображения купона в разделе Скидочные купоны в Кабинете разработчика.
1 - отображается,
0 - не отображается.
Product Да Не используется Если контейнер не передан, то данные продукта не будут обновлены Да Контейнер со списком продуктов, на которые купон будет действовать.
Должен содержать один из вариантов тегов, в зависимости от способа расчета скидки.
Вариант содержания 1: для расчета процента скидки от окончательной стоимости продукта.
  BuyLinkID Да Не используется Да, если передан контейнер <product> Да Идентификатор продукта, к которому можно применить купон (ID ценовой группы, который также используется в ссылке на покупку).
Zone Не используется Код страны в формате ISO 3166-1 alpha-2 (например, RU, UA).
Параметр Zone использовался в старых версиях API. В новых интеграциях использовать не нужно.
Если код передан, то он должен соответствовать коду валюты, в которой указана цена со скидкой.
Currency Да Не используется Да, если передан контейнер <product> Да Код валюты, в которой указана цена со скидкой.
 
Буквенный код в формате ISO 4217 (например, RUB, UAH).
(!) Важно! Должна быть использована та же валюта, в которой цена задана в каталоге (даже если покупатель в корзине видит другую валюту заказа):
Если в каталоге цена задана в единых ценах - то указывается валюта базовой цены.
Если в каталоге цена задана региональных ценах - то указывается валюта цены в регионе, в котором должен быть применен купон.
StreetPrice Да Не используется Да, если передан контейнер <product> Да Цена со скидкой - окончательная стоимость продукта после применения купона.
До двух знаков после запятой, разделитель - точка.
Вариант содержания 2: для скидки в виде процента
  BuyLinkID Да Не используется Да, если передан контейнер <product> Да Идентификатор продукта, к которому можно применить купон (ID ценовой группы, который также используется в ссылке на покупку).
CouponDiscountPercent Да Не используется Да, если передан контейнер <product> Да Скидка на продукт в процентах.
 
Для того, чтобы назначить скидку необходимо указать число:
0 < CouponDiscountPercent < 100
Формат: до 6 знаков после запятой, разделитель - точка.
 
Для удаления привязки продукта к купону:
Необходимо передать значение <CouponDiscountPercent xsi:nil="true"/> Подробнее.

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

Для создания купонов предназначен запрос create.

(!) Один и тот же купон указывается в запросе только один раз, в противном случае:
  • Купон будет создан на основе первого блока;
  • Остальные блоки вернутся с указанием кода ошибки 30.

Пример:

<?xml version="1.0" encoding="UTF-8"?>
<Request>
   <Request>create</Request>
   <Coupon>
      <Activity>1</Activity>
      <CampaignName>PROMORU</CampaignName>
      <CouponCode>PROMO_RU_1</CouponCode>
      <CouponNumberFrom>566544</CouponNumberFrom>
      <CouponNumberUp>566544</CouponNumberUp>
      <CouponStartDate>2019-08-01</CouponStartDate>
      <CouponStopDate>2019-08-15</CouponStopDate>
      <CouponType>reusable</CouponType>
      <ExternalCode>CodPromo1</ExternalCode>
      <Product>
         <BuyLinkID>1400835</BuyLinkID>
         <CouponDiscountPercent>45.000000</CouponDiscountPercent>
      </Product>
      <Product>
         <BuyLinkID>44455566</BuyLinkID>
         <CouponDiscountPercent>38.000000</CouponDiscountPercent>
      </Product>
   </Coupon>
   <Coupon>
      <Activity>1</Activity>
      <CampaignName>PROMORU</CampaignName>
      <CouponCode>TESTALLSOFT2</CouponCode>
      <CouponNumberFrom>537066</CouponNumberFrom>
      <CouponNumberUp>537066</CouponNumberUp>
      <CouponStartDate>2019-07-01</CouponStartDate>
      <CouponStopDate>2019-07-15</CouponStopDate>
      <CouponType>one-time</CouponType>
      <ExternalCode>TESTPromo1</ExternalCode>
      <Product>
         <BuyLinkID>4614176</BuyLinkID>
         <Currency>COP</Currency>
         <StreetPrice>600</StreetPrice>
      </Product>
   </Coupon>
</Request>
См. также:

Обновление купонов

Для обновления ранее созданных купонов предназначен запрос update.

  • В одном запросе могут быть переданы данные для обновления нескольких купонов.
  • Один и тот же купон должен быть передан в запросе только один раз, иначе все переданные изменения применятся последовательно.
  • Если в запросе в качестве идентификационных данных передана только серия купона (CouponCode), то будет обновлен купон, применяемый только по серии (с пустыми CouponNumber).
  • Идентификационные данные купона нельзя обновить. В том числе нельзя сделать из купона, который применяется по серии, купон, который будет применяться по серии и номеру.
  • Все данные купона кроме идентификационных можно обновить, передав новые значения в одном запросе.

Пример:

<Request>
   <Request>update</Request>
   <Coupon>
      <Activity>1</Activity>
      <CampaignName>PROMORU</CampaignName>
      <CouponCode>PROMO_RU_1</CouponCode>
      <CouponNumberFrom>566544</CouponNumberFrom>
      <CouponNumberUp>566544</CouponNumberUp>
      <CouponStartDate>2021-01-01</CouponStartDate>
      <CouponStopDate>2022-01-01</CouponStopDate>
      <CouponType>one-time</CouponType>
      <ExternalCode>CodPromo1</ExternalCode>
      <IsVisibleToAuthor>1</IsVisibleToAuthor>
      <Product>
         <BuyLinkID>1400835</BuyLinkID>
         <CouponDiscountPercent>10.000000</CouponDiscountPercent>
      </Product>
      <Product>
         <BuyLinkID>1400836</BuyLinkID>
         <CouponDiscountPercent xsi:nil="true"/>
      </Product>
   </Coupon>
</Request>
См. также:

Обновление свойств купона

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

Пример:

<Request>
   <Request>update</Request>
   <Coupon>
      <CouponId>1114566</CouponId>
      <Activity>0</Activity>
   </Coupon>
</Request>
См. также:

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

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

  • Если в запросе передан продукт (BuyLinkID) и скидка для него:
    • Если ранее продукт не был привязан к купону, то привязка будет добавлена. То есть после применения купона к продукту будет применена скидка.
    • Если продукт уже был привязан к купону, то скидка будет обновлена.
  • Скидка на продукт останется без изменений, если продукт не указан в запросе.

Пример:

<Request>
   <Request>update</Request>
   <Coupon>
      <Activity>1</Activity>
      <CouponCode>PROMO_RU_1</CouponCode>
      <CouponNumberFrom>566544</CouponNumberFrom>
      <CouponNumberUp>566544</CouponNumberUp>
      <Product>
         <BuyLinkID>1400835</BuyLinkID>
         <CouponDiscountPercent>10.000000</CouponDiscountPercent>
      </Product>
   </Coupon>
</Request>
См. также:

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

Для удаления скидки на продукт из купона нужно:
  • Выполнить запрос update.
  • В контейнере Product передать BuyLinkID продукта и <CouponDiscountPercent xsi:nil="true"/>
После выполнения запроса:
  • В случае успешной обработки продукт будет отвязан от купона, скидка на продукт будет удалена.
  • Если продукт не привязан к купону, то вернется ошибка 17 (Reason: The coupon does not provide such a discount for the item).
  • Если из купона удаляются скидки на все продукты, и добавляются скидки на новые продукты, то купон будет обновлен.
  • Если в одном запросе удаляется скидка на определенный продукт, а затем для этого же продукта добавляется скидка с новыми данными - то будет возвращена ошибка (400 Bad Request. Double BuyLinkID: [ID продукта], CouponCode: [Серия купона]). Данные не будут обновлены.
  • Если после удаления в купоне больше не осталось привязанных к нему продуктов со скидками, то купон будет удален автоматически.

Пример:

<Request>
   <Request>update</Request>
   <Coupon>
      <CouponId>1114566</CouponId>
      <Product>
         <BuyLinkID>1400835</BuyLinkID>
         <CouponDiscountPercent xsi:nil="true"/>
      </Product>
   </Coupon>
</Request>
См. также:

Удаление купонов

Для удаления купонов предназначен запрос delete.

  • Для удаления определенного купона достаточно передать один из вариантов идентификационных данных.
  • Для удаления всех купонов определенной серии с любыми номерами/без номеров следует передать только серию купона.
(!) Обратите внимание:
  • Один и тот же купон указывается в запросе только один раз, в противном случае:
    • Будет удален купон, указанный в первом блоке.
    • Остальные блоки вернутся с указанием кода ошибки 20.
  • Если в запросе указать другие параметры (например, идентификатор продукта), то они будут проигнорированы.

Примеры:

Удаление определенного купона
по ID
Удаление определенного купона,
применяемого по серии и номеру
<?xml version="1.0" encoding="UTF-8"?>
<Request>
   <Request>delete</Request>
   <Coupon>
      <CouponId>1114566</CouponId>
   </Coupon>
</Request>
<?xml version="1.0" encoding="UTF-8"?>
<Request>
   <Request>delete</Request>
   <Coupon>
      <CouponCode>PROMO_RU_9</CouponCode>
      <CouponNumberFrom>5</CouponNumberFrom>
      <CouponNumberUp>50</CouponNumberUp>
   </Coupon>
</Request>
Удаление определенного купона,
применяемого только по серии
Удаление всех купонов определенной серии
<?xml version="1.0" encoding="UTF-8"?>
<Request>
   <Request>delete</Request>
   <Coupon>
      <CouponCode>PROMO_RU_6</CouponCode>
      <CouponNumberFrom></CouponNumberFrom>
      <CouponNumberUp></CouponNumberUp>
   </Coupon>
</Request>

(!) Обратите внимание, теги CouponNumber переданы пустыми, чтобы был удален именно определенный купон, а не все купоны указанной серии
<?xml version="1.0" encoding="UTF-8"?>
<Request>
   <Request>delete</Request>
   <Coupon>
      <CouponCode>PROMO_RU_8</CouponCode>
   </Coupon>
</Request>
См. также:

Замена купонов

Для замены списка купонов на новый список предназначен запрос replace.
При успешном выполнении запроса:
  • Все существующие купоны Партнера удаляются;
  • Создаются новые купоны согласно запросу.

(!) Один и тот же купон указывается в запросе только один раз, в противном случае запрос не будет выполнен.

Примеры:

<?xml version="1.0" encoding="UTF-8"?>
<Request>
   <Request>replace</Request>
   <Coupon>
      <Activity>1</Activity>
      <CampaignName>PROMORU</CampaignName>
      <CouponCode>PROMO_RU_1</CouponCode>
      <CouponNumberFrom>566544</CouponNumberFrom>
      <CouponNumberUp>566544</CouponNumberUp>
      <CouponStartDate>2020-01-01</CouponStartDate>
      <CouponStopDate>2021-01-01</CouponStopDate>
      <CouponType>reusable</CouponType>
      <ExternalCode>CodPromo1</ExternalCode>
      <IsVisibleToAuthor>1</IsVisibleToAuthor>
      <Product>
         <BuyLinkID>1400835</BuyLinkID>
         <CouponDiscountPercent>45.000000</CouponDiscountPercent>
      </Product>
      <Product>
        <BuyLinkID>4145393</BuyLinkID>
    <Currency>RUB</Currency>
    <StreetPrice>99.99</StreetPrice>
      </Product>
   </Coupon>
   <Coupon>
      <Activity>0</Activity>
      <CampaignName>PROMORU</CampaignName>
      <CouponCode>PROMO_RU_2</CouponCode>
      <CouponNumberFrom>537066</CouponNumberFrom>
      <CouponNumberUp>537066</CouponNumberUp>
      <CouponStartDate>2020-01-01</CouponStartDate>
      <CouponStopDate>2021-01-01</CouponStopDate>
      <CouponType>one-time</CouponType>
      <ExternalCode>TESTPromo1</ExternalCode>
      <IsVisibleToAuthor>0</IsVisibleToAuthor>
      <Product>
         <BuyLinkID>4614176</BuyLinkID>
         <Currency>COP</Currency>
         <StreetPrice>600</StreetPrice>
      </Product>
   </Coupon>
</Request>
См. также:

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

Положительный ответ на запросы по созданию, обновлению и удалению купонов

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

Подробнее:

Положительный ответ на запрос по замене купонов

Список купонов успешно заменится на новый список, если выполнены все действия:
  • Все проверки успешно завершены;
  • Предыдущие купоны успешно удалены;
  • Создан новый список купонов согласно запросу.

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

Поскольку при замене купонов предыдущие купоны Партнера удаляются, то в ответе также придут данные по удаленным купонам (см. блок <Deleted> в примере далее).

Пример:

<Response>
    <Result>
        <Error>0</Error>
        <ErrorMessage/>
        <Coupon>
            <Request>replace</Request>
            <CouponId>980021</CouponId>
            <Activity>0</Activity>
            <IsVisibleToAuthor>1</IsVisibleToAuthor>
            <CampaignName>PROMORU</CampaignName>
            <CouponCode>PROMO_RU_3</CouponCode>
            <CouponNumberFrom>537066</CouponNumberFrom>
            <CouponNumberUp>537066</CouponNumberUp>
            <CouponStartDate>2020-01-01</CouponStartDate>
            <CouponStopDate>2021-01-01</CouponStopDate>
            <CouponType>one-time</CouponType>
            <CouponDiscountPercent>1</CouponDiscountPercent>
            <ExternalCode>TESTPromo1</ExternalCode>
            <Product>
                <CouponDiscountPercent>80.645161</CouponDiscountPercent>
                <BuyLinkID>4614176</BuyLinkID>
                <Currency>COP</Currency>
                <StreetPrice>600</StreetPrice>
            </Product>
        </Coupon>
    </Result>
    <Deleted>
        <Coupon>
            <CouponId>980019</CouponId>
            <CampaignName>PROMORU</CampaignName>
            <CouponCode>PROMO_RU_1</CouponCode>
            <CouponNumberFrom>566544</CouponNumberFrom>
            <CouponNumberUp>566544</CouponNumberUp>
            <CouponStartDate>2020-01-01</CouponStartDate>
            <CouponStopDate>2021-01-01</CouponStopDate>
            <CouponType>reusable</CouponType>
            <CouponDiscountPercent>1.000000</CouponDiscountPercent>
            <ExternalCode>CodPromo1</ExternalCode>
            <Activity>1</Activity>
            <IsVisibleToAuthor>1</IsVisibleToAuthor>
            <Products>
                <Product>
                    <BuyLinkID>1400835</BuyLinkID>
                    <DiscountPercent>45.000000</DiscountPercent>
                </Product>
                <Product>
                    <BuyLinkID>4145393</BuyLinkID>
                    <DiscountPercent>98.000200</DiscountPercent>
                </Product>
            </Products>
        </Coupon>
        <Coupon>
            <CouponId>980020</CouponId>
            <CampaignName>PROMORU</CampaignName>
            <CouponCode>PROMO_RU_2</CouponCode>
            <CouponNumberFrom>537066</CouponNumberFrom>
            <CouponNumberUp>537066</CouponNumberUp>
            <CouponStartDate>2020-01-01</CouponStartDate>
            <CouponStopDate>2021-01-01</CouponStopDate>
            <CouponType>one-time</CouponType>
            <CouponDiscountPercent>1.000000</CouponDiscountPercent>
            <ExternalCode>TESTPromo1</ExternalCode>
            <Activity>0</Activity>
            <IsVisibleToAuthor>0</IsVisibleToAuthor>
            <Products>
                <Product>
                    <BuyLinkID>4614176</BuyLinkID>
                    <DiscountPercent>80.645161</DiscountPercent>
                </Product>
            </Products>
        </Coupon>
    </Deleted>
</Response>

Ошибки

Ошибка Описание
HTTP/1.1 401 Unauthorized Неуспешная авторизация.
HTTP/1.1 400 Bad Request Запрос не действителен (ошибка в параметрах, не переданы необходимые данные).
Или для одного купона переданы данные с процентом скидки на продукт (CouponDiscountPercent) и окончательную стоимость продукта (StreetPrice).
HTTP/1.1 400 Bad Request. Double BuyLinkID: [Идентификатор продукта], CouponCode: [Серия купона] В запросе update для одного BuyLinkID одновременно передано: удаление скидки и добавление новой скидки.
HTTP/1.1 500 Request Error Ошибка на стороне сервера.

Дополнительно в теле ответа может быть передан xml с внутренним кодом ошибки и описанием.

Дополнительные коды ошибок
Ошибка Сообщение об ошибке Запрос Описание
Ошибки в данных
Ответ возвращается по купону на каждый продукту отдельно, так как результат для каждого продукта в запросе может быть разный.
10 Product not found. create, update, replace Продукт с заданным BuyLinkID не найден.
11 You have no rights to work with this BuyLinkID create, update, replace Продукт найден, но принадлежит другому Партнеру.
12 No product price found in this currency create, update, replace Для продукта не найдена цена в переданной валюте.
13 Unable to determine the exact product price in this currency create, update, replace Цена на продукт в переданной валюте не может быть однозначно определена.
14 Unable to determine the exact product price, a range of prices is set create, update, replace Цена на продукт не может быть однозначно определена, так как для ценовой группы настроено несколько цен в зависимости от количества продукта.
15 The calculated discount percentage is greater than or equal to 100% create, update, replace Рассчитанный процент скидки больше или равен 100%.
16 The discounted price is greater than or equal to the price of the product in the catalog create, update, replace Стоимость со скидкой больше или равна цене продукта в каталоге.
17 The coupon does not provide such a discount for the item. update При попытке удалить позицию из купона, если этой позиции в данном купоне нет.
21 You have no rights to work with this coupon delete, update Характеристики купона не позволяют управлять им (например, скидка по купону предоставлена на программы другого Партнера).
22 You have no rights to work with this coupon, the discount is provided by Allsoft delete, update У вас нет прав для работы с данным купоном, скидку по нему предоставляет Softline Ecommerce.
30 The action can not be performed, the coupon already exists create, replace Данный купон уже существует в системе или купон был передан в одном и том же запросе более одного раза.
100 The request could not be completed replace Обнаружена ошибка при проверке данных в запросе. Отправляется по всем продуктам, по которым были пройдены проверки.
Ошибки при выполнении запроса
50 Could not fulfill the request create, update, replace Не удалось выполнить запрос (технические проблемы, проблемы на стороне Softline Ecommerce).

Примеры:

Ответ на запрос "update" Ответ на запрос "replace"
<Response>
    <Result>
        <Error>20</Error>
        <ErrorMessage>Coupon not found</ErrorMessage>
        <Coupon>
            <Request>update</Request>
            <Activity>1</Activity>
            <CampaignName>PROMORU</CampaignName>
            <CouponCode>PROMO_RU_11</CouponCode>
            <CouponStartDate>2021-01-01</CouponStartDate>
            <CouponStopDate>2022-01-01</CouponStopDate>
            <CouponType>one-time</CouponType>
            <ExternalCode>CodPromo1</ExternalCode>
            <IsVisibleToAuthor>0</IsVisibleToAuthor>
            <CouponNumberFrom/>
            <CouponNumberUp/>
            <Product>
                <BuyLinkID>1400835</BuyLinkID>
                <CouponDiscountPercent>10.000000</CouponDiscountPercent>
            </Product>
        </Coupon>
    </Result>
</Response>
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Result>
        <Error>10</Error>
        <ErrorMessage>Product not found</ErrorMessage>
        <Coupon>
            <Request>replace</Request>
            <Activity>1</Activity>
            <CampaignName>PROMORU</CampaignName>
            <CouponCode>PROMO_RU_11</CouponCode>
            <CouponStartDate>2021-01-01</CouponStartDate>
            <CouponStopDate>2022-01-01</CouponStopDate>
            <CouponType>one-time</CouponType>
            <ExternalCode>CodPromo1</ExternalCode>
            <IsVisibleToAuthor>0</IsVisibleToAuthor>
            <CouponNumberFrom/>
            <CouponNumberUp/>
            <Product>
                <BuyLinkID>1234567899876564321</BuyLinkID>
                <CouponDiscountPercent>10.000000</CouponDiscountPercent>
            </Product>
        </Coupon>
    </Result>
    <Result>
        <Error>100</Error>
        <ErrorMessage>The request could not be completed</ErrorMessage>
        <Coupon>
            <Request>replace</Request>
            <Activity>1</Activity>
            <CampaignName>PROMORU</CampaignName>
            <CouponCode>PROMO_RU_12</CouponCode>
            <CouponStartDate>2021-01-01</CouponStartDate>
            <CouponStopDate>2022-01-01</CouponStopDate>
            <CouponType>one-time</CouponType>
            <ExternalCode>CodPromo2</ExternalCode>
            <IsVisibleToAuthor>0</IsVisibleToAuthor>
            <CouponNumberFrom/>
            <CouponNumberUp/>
            <Product>
                <BuyLinkID>12345678</BuyLinkID>
                <CouponDiscountPercent>10.000000</CouponDiscountPercent>
            </Product>
        </Coupon>
    </Result>
</Response>

Ответ с ошибками возвращается в случае, если произошла хотя бы одна ошибка при обработке запроса.
В этом случае:
- Код соответствующей ошибки возвращается только для первой найденной ошибки.
- Код 100 возвращается по всем прочим продуктам (включая те, которые были успешно проверены и те, которые не были проверены).
- Новый список купонов не создается.

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

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

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

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

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