Управление акциями через API

REST API для акций позволяет автоматизировать работу с акциями Lamoda: находить доступные акции, получать информацию об условиях участия, подбирать подходящие товары и управлять их участием — добавлять в акции, удалять из акций и переключать между вариантами с разной скидкой.

Все методы требуют JWT-токен в заголовке Authorization: Bearer <token>. Во всех запросах sellerId должен соответствовать селлеру из токена. Полный контракт запросов и ответов смотрите в REST API Specification Lamoda Seller.

Что можно сделать через API

Получить список акций и вариантов

GET /v2/promotions?sellerId=12345
Authorization: Bearer <access_token>

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

Идентификаторы:

• promotionId — значение поля promotions[*].id;
• promotionVariantId — значение поля promotions[*].promotionVariants[*].promotionVariantId.

Акция и вариант акции

В API есть два уровня промо:

Например, одна акция может иметь несколько вариантов с разным процентом скидки. Процент скидки варианта передаётся в поле discountAmount. Просмотр товаров, участвующих в акции, выполняется по promotionId, а добавление и удаление товаров — по promotionVariantId.

Фильтр finished

По умолчанию GET /v2/promotions работает как finished=false и возвращает акции, у которых время завершения ещё не истекло. В такой ответ могут попасть акции со статусами ACTIVE, PLANNED, OPEN и IDLE.

Чтобы получить завершённые акции, передайте finished=true.

GET /v2/promotions?sellerId=12345&finished=true
Authorization: Bearer <access_token>

Типы акций

В ответе по акциям есть поле type:

Периоды управления товарами

У акции есть несколько дат, которые влияют на работу с товарами:

Посмотреть товары, добавленные в акцию

GET /v2/promotions/{promotionId}/products?sellerId=12345
Authorization: Bearer <access_token>

Метод возвращает товары, которые уже добавлены селлером в акцию. Используйте promotionId из метода GET /v2/promotions.

Этот метод полезен после добавления или удаления товаров: он помогает сверить фактический состав товаров в акции. Но важно понимать, что процесс добавления и удаления товаров может занимать несколько минут.

Пагинация и сортировка

Метод поддерживает пагинацию. Также можно отсортировать список по дополнительной скидке от Lamoda:

GET /v2/promotions/{promotionId}/products?sellerId=12345&sort=-lamodaDiscountPercent
Authorization: Bearer <access_token>

В параметре sort можно передать поле lamodaDiscountPercent. Без префикса - сортировка выполняется по возрастанию, с префиксом - — по убыванию. Если sort не передан, применяется сортировка по умолчанию: по внутреннему идентификатору товара.

Получить товары для добавления в вариант акции

GET /v2/promotion-variants/{promotionVariantId}/available-products?sellerId=12345
Authorization: Bearer <access_token>

Метод возвращает товары селлера, которые подходят для выбранного варианта акции. Используйте promotionVariantId из метода GET /v2/promotions.

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

Если товар уже участвует в смежном варианте, то информация отобразится в поле addedToAdjacentVariant. В таком случае потребуется сначала удалить товар из текущего варианта — товар может находиться только в одном варианте акции.

Идентификатор товара и страна продажи

В методах работы с товарами идентификатор товара — это пара parentSku + country. Поле parentSku указывает на родительский SKU Lamoda, а country — на страну продажи товара.

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

На данный момент акции умеют работать только с товарами RU. Для добавления и удаления товаров передавайте country, равный RU.

На что обращать внимание при выборе товаров

Все цены в ответах передаются в копейках. Например, amount: 680000 означает 6800.00 RUB.

Валидация акционных цен и рекомендуемые цены

При добавлении товара в акцию система автоматически проверяет, проходит ли рассчитанная цена по акции валидацию акционных цен. Если цена по акции не проходит валидацию, поле isFraudThresholdExceeded будет true.

В этом случае API может вернуть рекомендации:

Подробнее про валидацию акционных цен см. в статье Валидация акционных цен.

Период цены со скидкой (красной цены)

В некоторых случаях для успешного прохождения валидации redPrice необходимо, чтобы период действия redPrice включал период действия акции — см. salePeriodCoversPromoPeriod:

Если красной цены нет, значение считается FULLY_COVERED.

Смежные варианты акции

Товар может находиться только в одном варианте акции. Например, если товар уже добавлен в вариант со скидкой 15%, его нельзя сразу добавить в вариант со скидкой 25%.

В списке доступных товаров поле addedToAdjacentVariant показывает, в каком варианте этой же акции товар находится сейчас:

• promotionVariantId — текущий вариант акции, куда уже добавлен товар;
• discountPercent — скидка в смежном варианте;
• promocodePrice — рассчитанная цена по акции в смежном варианте;
• lamodaDiscountPercent — дополнительная скидка от Lamoda, если она есть.

Чтобы добавить такой товар в другой вариант, сначала удалите его из текущего варианта методом DELETE /v2/promotion-variants/{promotionVariantId}/products, а затем добавьте в целевой вариант методом POST /v2/promotion-variants/{promotionVariantId}/products.

Добавить товары в вариант акции

POST /v2/promotion-variants/{promotionVariantId}/products
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "sellerId": "12345",
  "products": [
    {
      "parentSku": "MP002XG033BD",
      "country": "RU"
    }
  ]
}

Метод добавляет товары в выбранный вариант акции. Используйте promotionVariantId целевого варианта.

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

Как читать validation

Ответ 200 OK означает, что запрос обработан, но не гарантирует добавление каждого товара. Проверяйте массив validation:

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

Примеры возможных значений reasons[]:

• wrong axapta category — товар не подходит по категории;
• wrong term — товар не подходит по срокам или условиям участия;
• wrong price — товар не подходит по цене;
• wrong gender — товар не подходит по полу;
• fraud price threshold exceeded — рассчитанная цена по акции не проходит валидацию акционных цен;
• sale period not cover promo period — период действия цены со скидкой не покрывает период акции.

Эти значения приведены как примеры. Строки в validation.reasons не зафиксированы контрактом и могут измениться, поэтому не используйте их как единственный стабильный признак бизнес-логики.

Удалить товары из варианта акции

DELETE /v2/promotion-variants/{promotionVariantId}/products
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "sellerId": "12345",
  "products": [
    {
      "parentSku": "MP002XG033BD",
      "country": "RU"
    }
  ]
}

Метод удаляет товары из конкретного варианта акции. Удаление доступно только в пределах периода deleteProductsToDate.

Рекомендуемый сценарий интеграции

1. Получите список акций методом GET /v2/promotions?sellerId=<sellerId>.
2. Выберите акцию и подходящий вариант акции из promotionVariants.
3. Проверьте сроки добавления и удаления товаров.
4. При необходимости посмотрите уже добавленные товары методом GET /v2/promotions/{promotionId}/products?sellerId=<sellerId>.
5. Получите товары для добавления методом GET /v2/promotion-variants/{promotionVariantId}/available-products?sellerId=<sellerId>.
6. Проверьте, проходят ли рассчитанные цены по акции валидацию акционных цен, включает ли период действия цены со скидкой у таких товаров период действия акции, изучите рекомендации по изменению цен и условия участия в других вариантах этой акции.
7. Если addedToAdjacentVariant заполнен и товар нужно добавить в целевой вариант, сначала удалите его из текущего варианта методом DELETE /v2/promotion-variants/{promotionVariantId}/products.
8. Добавьте товары методом POST /v2/promotion-variants/{promotionVariantId}/products.
9. Проверьте validation: товары из этого массива не были добавлены в выбранный вариант.
10. Проверьте итоговый список товаров методом GET /v2/promotions/{promotionId}/products?sellerId=<sellerId>.

Коды ошибок

См. также

• REST API Specification Lamoda Seller
• Акции (бизнес-правила)
• Валидация акционных цен
• Акции с дополнительной скидкой от Lamoda