Каталог RetailCRM связывает товары с заказами и аналитикой, а остатки определяют, что реально можно продать. API даёт читать каталог, обновлять остатки и цены торговых предложений, но у наполнения каталога есть особенность: чаще его загружают через ICML, а через API управляют динамикой.
Модель каталога: товар и торговое предложение
В RetailCRM каталог двухуровневый. Товар (product) — карточка с названием и общими свойствами. Торговое предложение (offer) — конкретный вариант товара с ценой и остатком: размер, цвет, комплектация. Именно offer участвует в позициях заказа и в остатках.
- Товар может иметь одно или несколько торговых предложений;
- у каждого offer есть свои идентификаторы:
id,externalId,xmlId; - позиция заказа ссылается именно на offer.
offer, соответствие ищется по одному из идентификаторов. Согласованность xmlId между сайтом и CRM — залог того, что позиции корректно свяжутся с каталогом.Наполнение каталога: ICML против API
Основной способ загрузить и обновлять структуру каталога — ICML (Intaro Catalog Markup Language), XML-выгрузка, которую CRM периодически забирает по URL. Через неё передают товары, предложения, категории, производителей и свойства.
API же удобнее для оперативных изменений, которые не хочется ждать до следующей выгрузки:
- обновление остатков в реальном времени;
- корректировка цен по акции;
- чтение каталога для отображения в интеграции.
| Задача | ICML | API |
|---|---|---|
| Полная структура каталога | Да | Ограниченно |
| Оперативные остатки | Медленно | Да |
| Цены по акции | Медленно | Да |
Чтение товаров и предложений
Каталог читается методом GET /api/v5/store/products. Он возвращает товары вместе с массивом offers и поддерживает фильтры по группам, наличию и идентификаторам:
GET /api/v5/store/products?filter[groupId]=5&filter[active]=1&limit=100
Дополнительно доступны:
/store/product-groups— категории каталога;/store/products/batch/edit— пакетное изменение товаров и предложений;/store/offers/upload— загрузка торговых предложений.
Для больших каталогов применяйте пагинацию и фильтр по группам, чтобы не тянуть всю базу одним проходом.
Обновление остатков
Остатки — самая динамичная часть каталога, и для них есть выделенные методы. Чтение — GET /api/v5/store/inventories, запись — POST /api/v5/store/inventories/upload. Остаток привязан к складу, поэтому в объекте указывают код склада и торговое предложение:
offers=[{"externalId":"SKU-42","stores":[{"code":"main-wh","available":15}]}]
Один вызов принимает до нескольких десятков предложений, что позволяет обновлять остатки пакетами. Склады как справочник читаются через /reference/stores.
Цены и типы цен
RetailCRM поддерживает несколько типов цен (розничная, оптовая, акционная), которые описаны в справочнике /reference/price-types. Цены торговых предложений обновляют методом POST /api/v5/store/prices/upload:
prices=[{"externalId":"SKU-42","prices":[{"code":"base","price":1790}]}]
Так реализуют динамическое ценообразование: интеграция считает цену на своей стороне и выгружает её в нужный тип. При создании заказа цена позиции берётся из initialPrice, поэтому важно, чтобы каталог и заказ использовали согласованные значения.
Связь каталога с заказами и аналитикой
Корректная привязка позиций к offer — это не только удобство, но и основа отчётности. Когда заказ ссылается на реальные торговые предложения:
- работает списание и контроль остатков;
- формируется товарная аналитика — что и сколько продаётся;
- правильно считается маржа при заполненных закупочных ценах.
Если позиция создана без offer (только productName), заказ оформится, но выпадет из товарной аналитики и не повлияет на остатки. Поэтому в продуктивной интеграции стремятся к тому, чтобы каждая позиция ссылалась на каталог по стабильному идентификатору.
Итог
Работа с каталогом через API строится на разделении ролей: структуру грузят через ICML, а динамику — остатки через /store/inventories/upload и цены через /store/prices/upload — через API пакетами. Ключ к корректной аналитике и учёту остатков — стабильные идентификаторы offer, согласованные между сайтом и CRM.
Мы настраиваем выгрузку каталога и синхронизацию остатков между 1С-Битрикс, RetailCRM и учётными системами: генерацию ICML, пакетное обновление цен и остатков, согласование идентификаторов. Если каталог и остатки должны совпадать во всех системах в реальном времени, поможем это выстроить.
Частые вопросы
Чем товар отличается от торгового предложения?
Товар — карточка с общими свойствами, торговое предложение (offer) — конкретный вариант с ценой и остатком. В заказе позиция ссылается именно на offer.
Как лучше наполнять каталог — через API или ICML?
Структуру каталога проще загружать через ICML-выгрузку, а через API оперативно обновлять остатки и цены.
Каким методом обновлять остатки?
POST /api/v5/store/inventories/upload: остаток привязывается к складу через код магазина и торговое предложение. Обновляйте пакетами.
Как задать цену торгового предложения?
Методом /store/prices/upload с указанием кода типа цены из справочника /reference/price-types и значением цены.
Что будет, если товар в заказе не привязан к каталогу?
Заказ создастся по productName, но выпадет из товарной аналитики и не повлияет на остатки. Лучше привязывать позиции к offer.
Как прочитать список складов?
Через справочник /reference/stores. Код склада затем используется при обновлении остатков через inventories/upload.
Как выгрузить большой каталог, не превысив лимиты?
Применяйте пагинацию и фильтр по группам (filter[groupId]), читая каталог частями, а обновления шлите пакетами.
Поможем с настройкой и поддержкой Для разработчиков
Поможем с настройкой, доработкой и поддержкой Для разработчиков.