ICML (IntaroCRM Markup Language) — XML-формат, в котором интернет-магазин отдаёт свой каталог в RetailCRM. Правильная выгрузка — фундамент интеграции: без неё позиции в заказах не свяжутся с товарами, а остатки и аналитика будут пустыми.
Что такое ICML и зачем он нужен
ICML — это диалект YML/XML, разработанный специально для RetailCRM. Файл формируется на стороне сайта, а CRM скачивает его по ссылке и обновляет справочник товаров. Каталог в RetailCRM хранится отдельно от сайта, поэтому без ICML система не знает ни о товарах, ни об остатках.
Наличие каталога в CRM даёт:
- связь позиций заказа с реальными товарами (картинка, артикул, цена);
- актуальные остатки для резервов и триггеров «нет в наличии»;
- корректную товарную аналитику и ABC/XYZ-отчёты;
- подбор товара оператором прямо в карточке заказа.
Структура ICML-файла
Файл состоит из двух ключевых блоков: categories — дерево категорий, и offers — торговые предложения. Минимальный каркас выглядит так:
<yml_catalog date="2026-07-14 10:00"><shop><categories>…</categories><offers>…</offers></shop></yml_catalog>
Каждая категория имеет свой id и, при вложенности, parentId. Каждое предложение — атрибуты id, productId и quantity, а внутри — цену, имя и характеристики.
Товар и торговые предложения
Ключевое отличие ICML — разделение товара (product) и предложения (offer). Товар — это карточка, предложения — её вариации (размер, цвет). Все вариации одного товара имеют одинаковый productId, но разные id.
Пример предложения с вариацией:
<offer id="1024-M" productId="1024" quantity="7"><categoryId>15</categoryId><name>Футболка, M</name><productName>Футболка</productName><price>1290</price><vendorCode>TS-1024-M</vendorCode><param name="Размер">M</param></offer>
| Элемент | Назначение |
|---|---|
id | уникальный код предложения (externalId в CRM) |
productId | объединяет вариации в один товар |
quantity | остаток на складе |
vendorCode | артикул / SKU |
param | характеристики и свойства |
Цены, остатки и склады
Цена передаётся в теге price, закупочная — в purchasePrice (нужна для расчёта маржи в аналитике). Остаток — в атрибуте quantity.
- Если у магазина несколько типов цен, их выгружают как дополнительные ценовые типы, заранее заведённые в RetailCRM;
- Остатки удобно отдавать по конкретному складу, а не суммой, если в CRM ведётся мультискладской учёт;
- Пустой или нулевой остаток — это
quantity="0", а не отсутствие атрибута.
Как формируется выгрузка на сайте
Способ генерации зависит от платформы. У популярных CMS есть готовые модули RetailCRM, которые сами строят ICML; для самописного сайта файл собирают скриптом.
- Скрипт обходит активные товары и категории;
- Формирует XML по структуре ICML;
- Отдаёт файл по постоянной ссылке, например
https://shop.ru/retailcrm/icml; - RetailCRM забирает файл по расписанию.
Для больших каталогов (десятки тысяч позиций) генерацию выносят в фоновую задачу по cron и отдают уже готовый файл, чтобы не строить его на каждый запрос CRM и не ловить таймаут.
Проверка и частые ошибки
Перед подключением к CRM файл стоит проверить вручную и через журнал загрузки RetailCRM (Администрирование → Настройки каталога).
- Файл не парсится — неэкранированные символы
&,<,>в названиях товаров; - Дублируются товары — вариации получили разный
productIdвместо общего; - Слетают остатки — атрибут
quantityне передан, CRM считает остаток неизменным; - Пустые категории — у предложения не указан
categoryIdили он ссылается на несуществующую категорию; - Таймаут загрузки — файл генерируется слишком долго, нужен предпросчёт.
Итог
Корректный ICML — это валидный UTF-8 XML с деревом категорий и торговыми предложениями, где вариации связаны общим productId, а остатки переданы явным quantity. От качества выгрузки зависит вся дальнейшая интеграция: связь заказов с товарами, остатки, резервы и аналитика.
Мы настраиваем выгрузку каталога под особенности конкретного магазина, проверяем структуру и остатки, а затем следим, чтобы файл строился без таймаутов и корректно читался RetailCRM.
Частые вопросы
Чем ICML отличается от обычного YML для Яндекса?
ICML — расширенный формат под RetailCRM: он разделяет товар и торговые предложения через productId, передаёт остатки, закупочные цены и произвольные характеристики. YML для маркетплейсов такой структуры не требует.
Как объединить размеры и цвета в один товар?
Всем вариациям присваивается одинаковый productId, но разные id предложений. Тогда RetailCRM показывает их как один товар с несколькими торговыми предложениями.
Что будет, если убрать товар из выгрузки?
В CRM он останется со старым остатком. Чтобы снять с продажи, выгружайте его с quantity="0" или признаком неактивности, а не удаляйте из файла.
Как часто RetailCRM скачивает ICML?
По расписанию, обычно раз в час. Частоту задают в настройках каталога, но для больших магазинов её не стоит делать слишком высокой из-за нагрузки на генерацию файла.
Почему выгрузка отклоняется с ошибкой формата?
Чаще всего в названиях или характеристиках есть неэкранированные символы & < >. Их нужно заменить на сущности или обернуть в CDATA, чтобы XML стал валидным.
Нужно ли передавать закупочную цену?
Не обязательно, но без purchasePrice RetailCRM не сможет считать маржинальность в аналитике. Если нужны отчёты по прибыли, закупочную цену стоит выгружать.
Как ускорить выгрузку большого каталога?
Генерируйте файл заранее по cron и отдавайте готовый статический ICML, а не стройте его на каждый запрос CRM. Так вы избежите таймаутов на десятках тысяч позиций.
Поможем с настройкой и поддержкой RetailCRM
Поможем с настройкой, доработкой и поддержкой RetailCRM.