Сквозной сценарий · Руководства
Каталог и карточки товаров
Поиск товаров, получение полной карточки, создание модели, справочники брендов и категорий и работа с параметрами маркетплейсов.
В SelSup карточка строится иерархически — модель, варианты цвета и конечные товары или размеры. Для синхронизации важно хранить идентификаторы каждого уровня.
PIM, ERP, 1С и товарные интеграции01
Найти товар и получить полную карточку
Поиск товаров возвращает облегчённые данные для списка. Сохраняйте productId, skuId, viewId и modelId отдельно — они относятся к разным сущностям и не взаимозаменяемы.
Для полной структуры карточки запросите модель по modelId. Если нужны значения динамических параметров, включите соответствующий параметр запроса, описанный у метода модели.
- 1
Найдите товары страницами
Используйте стабильную сортировку по ID и не включайте count на каждой странице.
- 2
Возьмите идентификатор модели
Из результата поиска получите modelId или view.model.id в зависимости от представления ответа.
- 3
Загрузите полную модель
Полная модель содержит варианты и размеры, необходимые для редактирования карточки.
02
Создать минимальную карточку
У модели должен быть как минимум один вариант и один конечный товар, даже если бизнес не использует цвета и размеры.
Сначала найдите или создайте бренд и категорию. Сохраняйте их идентификаторы в своей системе, чтобы не создавать дубликаты при каждом импорте.
Артикул модели должен быть стабильным внешним ключом. Если штрих-коды не переданы, SelSup может сформировать их, но для двусторонней синхронизации лучше явно хранить назначенные значения.
Общая модель содержит служебные поля. Передавайте только поля, перечисленные в теле запроса актуальной документации.
{
"article": "MODEL-001",
"title": "Базовая футболка",
"brandId": 8124,
"categoryId": 27640,
"organizationId": 1,
"views": [
{
"color": "Черный",
"sizes": [
{
"name": "Базовая футболка, M",
"size": "M"
}
]
}
]
}
03
Обновить карточку без потери данных
Для частичного изменения используйте PATCH на конечном товаре, когда нужный метод поддерживает объединение данных. PUT модели рассматривайте как полную замену редактируемой структуры.
Перед PUT сначала получите актуальную модель, измените только нужные поля в своей копии и отправьте согласованную структуру. Не используйте старый ответ, если карточку могли изменить в кабинете.
Если API не предоставляет версию сущности или ETag, уменьшайте окно между чтением и записью и выполняйте контрольное чтение после сохранения.
04
Параметры и справочные значения
Значения параметров могут находиться на уровне категории, модели, варианта или товара. Более конкретный уровень имеет приоритет, но конкретное правило передачи зависит от маркетплейса.
Для multiValueAllowed передавайте несколько значений одного paramId. Форму значения выбирайте по valueType, а для displayType=SUGGEST сначала получите разрешённую опцию.
Категории и параметры маркетплейсов меняются. Обновляйте их регулярно и не полагайтесь на сохранённое название как на постоянный ключ.
GET https://params.selsup.ru/knowledge/getParams?ozonCategoryId=91025609
GET https://options.selsup.ru/option/fetchOption?paramId=60019&query=хлопок&limit=10