FBO, возвраты, вопросы, акции и сертификаты

Часть руководства «Переход на Lamoda Seller API v2».

Раздел описывает миграцию FBO-поставок, FBO-остатков, FBS-возвратов, вопросов покупателей, акций и подарочных сертификатов.

FBO-поставки

Пример создания поставки:

{
  "sellerId": "12345",
  "warehouseCode": "BYKOVO",
  "externalShipmentId": "SHP-2024-0001",
  "documentNumber": "1aa2706f-cacd-4040-b094-c5f9fd844b2b",
  "plannedDate": "2024-05-30",
  "items": [
    {
      "externalSku": "CSM02425/grey-S",
      "quantity": 10,
      "price": {"amount": 19990, "currency": "RUB"},
      "markingCodes": ["010460123456789021u7H6Y7pTt9"]
    }
  ],
  "pallets": [
    {"palletCode": "PALLET-1"}
  ]
}

warehouseCode в спецификации v2 ограничен значениями BYKOVO и SOFINO. Отдельного v2-метода для списка складов, аналогичного JSON-RPC fbo/warehouse.list, нет.

Для отмены поставки используйте POST /v2/fbo/shipments/{shipmentId}/cancel:

{
  "sellerId": "12345",
  "cancelReason": "ACTUALITY"
}

cancelReason обязателен. Допустимые значения:

• DUPLICATED — дубликат поставки;
• ACTUALITY — поставка больше не актуальна;
• DOCS — неверные документы поставки;
• DATE — неверная дата поставки;
• SIZE — неверная сумма или количество товаров.

При переносе старого кода обратите внимание на идентификаторы:

• старый code поставки становится shipmentId в path методов чтения;
• внешний номер поставки передается как externalShipmentId;
• товар в поставке идентифицируется через externalSku;
• documentNumber не входит в список обязательных полей, но остается доступным для сопроводительного документа.

FBO-остатки

Для FBO в v2 доступны только операции чтения:

• GET /v2/fbo/stocks — остатки с фильтрами warehouseCode, sku, externalSku, withZeroQuantity;
• GET /v2/fbo/stocks/illiquid — заблокированные/неликвидные остатки.

Обновления FBO-остатков через API нет: остатки меняются через поставки и складские процессы Lamoda.

Возвраты FBS

В Seller API v2 появляется отдельный раздел для мониторинга FBS-возвратов, которого не было в v1. При переходе на v2 используйте его как новый блок интеграции: отслеживайте возвратные короба, возвратные товары, историю статусов и сводки.

Методы возвратов читают состояние возвратных коробов и товаров. Через них нельзя менять статус возврата. Если старая интеграция меняла статус возврата через заказ или change_status_request, сверяйте такой переход с правилами обработки заказа.

Вопросы покупателей

Пример ответа:

{
  "sellerId": "242541217",
  "text": "Здравствуйте! Товар соответствует размерной сетке бренда."
}

Ограничение текста ответа — 1000 символов. После отправки учитывайте модерационные статусы ответа: APPROVED, ON_MODERATION, REJECTED.

Акции

В Seller API v2 появляется управление акциями через API, которого не было в v1. При переходе на v2 добавьте в интеграцию получение списка акций, проверку доступных товаров, добавление товаров в вариант акции и удаление из него.

Перед добавлением товаров в акцию проверьте:

• status акции: регистрация товаров имеет смысл для открытых и доступных к управлению акций;
• isRegistrationClosed, addProductsFromDate, addProductsToDate, deleteProductsToDate — окна добавления и удаления товаров;
• ограничения варианта: businessModels, gender, categories, productMinPrice, процент скидки;
• доступные товары в GET /v2/promotion-variants/{promotionVariantId}/available-products: isFraudThresholdExceeded, recommendedBlackPrice, recommendedRedPrice, salePeriodCoversPromoPeriod, addedToAdjacentVariant;
• страна в контракте добавления/удаления товаров сейчас ограничена country: "RU".

Пример добавления товара:

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

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

При миграции цен и акций учитывайте связь с force в методах цен:

• если цена нарушает условия акции со статусом WARNING, force=true может обновить цену и удалить товар из акции;
• если нарушение имеет статус RESTRICTION, принудительное обновление цены невозможно;
• интерфейс интегратора должен показывать причину отказа, а не просто повторять запрос.

Подарочные сертификаты

Пример генерации сертификата:

{
  "sellerId": "12345",
  "country": "RU",
  "currency": "RUB",
  "certificates": [
    {"amount": 100000, "quantity": 1}
  ]
}

Для перевода сертификатов в статус Paid используйте POST /v2/gift-certificates/mark-paid:

{
  "sellerId": "12345",
  "certificateIds": ["GC-000001", "GC-000002"]
}

Нотификации

Методы v1 для управления webhook subscriptions, callback payload specs и resend notifications станут deprecated и позже будут выключены.

См. также

• Переход на Lamoda Seller API v2
• Общие изменения контракта
• Справочник соответствия методов
• Продажа со склада Lamoda (FBO)