По всей базе знаний
Softline Checkout
Наверх
По всей базе знаний
Softline CheckoutИнтеграцияPromotions API
[POST] Создание промоакции

[POST] Создание промоакции

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

POST /v1/promotion

Запрос позволяет создать промоакцию и настроить скидки на ваши продукты. Узнайте подробнее о том, как работают промоакции.

В запросе передаются:

Данные для отправки запроса

Параметры заголовка

content-type
string
required
MIME-тип данных в теле запроса.
Должен быть равен "application/json".
AuthorizationJWT
required
Авторизационный токен
  • Формат значения: Bearer [token]
  • Вместо [token] подставьте значение token, полученное в ответ на запрос к Authentication API.

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

promotion_type
string
required
Тип промоакции

Варианты значения:
  • coupon - скидка применится к продукту только после активации промокода в корзине
  • discount - скидка применится к продукту автоматически сразу при его добавлении в корзину
promotion_name
string
required
Название промоакции
Не отображается покупателю. Используйте, чтобы упорядочить список промоакций. По названию вы сможете найти промоакцию с помощью GET-запроса или через Merchant Portal.

Не более 255 символов.
status
boolean
Активность промоакции

Варианты значений:
  • true - активна
  • false - деактивирована
По умолчанию - true.
date_from
string
Дата начала действия промоакции
  • Формат даты: YYYY-MM-DDThh:mm:ss±hh:mm
    При обработке дата будет пересчитана по часовому поясу сервера и сохранена в промоакцию. При последующих запросах на получение данных промоакции дата будет возвращена в часовом поясе сервера
  • Если параметр передан, то должно выполняться условие: date_from ≤ date_to
  • Если параметр не передан, то в качестве даты начала будет сохранена текущая дата и время
date_to
string
Дата окончания действия промоакции
  • Формат даты: YYYY-MM-DDThh:mm:ss±hh:mm
    При обработке дата будет пересчитана по часовому поясу сервера и сохранена в промоакцию. При последующих запросах на получение данных промоакции дата будет возвращена в часовом поясе сервера
  • Если параметр передан, то должно выполняться условие: date_from ≤ date_to
  • Если параметр не передан, то в качестве даты окончания будет сохранено значение "01.01.3000 00:00" (соответствует "бессрочной" промоакции)
coupons
object
required*
Данные промокодов для промоакции с типом coupon
  • * - Обязательный параметр, если "promotion_type":"coupon"
  • Параметр не должен быть передан, если "promotion_type":"discount"
Посмотрите примеры заполнения данных в объекте для разных вариантов применения скидок.
coupons
/
coupon_type
string
Тип промокодов
Определяет возможности повторного применения одного промокода. В одной промоакции могут быть промокоды только одного типа.

Варианты значения:
  • one-time - в этом случае один и тот же промокод может быть применен только к продуктам одного заказа. При управлении промоакцией через портал данный тип промокодов называется "disposable"
  • reusable - в этом случае один и тот же промокод может быть применен к продуктам нескольких заказов
По умолчанию reusable.
coupons
/
coupon_code
array [strings]
required*
Список промокодов
Для получения скидки промокод должен быть активирован в корзине. Покупатель должен ввести промокод в специальное поле для его активации.
  • * - Обязательный параметр, если "promotion_type":"coupon"
  • Список промокодов передается в формате массива, каждый элемент массива содержит один промокод
  • Формат элемента массива:
    • Строка, не более 30 символов.
    • Разрешено: буквы (латинский и кириллический алфавит), цифры, тире, подчеркивание, точка.
    • Значение регистронезависимо.
    • Уникальное значение в рамках одной промоакции. Обратите внимание, промокоды разных промоакций могут совпадать. Если при активации промокода будут найдено несколько промоакций, отвечающих условиям применения, то на продукт подействует скидка только из одной из них. Узнайте подробнее о том, как применяется скидка в этом случае
coupons
/
discount_percent
string
required*
Общая скидка (процент)
Действует на продукты, которые переданы в параметре coupons.product_id или на все ваши продукты, если параметр coupons.product_id не передан. Скидка применяется к продукту после активации промокода в корзине.
  • ⃰ - Обязательный параметр, если в промоакции не используются индивидуальные скидки на продукты (не передан параметр coupons.products). Т.е. в запросе может быть передан только один из параметров: coupons.discount_percent или coupons.products
  • Формат: Число, до 6 десятичных знаков, разделитель - точка
  • Правило заполнения: 0 < discount_percent ≤ 100
Посмотрите примеры запросов с использованием общей скидки:
coupons
/
product_id
array [numbers]
Список идентификаторов продуктов, на которые действует общая скидка (coupons.discount_percent). Скидка применяется к продукту после активации промокода в корзине. Если вы хотите, чтобы общая скидка действовала на все ваши продукты, то не передавайте этот параметр.
  • Параметр не должен быть передан, если в промоакции используются индивидуальные скидки на продукты (передан параметр coupons.products). Т.е. в запросе может быть передан только один из параметров: coupons.product_id или coupons.products
  • Список идентификаторов продуктов в параметре передается в формате массива, каждый элемент массива содержит один идентификатор
  • Формат элемента массива: Число
  • Значения идентификаторов в массиве не должны повторяться
Посмотрите пример запроса с использованием общей скидки на выбранные продукты.
coupons
/
products
object
Список индивидуальных скидок на продукты
Используйте, чтобы передать список продуктов-участников промоакции и задать индивидуальную скидку для каждого из них. Скидка применяется к продукту после активации промокода в корзине.
Параметр не должен быть передан, если в промоакции используется общая скидка (передан параметр coupons.discount_percent). Т.е. в запросе может быть передан только один из параметров: coupons.discount_percent или coupons.products.

Посмотрите пример запроса с использованием индивидуальных скидок.
coupons / products / [object]
/
product_id
number
required
Идентификатор продукта, на который действует индивидуальная скидка по промокоду. Скидка применяется к продукту после активации промокода в корзине. Значение идентификатора должно быть уникальным в массиве coupons.products.
coupons / products / [object]
/
discount_percent
string
required
Индивидуальная скидка на продукт
Действует только на продукт, идентификатор которого передан в объекте, в котором передан параметр. Скидка применяется к продукту после активации промокода в корзине.
  • Формат: Число, до 6 десятичных знаков, разделитель - точка
  • Правило заполнения: 0 < discount_percent ≤ 100
discounts
object
required
Данные скидок для промоакции с типом discount
  • * - Обязательный параметр, если "promotion_type":"discount"
  • Параметр не должен быть передан, если "promotion_type":"coupon"
Посмотрите примеры заполнения данных в объекте для разных вариантов применения скидок.
discounts
/
discount_percent
string
required*
Общая скидка (процент)
Действует на продукты, которые переданы в параметре discounts.product_id или на все ваши продукты, если параметр discounts.product_id не передан. Скидка применяется к продукту автоматически сразу после добавления продукта в корзину.
  • ⃰ - Обязательный параметр, если в промоакции не используются индивидуальные скидки на продукты (не передан параметр discounts.products). Т.е. в запросе может быть передан только один из параметров: discounts.discount_percent или discounts.products
  • Формат: Число, до 6 десятичных знаков, разделитель - точка
  • Правило заполнения: 0 < discount_percent ≤ 100
Посмотрите примеры запросов с использованием общей скидки:
discounts
/
product_id
array [numbers]
Список идентификаторов продуктов, на которые действует общая скидка (discounts.discount_percent). Скидка применяется к продукту автоматически сразу после добавления продукта в корзину. Если вы хотите, чтобы общая скидка действовала на все ваши продукты, то не передавайте этот параметр.
  • Параметр не должен быть передан, если в промоакции используются индивидуальные скидки на продукты (передан параметр discounts.products). Т.е. в запросе может быть передан только один из параметров: discounts.product_id или discounts.products
  • Список идентификаторов продуктов в параметре передается в формате массива, каждый элемент массива содержит один идентификатор
  • Формат элемента массива: Число
  • Значения идентификаторов в массиве не должны повторяться
Посмотрите пример запроса с использованием общей скидки на выбранные продукты.
discounts
/
products
object
required*
Список индивидуальных скидок на продукты
Используйте, чтобы передать список продуктов-участников промоакции и задать индивидуальную скидку для каждого из них. Скидка применяется к продукту автоматически сразу после добавления продукта в корзину.
Параметр не должен быть передан, если в промоакции используется общая скидка (передан параметр discounts.discount_percent). Т.е. в запросе может быть передан только один из параметров: discounts.discount_percent или discounts.products.

Посмотрите пример запроса с использованием индивидуальных скидок.
coupons / products / [object]
/
product_id
number
required
Идентификатор продукта, на который действует индивидуальная скидка. Скидка применяется к продукту автоматически сразу после добавления продукта в корзину. Значение идентификатора должно быть уникальным в массиве discounts.products.
coupons / products / [object]
/
discount_percent
string
required
Индивидуальная скидка на продукт
Действует только на продукт, идентификатор которого передан в объекте, в котором передан параметр. Скидка применяется к продукту автоматически сразу после добавления продукта в корзину.
  • Формат: Число, до 6 десятичных знаков, разделитель - точка
  • Правило заполнения: 0 < discount_percent ≤ 100

Примеры запроса с общей скидкой на все продукты

В этом случае:

  • Скидка действует на все ваши продукты
  • Размер скидки одинаковый для каждого продукта

Для создания промоакции с таким типом скидки:

Пример для промоакции с типом coupon и общей скидкой на все продукты

{
 "promotion_type": "coupon",
 "promotion_name": "Black Friday",
 "status": true,
 "date_from": "2023-01-01T00:00:00+03:00",
 "date_to": "2023-01-10T00:00:00+03:00",
 "coupons": {
  "coupon_type": "reusable",
  "coupon_code": [
   "PROMO-001",
   "PROMO-002"
  ],
  "discount_percent": "10"
 }
}

Пример для промоакции с типом discount и общей скидкой на все продукты

{
 "promotion_type": "discount",
 "promotion_name": "Black Friday",
 "status": true,
 "date_from": "2023-01-01T00:00:00+03:00",
 "date_to": "2023-01-10T00:00:00+03:00",
 "discounts": {
  "discount_percent": "10"
 }
}

Примеры запроса с общей скидкой на выбранные продукты

В этом случае:

  • Скидка действует только на продукты, выбранные в промоакции
  • Размер скидки одинаковый для каждого продукта-участника

Для создания промоакции с таким типом скидки:

Пример для промоакции с типом coupon и общей скидкой на выбранные продукты

{
 "promotion_type": "coupon",
 "promotion_name": "Black Friday",
 "status": true,
 "date_from": "2023-01-01T00:00:00+03:00",
 "date_to": "2023-01-10T00:00:00+03:00",
 "coupons": {
  "coupon_type": "reusable",
  "coupon_code": [
   "PROMO-001",
   "PROMO-002"
  ],
  "discount_percent": "10",
  "product_id": [
   11111,
   22222
  ]
 }
}

Пример для промоакции с типом discount и общей скидкой на выбранные продукты

{
 "promotion_type": "discount",
 "promotion_name": "Black Friday",
 "status": true,
 "date_from": "2023-01-01T00:00:00+03:00",
 "date_to": "2023-01-10T00:00:00+03:00",
 "discounts": {
  "discount_percent": "10",
  "product_id": [
   11111,
   22222
  ]
 }
}

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

В этом случае:

  • Скидка действует только на продукты, выбранные в промоакции
  • Размер скидки индивидуальный для каждого продукта-участника

Для создания промоакции с таким типом скидки:

Пример для промоакции с типом coupon и индивидуальными скидками

{
 "promotion_type": "coupon",
 "promotion_name": "Black Friday",
 "status": true,
 "date_from": "2023-01-01T00:00:00+03:00",
 "date_to": "2023-01-10T00:00:00+03:00",
 "coupons": {
  "coupon_type": "reusable",
  "coupon_code": [
   "PROMO-001",
   "PROMO-002"
  ],
  "products": [{
    "product_id": 11111,
    "discount_percent": "10"
   }, {
    "product_id": 22222,
    "discount_percent": "20"
   }
  ]
 }
}

Пример для промоакции с типом discount и индивидуальными скидками

{
 "promotion_type": "discount",
 "promotion_name": "Black Friday",
 "status": true,
 "date_from": "2023-01-01T00:00:00+03:00",
 "date_to": "2023-01-10T00:00:00+03:00",
 "discounts": {
  "products": [{
    "product_id": 11111,
    "discount_percent": "10"
   }, {
    "product_id": 22222,
    "discount_percent": "20"
   }
  ]
 }
}

Ответ на запрос

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

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

При успешной обработке запроса вы получите код ответа сервера HTTP/1.1 200 OK. В теле ответа будет передан идентификатор созданной промоакции в формате JSON.

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

id
number
required
Идентификатор промоакции.

Пример положительного ответа

{
 "id": 45566
}

Ответ об ошибке

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

Справочник HTTP-кодов ответа сервера при ошибке

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

Справочник дополнительных кодов ошибок для HTTP 400

Error Message Описание
Если хотя бы одна ошибка из списка ниже найдена, то она возвращается в ответе на запрос, остальные ошибки не проверяются.
110 JSON is not valid. Структура запроса невалидна. Проверьте параметры в теле запроса на соответствие формату JSON.
111 Invalid data format (Content-type). Неправильный заголовок запроса. Content-type должен быть равен application/json.
11000 No access to promotion management. Please contact technical support. При обработке не смогли однозначно определить настройки вашего аккаунта. Обратитесь в службу поддержки.
Если хотя бы одна ошибка из списка ниже найдена, то проверка запроса не прерывается. В ответе может быть возвращено несколько ошибок.
11010 Invalid field value: [наименование параметра] Запрос не валиден, например, не заполнен обязательный параметр, передано неверное название параметра, тип или формат значения параметра неверны.
В том числе ошибка будет возвращена, если в параметре передано null, и этот вариант значения не указан как допустимый в описании.
11020
 Product not found: [список id продуктов] В запросе передан продукт, который не был найден, или у вас нет доступа к нему. В ошибке будут перечислены идентификаторы продуктов, не прошедших проверку. Проверьте значение параметра: coupons.product_id, coupons.products.[object].product_id, discounts.product_id, discounts.products.[object].product_id
11030
 Same product can be listed only once ([product_id]) within one promotion. Для промоакции с типом "coupon" в одном из параметров запроса переданы совпадающие идентификаторы продуктов (coupons.product_id, coupons.products.[object].product_id. В одном и том же параметре идентификаторы продуктов не должны совпадать.
11031 Same product can be listed only once ([product_id]) within one promotion. Для промоакции с типом "discount" в одном из параметров запроса переданы совпадающие идентификаторы продуктов (discounts.product_id, discounts.products.[object].product_id). В одном и том же поле идентификаторы продуктов не должны совпадать.
11035 Product list has been sent twice. Transfer only one of the two options: coupons.product_id or coupons.products. Для промоакции с типом "coupon" в запросе два раза передан список продуктов: для общей скидки (coupons.product_id) и массив индивидуальных скидок (coupons.products). Допустимо использовать только один из этих вариантов определения скидки. Посмотрите примеры запроса для промоакции с типом coupon.
11036 Product list has been sent twice. Transfer only one of the two options: discounts.product_id or discounts.products. Для промоакции с типом "discount" в запросе два раза передан список продуктов: для общей скидки (discounts.product_id) и массив индивидуальных скидок (discounts.products). Допустимо использовать только один из этих вариантов определения скидки. Посмотрите примеры запроса для промоакции с типом discount.
11040 No discount is set. Provide values for parameters: coupons.discount_percent or coupons.products.discount_percent. Для промоакции с типом "coupon" не определена скидка по промоакции. Вы должны передать один из видов скидки: общую для всех продуктов-участников (coupons.discount_percent) или индивидуальные для каждого продукта-участника (coupons.products.[object].discount_percent). Посмотрите примеры запроса для промоакции с типом coupon.
11041 No discount is set. Provide values for parameters: discounts.discount_percent or discounts.products.discount_percent. Для промоакции с типом "discount" не определена скидка по промоакции. Вы должны передать один из видов скидки: общую для всех продуктов-участников (discounts.discount_percent) или индивидуальные для каждого продукта-участника (discounts.products.[object].discount_percent). Посмотрите примеры запроса для промоакции с типом discount.
11045 Discounts has been sent twice. Transfer only one of the two options: discount_percent or products.discount_percent. Для промоакции с типом "coupon" в запросе два раза передана скидка: общая скидка (coupons.discount_percent) и массив индивидуальных скидок (coupons.products). Допустимо использовать только один из этих вариантов определения скидки. Посмотрите примеры запроса для промоакции с типом coupon.
11046 Discounts has been sent twice. Transfer only one of the two options: discount_percent or products.discount_percent. Для промоакции с типом "discount" в запросе два раза передана скидка: общая скидка (discounts.discount_percent) и массив индивидуальных скидок (discounts.products). Допустимо использовать только один из этих вариантов определения скидки. Посмотрите примеры запроса для промоакции с типом discount.
11050 Promotion validity period (date_from, date_to) is incorrect. В запросе переданы даты действия промоакции, которые не отвечают требованиям (date_from, date_to).
11070 No coupon code is set. Provide at least one value for coupons.coupon_code. Для промоакции с типом "coupon" не переданы промокоды (coupons.coupon_code). Передайте этом параметр или измените тип промоакции.
11080 Coupons.coupon_code list must not contain duplicate values. Для промоакции с типом "coupon" переданы совпадающие промокоды (coupons.coupon_code). Промокоды в одной промоакции не должны совпадать.
11090 Request data and promotion type do not match (promotion_type). В запросе переданы данные, которые не соответствуют типу промоакции.
Например, для промоакции с типом "coupon" ("promotion_type": "coupon") передана информация о скидках (discounts), или для промоакции с типом "discount" ("promotion_type": "discount") передана информация о промокодах (coupons).

Справочник дополнительных кодов ошибок для HTTP 401

Справочник этих ошибок одинаковый для всех API, которые используют авторизацию по токену.

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

errors
array [objects]
required
Список ошибок.
errors / [error object]
/
error
number
required
Код ошибки.
errors / [error object]
/
message
string
Описание ошибки.

Пример ответа об ошибке

{
 "errors": [{
   "error": 11010,
   "message": "Invalid field value: date_from"
  }, {
   "error": 11010,
   "message": "Invalid field value: product_id"
  }
 ]
}
Политика конфиденциальности
© 2024 Softline