Каталог: карточки товаров и цены

Карточка товара (номенклатура) — это описание товара продавца в каталоге Lamoda: родительский товар вместе с его вариациями (например, размерами).

Эта статья описывает порядок работы с методами API при создании и ведении каталога.

Бизнес-процесс и требования к контенту — в разделе «Работа с товарами» Академии. Детали каждого метода (параметры, поля, значения) смотрите в справочнике по ссылке на метод.

Как устроен процесс

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

Создание и обновление — это один upsert-метод: конкретную операцию выбирает поле requestType (CREATE — создать, UPDATE — обновить существующую карточку).

Порядок работы

1. Определение категории и атрибутов

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

1. GET /v2/nomenclature-categories — выбрать категорию (даёт categoryId).
2. GET /v2/nomenclature-categories/{categoryId}/attributes — обязательные и доступные атрибуты категории.
3. GET /v2/nomenclature-categories/{categoryId}/attributes-mappings — маппинг значений атрибутов.
4. GET /v2/dictionaries/attributes — справочники значений атрибутов.

2. Создание или обновление карточки товара

Карточка создаётся и обновляется одним методом.

За один запрос обрабатывается одна карточка — родитель вместе с вариациями. В теле указываются тип операции (requestType), категория (categoryId), атрибуты родителя (attributes) и вариаций (variationAttributes); цены можно передать здесь же (prices) или отдельными методами (шаг 5).

• POST /v2/nomenclatures — создать или обновить карточку (requestType = CREATE / UPDATE). Успех — код 200 (не 201); в ответе — сохранённые номенклатуры, ошибки по элементам, статусы цен и результат фрод-проверки.

Как собрать тело запроса. Состав attributes не фиксирован контрактом — он зависит от категории, поэтому тело собирается по данным подготовительных запросов шага 1:

1. Возьмите categoryId выбранной категории (шаг 1).
2. Из ответа …/attributes определите, какие атрибуты заполнять: у каждого есть код (code), тип (type) и признаки обязательности — по бизнес-модели (requiredForShipmentTypes), полу/возрастной группе (requiredForGenders) и шаблону создания (requiredForTemplates). Заполните все атрибуты, обязательные для вашего сочетания.
3. Для атрибутов типа DICTIONARY_ENTRY / ARRAY_OF_DICTIONARY_ENTRY значения берите из связанного справочника (его имя — в поле dictionary атрибута, сами значения — в GET /v2/dictionaries/attributes). Допустимые сочетания значений — категории сайта, ТН ВЭД, наименования, размерные шкалы, бренды — в …/attributes-mappings.
4. Соберите nomenclature.attributes: ключ — код атрибута, значение — объект {type, value}.
5. Соберите nomenclature.variationAttributes: один элемент массива — одна вариация (например, размер) в той же структуре {код: {type, value}}; идентификаторы вариации (например, supplierSku) передаются здесь.
6. Укажите requestType (CREATE / UPDATE) и при необходимости prices — суммы в минорных единицах валюты (копейки для RUB/BYN, тиыны для KZT).

Каркас тела запроса (пример из спецификации; реальный состав attributes зависит от категории):

{
  "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"
    }
  ]
}

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

3. Добавление изображений

• POST /v2/nomenclatures/{sku}/images — загрузить изображения для карточки. В теле запроса указываются sku номенклатуры: Lamoda-идентификатор из storedNomenclatures[].sku ответа создания карточки (см. шаг 2). Требования к формату/размеру и структура тела смотрите в справочнике метода. Требования к оформлению фото смотрите в статье «Требования к оформлению фотографий».

4. Управление видимостью карточки

• POST /v2/nomenclatures-activation-status — показать или скрыть товар на сайте.

5. Установка и обновление цен

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

Суммы указываются в минорных единицах (копейки RUB/BYN, тиыны KZT).

• POST /v2/nomenclature-price — установить одну цену.
• POST /v2/nomenclatures-prices — массовая установка цен.
• GET /v2/minimal-prices — минимальные цены (ограничения продажи).
• GET /v2/nomenclatures-sell-values — параметры продажи по номенклатурам.

Как цены и статусы товаров работают со стороны бизнеса — «Работа с ценами и статусами товаров».

6. Чтение каталога

• GET /v2/nomenclatures — список номенклатур (требует обязательный query-параметр country = RU/BY/KZ; без него — 400).
• POST /v2/nomenclatures-search — поиск номенклатур по условиям.
• GET /v2/nomenclatures/{sku}/attributes — атрибуты конкретной карточки.

Особенности

Сквозные особенности, не привязанные к одному методу:

• Создание карточки едино для FBO и FBS — модель выбирается ниже, на этапе логистики.
• Upsert через requestType: повтор после 503 отправляйте с UPDATE, иначе создастся дубль карточки.
• Код HTTP-ответа 200 не гарантирует сохранение/цену — проверяйте errors[], priceStatuses, fraudValidationResult.
• Фрод по цене — только при UPDATE, только RU-цена; на чистом CREATE не срабатывает.
• Суммы цен — в минорных единицах (копейки RUB/BYN, тиыны KZT).
• Порядок проверок метода создания: сначала формат sellerId (400 при ошибке), затем токен (401 при невалидном токене, 403 при чужом sellerId), затем загрузка справочников и валидация тела (400 с details[]), сохранение карточки и — отдельным шагом — простановка цен (503 при сбое downstream).
• Идентификаторы дальше по цепочке: ваш supplierSku вариации в остальных доменах (остатки, поставки, заказы) возвращается в поле externalSku; Lamoda-идентификатор — sku.

См. также

• Начало работы и авторизация
• Продажа со своего склада (FBS)
• Продажа со склада Lamoda (FBO)
• Акции
• Синхронизация и события