Каталог, цены и остатки

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

Эта глава помогает перенести сценарии из Seller JSON-RPC и B2B REST v1: справочники, создание и обновление карточек, изображения, цены, активацию продаж и остатки.

Новый порядок работы с каталогом

1. Получить доступные справочники продавца: GET /v2/dictionaries.
2. Получить категории: GET /v2/nomenclature-categories.
3. Для нужной категории получить атрибуты: GET /v2/nomenclature-categories/{categoryId}/attributes.
4. Для атрибутов со словарными значениями получить словари: GET /v2/dictionaries/attributes?attributeNames=....
5. Получить соответствия словарных значений для конкретной категории: GET /v2/nomenclature-categories/{categoryId}/attributes-mappings.
6. Создать или обновить товар: POST /v2/nomenclatures.
7. Загрузить изображения: POST /v2/nomenclatures/{sku}/images.
8. Установить цены: POST /v2/nomenclature-price или POST /v2/nomenclatures-prices.
9. Включить или выключить продажи: POST /v2/nomenclatures-activation-status.
10. Обновлять FBS-остатки через /v2/fbs/stocks; FBO-остатки только читать и сверять.

Справочники и атрибуты

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

Практический порядок миграции справочников:

1. Сопоставьте старую категорию товара с категорией Seller API v2. В ответе GET /v2/nomenclature-categories поле называется categoryId, и оно же передаётся в nomenclature.categoryId при вызове POST /v2/nomenclatures. Не смешивайте его с внутренними id ERP/WMS продавца.
2. Для каждой целевой категории сохраните список обязательных атрибутов и допустимых словарных значений.
3. Перед отправкой товара валидируйте родительские атрибуты и атрибуты вариаций по v2-словарям.
4. Не кешируйте словари бессрочно: при изменении категории или страны продажи значения могут отличаться.

Создание или обновление товара

POST /v2/nomenclatures заменяет JSON-RPC nomenclatures.store, B2B POST /api/v1/nomenclatures и PATCH /api/v1/nomenclatures/{supplierSku}.

Упрощенный пример формы запроса:

{
  "sellerId": "471392924",
  "country": "RU",
  "nomenclature": {
    "requestType": "CREATE",
    "categoryId": "5637156660",
    "attributes": {
      "gender": {"type": "STRING", "value": "women"},
      "brand": {"type": "DICTIONARY_ENTRY", "value": "Nike"}
    },
    "variationAttributes": [
      {
        "supplierSku": {"type": "STRING", "value": "SUPPLIER_SKU_1"},
        "productIdentifier": {"type": "STRING", "value": "2000041459377"}
      }
    ]
  },
  "prices": [
    {
      "country": "RU",
      "price": {"amount": 199900, "currency": "RUB"},
      "salePrice": {"amount": 149900, "currency": "RUB"},
      "saleStart": "2025-06-01T00:00:00.000Z",
      "saleEnd": "2025-06-30T23:59:59.000Z"
    }
  ]
}

Обязательные атрибуты зависят от категории, страны и типа товара. Не используйте пример как универсальный минимальный набор для всех категорий: перед отправкой получите атрибуты и соответствия словарей для конкретной категории (categoryId).

Для обновления используйте requestType: "UPDATE". Не пытайтесь перенести старый PATCH как частичное обновление без проверки обязательных атрибутов v2: структура nomenclature должна соответствовать схеме v2.

Ответ метода нужно обрабатывать как результат бизнес-валидации, а не только как HTTP-успех. При 200 в ответе могут быть:

• storedNomenclatures — сохраненные вариации с Lamoda sku, parentSku и externalSku;
• errors — ошибки атрибутов, включая индекс вариации и код атрибута;
• priceStatuses — результат установки цен, если цены передавались в том же запросе;
• fraudValidationResult — ограничения по акционным ценам.

Старую логику “HTTP 200 значит карточка полностью готова” нужно заменить проверкой этих полей.

Получение товаров

Изображения

POST /v2/nomenclatures/{sku}/images заменяет JSON-RPC nomenclature-images.update.

• sellerId обязателен в теле запроса.
• Максимум 8 изображений за запрос.
• Можно передать новый файл в base64 или сослаться на существующий imageId.
• Порядок изображений задается индексами.

{
  "sellerId": "242541217",
  "images": [
    {
      "index": 1,
      "file": "/9j/4AAQSkZJRgABAQEBLAEsAAD..."
    },
    {
      "index": 2,
      "imageId": "existing-image-id"
    }
  ]
}

Для каждого элемента должен быть заполнен либо file, либо imageId. Если передаете file, используйте JPG/JPEG до 5 МБ.

Цены

Одна цена

POST /api/v2/nomenclature-price

{
  "sellerId": "242541217",
  "country": "RU",
  "parentSku": "MP002XW0J7E6R",
  "price": {"amount": 199900, "currency": "RUB"},
  "salePrice": {"amount": 149900, "currency": "RUB"},
  "saleStart": "2025-06-01T00:00:00.000Z",
  "saleEnd": "2025-06-30T23:59:59.000Z",
  "force": false
}

Массовое обновление

POST /api/v2/nomenclatures-prices

{
  "sellerId": "242541217",
  "country": "RU",
  "prices": [
    {
      "parentSku": "MP002XW0QCHC",
      "price": {"amount": 199900, "currency": "RUB"},
      "salePrice": {"amount": 149900, "currency": "RUB"},
      "saleStart": "2025-06-01T00:00:00.000Z",
      "saleEnd": "2025-06-30T23:59:59.000Z"
    },
    {
      "parentSku": "MP002XW0ZJW1",
      "needAutoConversion": true
    }
  ],
  "force": false
}

force=true может удалить товар из акции, если новая цена не соответствует условиям акции. Включайте его только как осознанное действие пользователя или бизнес-правила, а не по умолчанию.

Ответ цены нужно проверять как бизнес-результат:

• для POST /v2/nomenclature-price смотрите priceStatus.code: OK, ERROR, PROCESSING или QUARANTINE;
• если вернулся fraudValidationResult, цена конфликтует с условиями акции;
• для POST /v2/nomenclatures-prices проверяйте successCount, errorCount, errors[] и fraudValidationResults[];
• не считайте всю пачку успешной только по HTTP status.

Для чтения цен и ограничений используйте GET /v2/nomenclatures-sell-values, для минимальных цен — GET /v2/minimal-prices.

Активация продаж

POST /v2/nomenclatures-activation-status заменяет JSON-RPC nomenclatures.update-activation.

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

• sellerId;
• status: true для активации или false для деактивации;
• country;
• один из наборов идентификаторов: skus, externalSkus, parentSkus, externalParentSkus.

{
  "sellerId": "242541217",
  "status": true,
  "country": "RU",
  "parentSkus": ["MP002XW0QCHCR"]
}

Ответ содержит массив errors для товаров, по которым статус не удалось обновить. Не считайте операцию успешной для всего списка, пока не проверили этот массив.

Остатки

FBS

Чтение: GET /v2/fbs/stocks. Обновление: POST /v2/fbs/stocks.

{
  "sellerId": "12345",
  "data": [
    {"sku": "MP002XW0ZJWMR4042", "quantity": 2},
    {"sku": "MP002XW0ZJWMR4850", "quantity": 0}
  ]
}

За один запрос можно передать до 100 SKU. Количество трактуется как доступное для продажи, без резервов.

Правила для WMS-интеграций:

• обновление FBS-остатка перезаписывает абсолютное доступное количество по Lamoda sku;
• GET /v2/fbs/stocks фильтрует только по Lamoda sku и принимает до 100 SKU за запрос;
• sellerSku, externalSku и warehouseCode для FBS-остатков не используются;
• если передаете список sku, не рассчитывайте на пагинацию как на способ обхода всего каталога.

FBO

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

• GET /v2/fbo/stocks;
• GET /v2/fbo/stocks/illiquid.

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

Для FBO используйте фильтры warehouseCode, sku, externalSku, withZeroQuantity. Заблокированные и неликвидные остатки проверяйте отдельно через GET /v2/fbo/stocks/illiquid: в ответе есть причина блокировки (reason) и описание (reasonDescription).

См. также

• Переход на Lamoda Seller API v2
• Общие изменения контракта
• Справочник соответствия методов
• Каталог: карточки товаров и цены
• Заказы, FBS и этикетки