Product API

API для управления категориями, шаблонами карточек, брендами и параметрами маркетплейса.

Все методы - POST (RPC-стиль). Write-методы поддерживают идемпотентность через request_key.

Возможности

• Управление деревом категорий (leaf-only для создания товаров)
• Шаблоны карточек по категории (с атрибутами, справочниками значений, группами)
• Поиск и proposal брендов (с модерацией)
• Параметры: общие (из шаблонов) и кастомные (личные продавца)
• Proposal на расширение шаблона категории новым общим параметром (уровень B, модерация)
• Кастомные параметры продавца без модерации (уровень A)

Атрибуты — независимая сущность

Атрибут (attribute) — самостоятельная, глобальная сущность маркетплейса. Он не принадлежит конкретному шаблону или категории. Один и тот же атрибут (с одним и тем же attribute_id) может использоваться в шаблонах разных категорий для абсолютно разных товаров. Например, атрибут color (Цвет) с attribute_id = attr_color присутствует одновременно в шаблонах: - «Телевизоры QLED» (категория cat_qled_tv) — роль variation, значения: чёрный, белый, серебристый - «Кроссовки» (категория cat_sneakers) — роль variation, значения: красный, синий, чёрный, белый - «Чемоданы» (категория cat_luggage) — роль specification, значения: чёрный, синий, красный Шаблон категории (Template) содержит ссылки на атрибуты (по attribute_id), а не их полные определения. Полное определение атрибута (code, name, type, unit, values и т.д.) хранится в глобальном реестре и доступно через attributes/list. В шаблоне для каждого атрибута задаются только template-specific поля: role, required, sort_order, group_id. Это позволяет: - Переиспользовать один атрибут в любом числе категорий без дублирования - Менять определение атрибута в одном месте — изменения подхватываются всеми шаблонами - Сопоставлять товары разных категорий по общим атрибутам (например, фильтр «Цвет» работает для всех категорий)

Терминология

• SKU (sku_id) — минимальная единица учёта складского запаса, конкретная вариация товара (цвет + размер + версия). Остаток — это количество SKU на конкретном Складе. Если берём БУ или восстановленный товар, то это версия, то есть новый SKU.
• SPU (spu_id) — базовая единица, которая объединяет товары с общими ключевыми характеристиками (название, бренд, категория, описание), но без учёта конкретных вариаций (цвета, размера, версии). Проще говоря, это «общая стандартная форма» продукта.
• Номенклатура (nm_id) — отображаемая (tile) в поиске и рекомендациях форма карточки товара. Объединённая до «размеров». Объединение проходит по принципу, что у категории есть список схлопывающихся параметров. Решение о схлопывании принимает витрина.
• PDP — Product Detail Page — отображение товара (SPU), включая возможность переключения всех вариантов (всех SKU внутри SPU).
• PLP — Product Listing Page — страница списка товаров. Показывает множество карточек товаров (tiles) в виде сетки или списка. Разбивку товаров на PLP (какие nm_id показывать) решает маркетплейс, но в рамках одного SPU.
• tile — карточка товара в списке товаров. Отображает номенклатуру (nm_id).
• offer (offer_id) — торговое предложение. В общем смысле у одного sku_id может быть несколько offer_id. Как пример, для доставки через FBO — один офер, FBS со склада A — другой офер. Обязательно должен быть offer по умолчанию. На рынке у части игроков понятия sku и offer смешаны, у драгой части гибридный вариант, у некоторых полноценная реализация.