Метод catalog.product.add создаёт товар в товарном каталоге Битрикс24. Ключевой момент — товар всегда принадлежит информационному блоку каталога (iblockId), а цены и остатки добавляются отдельными методами. Разбираем обязательные поля, свойства и загрузку картинок.
Где живёт товар в каталоге
Товарный каталог Битрикс24 построен на информационных блоках. Прежде чем создавать товар, нужно знать идентификатор каталога:
catalog.catalog.list— список доступных каталогов (инфоблоков) с ихiblockId;catalog.product.getfieldsbyfilter— набор полей товара в конкретном каталоге, включая пользовательские свойства.
Каждый товар обязательно ссылается на каталог через iblockId. Без корректного идентификатора метод вернёт ошибку. Цены хранятся отдельно (catalog.price), а складские остатки — в модуле складского учёта (catalog.store*).
catalog.product.add с методами CRM-товаров crm.product.*. Первый работает с полноценным товарным каталогом онлайн-магазина, второй — с упрощённым списком товаров CRM.Типы товаров
В каталоге Битрикс24 есть несколько типов товарных сущностей, и под каждую — своя группа методов:
| Тип | Метод создания | Назначение |
|---|---|---|
| Простой товар | catalog.product.add | Обычный товар без вариаций |
| Товар с торговыми предложениями | catalog.product.sku.add | Родитель для offer (SKU) |
| Торговое предложение | catalog.product.offer.add | Вариация (цвет, размер) |
| Услуга | catalog.product.service.add | Нематериальная позиция |
Если планируются вариации, создают родителя как SKU, а вариации — методом offer с указанием родительского товара. Для простого товара достаточно catalog.product.add.
Обязательные и основные поля
Минимально необходимы каталог и название. Основные поля:
| Поле | Назначение |
|---|---|
| iblockId | Идентификатор каталога (обязательно) |
| name | Название товара (обязательно) |
| code | Символьный код (ЧПУ) |
| active | Активность (Y/N) |
| previewText / detailText | Краткое и подробное описание |
| previewPicture / detailPicture | Картинки (через fileContent) |
| measure | Единица измерения |
| vatId / vatIncluded | Ставка НДС и признак включения |
| purchasingPrice | Закупочная цена |
catalog.price.add с указанием типа цены. В catalog.product.add из ценового можно задать лишь закупочную цену.Пример создания товара
Создание простого активного товара в каталоге с iblockId 14:
POST https://portal.bitrix24.ru/rest/1/xxxxx/catalog.product.add.json
{ "fields": { "iblockId": 14, "name": "Кофемолка ручная", "code": "kofemolka-ruchnaya", "active": "Y", "measure": 5, "vatIncluded": "Y" } }Ответ содержит объект element с присвоенным id. Дальше к товару добавляют цену:
catalog.price.add?fields[productId]=920&fields[catalogGroupId]=1&fields[price]=1490&fields[currency]=RUB
Картинки и файловые свойства
Изображения передаются в формате fileContent — массив из имени файла и его содержимого в base64:
{ "fields": { "iblockId": 14, "name": "Кофемолка", "detailPicture": { "fileData": [ "grinder.jpg", "/9j/4AAQSkZJRg..." ] } } }Тот же принцип действует для пользовательских свойств типа «файл». Прочитать сохранённый файл позже помогает catalog.product.download. Формат передачи бинарных данных единый для каталога и других модулей Битрикс24, что упрощает написание общего загрузчика.
Пользовательские свойства товара
Помимо системных полей, у товара есть свойства инфоблока (бренд, цвет, вес). Их состав зависит от конкретного каталога, поэтому перед импортом получают карту полей:
catalog.product.getfieldsbyfilterс параметромiblockId— вернёт системные и пользовательские свойства именно этого каталога;- значения свойств передаются по их символьным кодам прямо в
fields; - для свойств-справочников (привязка к элементам) передаётся идентификатор значения.
Такой подход исключает жёсткую привязку кода к конкретному порталу: карта полей читается динамически.
Практика импорта
- Права catalog. Методам каталога нужно разрешение
catalogу вебхука или приложения. - Batch до 50. Оборачивайте создание товаров в
batch(до 50 команд за вызов), связывая товар, цену и остаток через$result. - Идемпотентность по code. Перед добавлением проверяйте наличие товара через
catalog.product.listпоcode, чтобы не плодить дубли. - Единицы измерения.
measureссылается на справочникcatalog.measure.list. - Лимиты API. Контролируйте частоту запросов и размер тела при массовой загрузке картинок.
Итог
Метод catalog.product.add создаёт товар, обязательно привязанный к каталогу через iblockId, с названием и опциональными полями. Цены, остатки и торговые предложения добавляются отдельными методами, картинки — через fileContent в base64, а пользовательские свойства читаются динамически по карте полей каталога.
Наладить регулярный обмен каталогом между сайтом, 1С и Битрикс24 — с маппингом свойств, обработкой картинок, дедупликацией и очередями — задача для полноценного модуля обмена. Мы проектируем и разрабатываем такие импортёры и интеграции под конкретный каталог заказчика.
Частые вопросы
Какие поля обязательны для catalog.product.add?
Обязательны iblockId (идентификатор каталога) и name (название товара). Остальные поля, включая код, активность и описания, опциональны.
Как узнать iblockId каталога?
Список каталогов с их идентификаторами возвращает метод catalog.catalog.list. Именно оттуда берут значение для поля iblockId нового товара.
Можно ли задать цену прямо в catalog.product.add?
Продажную цену — нет, она задаётся отдельно через catalog.price.add с указанием типа цены. В самом товаре можно указать только закупочную цену purchasingPrice.
Как загрузить картинку товара через REST?
Изображение передаётся в поле detailPicture или previewPicture в формате fileContent — массив из имени файла и содержимого в base64.
Чем отличается создание товара с вариациями?
Для вариаций родителя создают методом catalog.product.sku.add, а сами варианты — catalog.product.offer.add с привязкой к родителю. Простой товар создаётся через catalog.product.add.
Как передать пользовательские свойства товара?
Их состав зависит от каталога и читается через catalog.product.getfieldsbyfilter. Значения передаются по символьным кодам свойств прямо в fields.
Какие права нужны методам каталога?
Вебхуку или приложению требуется разрешение catalog. Без него catalog.product.add и связанные методы вернут ошибку доступа.
Поможем с настройкой и поддержкой Для разработчиков
Поможем с настройкой, доработкой и поддержкой Для разработчиков.