Выгрузка каталога ICML

ICML (Intaro Catalog Markup Language) — XML-формат, которым RetailCRM загружает товарный каталог с сайта. Магазин формирует файл по расписанию и отдаёт его по постоянному URL, а CRM регулярно скачивает его и обновляет номенклатуру, остатки и цены.

Что такое ICML

ICML — это диалект YML, ориентированный на нужды RetailCRM: помимо базовых данных о товаре он поддерживает торговые предложения (вариации), произвольные параметры и связь с внешними идентификаторами. Каталог передаётся не через API, а как статический XML-файл, который CRM забирает по HTTP.

• Направление — из магазина в RetailCRM (импорт номенклатуры);
• Транспорт — HTTP-загрузка файла по URL;
• Кодировка — UTF-8;
• Периодичность — по расписанию, заданному в настройках магазина.

Структура файла

Корневой элемент — <yml_catalog> с атрибутом даты формирования. Внутри располагается <shop>, а в нём два ключевых блока: категории и предложения.

<yml_catalog date="2026-07-16 10:00:00"><shop><categories>...</categories><offers>...</offers></shop></yml_catalog>

Атрибут даты в корне помогает RetailCRM понять, когда каталог был сформирован. Порядок блоков важен: сначала объявляется дерево категорий, затем предложения, которые на эти категории ссылаются. Файл должен быть корректным XML — незакрытый тег или неэкранированный спецсимвол в названии товара прервёт разбор, и загрузка завершится ошибкой. Поэтому спецсимволы вроде амперсанда и угловых скобок в текстовых полях обязательно экранируют или оборачивают в секции CDATA.

Категории

Блок <categories> описывает дерево разделов каталога. Каждая категория — элемент <category> с идентификатором, а вложенность задаётся атрибутом parentId.

<category id="12" parentId="3">Смартфоны</category>

• id — уникальный идентификатор категории;
• parentId — идентификатор родителя (для корневых не указывается);
• текст элемента — название категории.

Идентификаторы категорий должны быть стабильными между выгрузками: по ним RetailCRM сопоставляет разделы и не создаёт дубли при каждом обновлении. Дерево должно быть связным — если предложение ссылается на категорию, её обязательно объявляют в блоке категорий, иначе товар окажется вне структуры каталога.

Торговые предложения offers

Блок <offers> — главная часть файла. Каждый <offer> описывает конкретное торговое предложение с ценой и остатком.

Пример предложения:

<offer id="100-red" productId="100" quantity="5"><price>19990</price><name>Чехол красный</name><categoryId>12</categoryId></offer>

Помимо обязательных полей предложение может нести дополнительные: артикул <vendorCode>, производителя <vendor>, ссылку на страницу товара <url> и несколько изображений отдельными тегами <picture>. Остаток в quantity — целое число; если товара нет в наличии, передают ноль, а не убирают предложение из файла, иначе RetailCRM может расценить это как удаление позиции. Цена указывается числом без разделителей тысяч и символа валюты.

Товары и вариации

ICML различает товар и торговое предложение. Товар — это карточка (например, футболка), а предложения — её вариации (размеры, цвета). Связь задаётся полем productId: несколько предложений с одинаковым productId объединяются в один товар.

• Один товар — одно предложение — простой случай без вариаций;
• Один товар — несколько предложений — товар с размерами или цветами;
• дополнительные характеристики передаются элементами <param> с атрибутом name.

Настройка выгрузки

Со стороны магазина нужно сформировать корректный ICML-файл и отдавать его по постоянному URL. Со стороны RetailCRM — указать этот URL в настройках магазина и задать периодичность загрузки.

1. Реализуйте генерацию ICML на сайте (по расписанию или динамически);
2. Проверьте валидность XML и кодировку UTF-8;
3. Убедитесь, что файл доступен по HTTP без авторизации или с поддерживаемым способом доступа;
4. Пропишите URL в настройках магазина RetailCRM;
5. Запустите пробную загрузку и сверьте результат в каталоге CRM.

Для больших каталогов файл лучше генерировать заранее и кэшировать, а не собирать на каждый запрос — иначе загрузка будет медленной и создаст лишнюю нагрузку на сайт. Полезно вести журнал выгрузок: фиксировать время генерации, число товаров и предложений в файле. Резкое падение количества позиций между выгрузками — верный признак сбоя на стороне сайта, и такую выгрузку лучше не отдавать в CRM, чтобы случайно не обнулить остатки по всему каталогу.

Итог

ICML — простой и надёжный способ держать каталог RetailCRM в актуальном состоянии. Ключевые моменты: правильная структура yml_catalog с категориями и предложениями, различение товара и вариаций через productId, стабильные идентификаторы и корректная настройка URL и расписания.

Мы разрабатываем генерацию ICML на стороне сайта — с учётом больших каталогов, вариаций, остатков в реальном времени и обмена с 1С. Это часть наших интеграционных проектов, где каталог, заказы и учётная система работают как единое целое.