REST: товарный каталог (catalog)

Группа методов catalog.* в REST API Битрикс24 управляет товарным каталогом CRM-магазина: товарами и торговыми предложениями (SKU), ценами и типами цен, разделами, складами и остатками. Это не каталог CMS 1С-Битрикс, а сущности инфоблока торгового каталога внутри портала Битрикс24.

Что входит в группу catalog

Каталог в Битрикс24 хранится в инфоблоке торгового каталога, привязанном к CRM. Группа catalog.* даёт объектно-ориентированный доступ к этим данным через REST: у большинства сущностей единообразный набор действий add, update, get, list, delete и getFields.

• catalog.catalog.* — торговые каталоги (список инфоблоков-каталогов и их iblockId);
• catalog.product.* — простые товары и товары с предложениями;
• catalog.product.offer.* — торговые предложения (SKU);
• catalog.section.* — разделы каталога;
• catalog.price.* и catalog.priceType.* — цены и типы цен;
• catalog.store.*, catalog.storeProduct.* — склады и остатки;
• catalog.measure.*, catalog.ratio.*, catalog.vat.* — единицы измерения, коэффициенты фасовки и ставки НДС.

Доступ и обязательное условие

Обращения идут через входящий вебхук или OAuth-приложение. Для методов каталога у токена должно быть право catalog (в интерфейсе — «Торговый каталог»). Базовый URL вебхука выглядит так:

https://portal.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/catalog.product.list

Пример получения каталогов:

POST /rest/1/xxxx/catalog.catalog.list { "select": ["id", "iblockId", "name", "iblockTypeId"] }

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

Товар создаётся методом catalog.product.add. Обязательные поля — iblockId и name. Признак type определяет вид товара: 1 — простой, 3 — товар с торговыми предложениями, 2 — предложение, 4 — услуга, 5 — комплект.

catalog.product.add { "fields": { "iblockId": 14, "name": "Кофемашина Bosch", "type": 1, "vatId": 1, "vatIncluded": "Y", "measure": 5, "purchasingPrice": 18000 } }

В ответе придёт result.element.id — идентификатор товара. Обновление — catalog.product.update с id и изменёнными полями. Пользовательские свойства инфоблока передаются как property123 внутри fields; список доступных полей всегда сверяйте через catalog.product.getFieldsByFilter (нужны iblockId и productType).

Торговые предложения (SKU)

Если товар имеет вариации (цвет, размер), создайте родительский товар с type: 3, а варианты — методом catalog.product.offer.add с указанием parentId:

catalog.product.offer.add { "fields": { "iblockId": 15, "name": "Футболка, L, чёрная", "parentId": { "value": 240 }, "property45": 12 } }

• iblockId предложений отличается от каталога товаров — берите его из catalog.catalog.list (у SKU-инфоблока он свой);
• связка со свойствами вариаций делается через свойства инфоблока предложений;
• для получения предложений товара используйте catalog.product.offer.list с фильтром по parentId.

Цены, типы цен и НДС

Цена — отдельная сущность, привязанная к товару и типу цены. Сначала получите типы цен через catalog.priceType.list (розница, опт и т.д.), затем задайте значение методом catalog.price.add:

catalog.price.add { "fields": { "productId": 240, "catalogGroupId": 1, "price": 24990, "currency": "RUB" } }

Разделы, склады и остатки

Каталог структурируется разделами (catalog.section.add с iblockSectionId для вложенности). Складской учёт включается отдельно; при активном учёте остатки задаются связкой товар–склад:

1. получите склады — catalog.store.list;
2. установите остаток — catalog.storeProduct.add или .update с productId, storeId и amount;
3. для документов прихода и списания используйте группу catalog.document.*.

Для массовой выгрузки удобны фильтры и постраничность: catalog.product.list принимает filter, order, select и параметр start. Ответ содержит total и next; выборка идёт страницами по 50 элементов.

Пакетная загрузка и производительность

При импорте тысяч позиций одиночные вызовы упираются в лимиты (около 2 запросов в секунду и метод оценки нагрузки). Решение — метод batch, объединяющий до 50 команд и умеющий подставлять результат одной команды в другую через $result[...]:

batch { "halt": 0, "cmd": { "p": "catalog.product.add?fields[iblockId]=14&fields[name]=Товар", "pr": "catalog.price.add?fields[productId]=$result[p][element][id]&fields[catalogGroupId]=1&fields[price]=100" } }

• halt определяет, прерывать ли пакет при первой ошибке;
• в ответе result_error покажет, какие команды упали;
• следите за полем time.operating — при приближении к лимиту метода делайте паузу, иначе портал вернёт OPERATION_TIME_LIMIT.

Итог

Группа catalog.* закрывает полный цикл работы с товаром CRM-магазина: каталоги, товары и SKU, цены, разделы, склады и остатки. Ключевые правила — всегда передавать корректный iblockId, сверять поля через getFields и getFieldsByFilter, не плодить дубли цен и грузить объёмы через batch с оглядкой на лимиты.

Если каталог нужно синхронизировать с 1С, сайтом или маркетплейсами без ручного заполнения, мы проектируем и внедряем такие обмены под ключ: маппинг полей, очереди, обработку ошибок и предсказуемую нагрузку. Поможем связать каталог Битрикс24 с вашими системами.