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

[PATCH] Изменение промоакции

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

PATCH /v1/promotion/[promotion id]

Запрос позволяет изменить свойства промоакции.
В том числе изменять:

  • Тип промоакции
  • Скидочную модель
  • Для промоакций типа "coupon" изменять список привязанных промокодов и их тип

Ограничение: доступны только промоакции, созданные под тем же пользователем API (username), от лица которого отправляется PATCH запрос.

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

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

[promotion id]
required
Идентификатор промоакции

Вы можете получить его в ответ на запросы: Пример передачи параметра в URL: /v1/promotion/123456

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

content-type
string
required
MIME-тип данных

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

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

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

Варианты значения:
  • coupon - скидка применится к продукту только после активации промокода в корзине.
  • discount - скидка применится к продукту автоматически сразу при его добавлении в корзину.
Если переданное значение не совпадает с текущим типом промоакции, то тип промоакции будет изменен. Посмотрите примеры изменения в отдельном руководстве.
promotion_name
string
Название промоакции
  • Не более 255 символов.
  • Если параметр не передан, то текущее название не изменится.
status
boolean
Активность промоакции

Варианты значений:
  • true - активна.
  • false - деактивирована.
Если параметр не передан, то текущая активность не изменится.
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.
  • Если параметр не передан, то текущая дата окончания действия промоакции не изменится.
coupons
object
required*
Данные промокодов
  • Если "promotion_type":"discount", то данный параметр не должен быть передан.
  • Если "promotion_type":"coupon":
    • Если вы меняете тип промоакции с discount на coupon в этом запросе, то данный параметр является обязательным - *.
    • Если на текущий момент промоакция имеет тип "coupon" и параметр не передан, то данные промокодов в текущей промоакции не изменятся.
    • Если на текущий момент промоакция имеет тип "coupon" и параметр передан, то все значения вложенных параметров будут полностью обновлены новыми значениями. Если какой-то вложнный параметр не передан, то его значение будет изменено на значение по умолчанию, если оно предусмотрено.
    • Если параметр передан, то требования к заполнению вложенных параметров такие же, как при создании промоакции.
discounts
object
required*
Данные скидок
  • Если "promotion_type":"coupon", то данный параметр не должен быть передан.
  • Если "promotion_type":"discount":
    • Если вы меняете тип промоакции с coupon на discount в этом запросе, то данный параметр является обязательным - *.
    • Если на текущий момент промоакция имеет тип "discount" и параметр не передан, то данные скидок в текущей промоакции изменятся.
    • Если на текущий момент промоакция имеет тип "discount" и параметр передан, то все значения вложенных параметров будут полностью обновлены новыми значениями. Если какой-то вложнный параметр не передан, то его значение будет изменено на значение по умолчанию, если оно предусмотрено.
    • Если параметр передан, то требования к заполнению вложенных параметров такие же, как при создании промоакции.

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

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

Запрос на создание: POST /v1/promotion/

{
 "promotion_type": "discount",
 "promotion_name": "Black Friday",
 "discounts": {
  "discount_percent": "50"
 }
}

Чтобы ограничить период проведения промоакции, и сделать так, чтобы промоакция действовала только на выбранный продукт, отправьте запрос на изменение:

PATCH /v1/promotion/123456

{
 "promotion_type": "discount",
 "date_to": "2022-01-10T09:16:35+03:00",
 "discounts": {
  "product_id": [22222],
  "discount_percent": "50"
 }
}

Обратите внимание:

  • В запросе должен присутствовать параметр с типом промоакции (promotion_type).
  • В объекте discounts переданы все параметры, в том числе размер скидки, который не меняется. Так как, если в запросе присутствует объект discounts (или coupons), то все вложенные параметры будут обновлены. Если какой-либо необязательный параметр не будет передан, то он будет пересохранен с значением по умолчанию.

Посмотрите дополнительные примеры изменения промоакции.

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

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

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

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

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

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

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

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

Справочник 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

Справочник этих ошибок совпадает с ошибками при создании промоакции.

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

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

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

Error Message Описание
Если хотя бы одна ошибка из списка ниже найдена, то она возвращается в ответе на запрос, остальные ошибки не проверяются.
11200 Promotion not found: [id промоакции] Запрос не может быть выполнен. Промоакция с переданным id не найдена или у вас нет доступа к ней (в том числе, если промоакция была создана под другим 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"
  }
 ]
}
Политика конфиденциальности
© 2025 Softline