retailCRM Документация

Формат ICML

Формат ICML является расширением формата YML. Он позволяет выгружать техническую информацию о товарах в систему (ID и XML ID товаров, информация об остатках), а также сложную структуру каталогов с торговыми предложениями (SKU). Вы можете генерировать файл выгрузки самостоятельно на стороне вашего интернет-магазина в соответствии с описанием ниже. Для ряда CMS есть готовые модули интеграции, которые умеют генерировать ICML с каталогом товаров.

Описание формата

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2013-06-20 10:09:18"> 
    <shop> 
        <name>Интернет-магазин</name> 
        <company>Интернет-магазин</company> 
        <categories> 
            <category id="2">Офисная мебель</category> 
            <category id="3" parentId="2">Стеллажи</category> 
            <category id="4" parentId="2">Рабочие места</category> 
            <category id="5" parentId="2">Стулья и кресла</category> 
            <category id="6">Мягкая мебель</category> 
            <category id="7" parentId="6">Диваны</category> 
            <category id="8" parentId="6">Кровати</category> 
            <category id="9">Мебель для сада</category> 
            <category id="10">Зеркала</category> 
            <category id="11">Освещение</category> 
            <category id="12">Текстиль</category> 
        </categories> 
        <offers> 
            <offer id="115" productId="43" quantity="16"> 
                <url>http://testbitrix.test/catalog/shelves/rack_2_sectional/</url> 
                <price>14000.00</price> 
                <purchasePrice>13200.00</purchasePrice> 
                <categoryId>3</categoryId> 
                <picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec6589.JPG</picture> 
                <name>Стеллаж 2-х секционный</name> 
                <xmlId>82</xmlId> 
                <productName>Стеллаж 2-х секционный</productName> 
                <param name="Артикул" code="article">789789</param> 
                <param name="Размер" code="size">двухъярусный</param> 
                <param name="Цвет" code="color">белый</param> 
                <vendor>Abagure</vendor> 
                <param name="Вес" code="weight">50 кг</param>
                <unit code="pcs" name="Штука" sym="шт." /> 
                <vatRate>18</vatRate>
            </offer>

            <offer id="116" productId="43" quantity="25"> 
                <url>http://testbitrix.test/catalog/shelves/rack_2_sectional/</url> 
                <price>14500.00</price> 
                <purchasePrice>11000.00</purchasePrice> 
                <categoryId>3</categoryId> 
                <picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec1501.JPG</picture> 
                <name>Стеллаж 2-х секционный (оранжевый)</name> 
                <xmlId>83</xmlId> 
                <productName>Стеллаж 2-х секционный</productName> 
                <param name="Артикул" code="article">789789</param>
                <param name="Размер" code="size">двухъярусная</param> 
                <param name="Цвет" code="color">черный</param> 
                <vendor>Cologio</vendor> 
                <param name="Вес" code="weight">60 кг</param>  
                <unit code="pcs" name="Штука" sym="шт." />
                <vatRate>none</vatRate>
            </offer>

            <offer id="253" productId="155" quantity="20"> 
                <url>http://testbitrix.loc/catalog/textile/sheet_beige/</url>
                <price>200.00</price>
                <purchasePrice>175.00</purchasePrice> 
                <categoryId>12</categoryId>
                <picture>http://testbitrix.loc/upload/iblock/be7/be7139e39cda62e8c032f3b2ed0106e4.JPG</picture>
                <name>Ткань льняная бежевая</name>
                <xmlId>66</xmlId>
                <productName>Ткань льняная бежевая</productName>
                <param name="Артикул" code="article">151642</param>
                <param name="Ширина" code="width">150</param> 
                <param name="Цвет" code="color">бежевый</param> 
                <unit code="meter" name="Метр" sym="м" />
                <vatRate>10</vatRate>
            </offer>

            <offer id="56" productId="56" quantity="30">
                <productActivity>N</productActivity>
                <url>http://testbitrix.loc/catalog/summer_collection/rocker/</url>
                <price>4250.00</price>
                <categoryId>9</categoryId>
                <picture>http://testbitrix.loc/upload/iblock/68b/68b955690e0f1f9dacb96cc4248e9c44.jpg</picture>
                <name>Кресло-качалка</name>
                <xmlId>104</xmlId>
                <productName>Кресло-качалка</productName>
                <param name="Артикул" code="article">891081</param>
                <vendor>Riotto</vendor> 
                <unit code="pcs" name="Штука" sym="шт." />
            </offer>

        </offers> 
    </shop> 
</yml_catalog>

XML-заголовок

<?xml version="1.0" encoding="..."?>

ICML-файл является XML-документом, в его начале следует разместить XML-заголовок, например, <?xml version="1.0" encoding="UTF-8"?>. В качестве кодировки рекомендуется использовать UTF-8.

Элемент <yml_catalog>

<yml_catalog date="2013-08-08 17:00">
    <shop>
    ...
    </shop>
</yml_catalog>

В качестве корневого элемента в формате ICML используется элемент <yml_catalog>. В одном файле может находится только один такой элемент. Тег имеет один обязательный атрибут date, значение которого должно соответствовать дате и времени генерации файла. Для хранения и передачи нескольких каталогов рекомендуем использовать несколько подобных xml-документов.

Элемент <shop>

<shop> 
    <name>Мой интернет-магазин</name> 
    <company>Моя компания</company> 
    <categories> … </categories> 
    <offers> … </offers> 
</shop>

Элемент <shop> содержит описание интернет-магазина и каталога товаров. Магазин описывается следующими элементами:


Все элементы не должны дублироваться.

Элемент <categories>

<categories> 
    <category id="2">Офисная мебель</category> 
    <category id="3" parentId="2">Стеллажи</category> 
    <category id="4" parentId="2">Рабочие места</category> 
    <category id="5" parentId="2">Стулья и кресла</category> 
    <category id="6">Мягкая мебель</category> 
    <category id="7" parentId="6">Диваны</category> 
    <category id="8" parentId="6">Кровати</category> 
    <category id="9">Мебель для сада</category> 
    <category id="10">Зеркала</category> 
    <category id="11">Освещение</category> 
    <category id="12">Текстиль</category> 
</categories>

В элементе <categories> содержится список категорий товаров интернет-магазина. Элемент <category> описывает одну отдельную категорию и содержит ее название. Название не должно превышать 255 символов. Каждый элемент должен иметь атрибут id — идентификатор категории, он должен быть уникальной последовательностью символов не длиннее 255 знаков. Также каждый элемент <category> может содержать атрибут parentId — идентификатор родительской категории, его значение должно быть одно из идентификаторов существующих категорий. Этот атрибут позволяет описывать вложенную структуру каталога. Если описание категории товара не содержит атрибут parentId, категория считается корневой.

Элемент <offers>

<offers>
    <offer> … </offer>
    … 
</offers>

В элементе <offers> содержится список товаров и товарных предложений интернет-магазина. Каждый элемент <offer> описывает товар и торговое предложение. Элемент <offers> должен быть в единственном экземпляре, а элементов <offer> может быть сколь угодно много.

Элемент <offer>

<offer id="115" productId="43" quantity="16"> 
    <url>http://testbitrix.test/catalog/shelves/rack_2_sectional/</url> 
    <price>14000.00</price> 
    <purchasePrice>13200.00</purchasePrice> 
    <categoryId>3</categoryId> 
    <picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec6589.JPG</picture> 
    <name>Стеллаж 2-х секционный</name> 
    <xmlId>82</xmlId> 
    <productName>Стеллаж 2-х секционный</productName> 
    <param name="Артикул" code="article">789789</param> 
    <param name="Размер" code="size">двухъярусная</param> 
    <param name="Цвет" code="color">белый</param> 
    <vendor>Riotto</vendor> 
    <param name="Вес" code="weight">50 кг</param> 
    <unit code="pcs" name="Штука" sym="шт." />
    <vatRate>none</vatRate>
</offer>

Элемент <offer> содержит поля описывающие свойства как товара, так и торгового предложения, что дает возможность элементу <offer> быть как товаром, так и торговым предложением. Элемент содержит обязательные атрибуты id и productId , которые соответствуют идентификаторам торгового предложения и товара. В случае если в интернет-магазине отсутствуют торговые предложения, то идентификаторы могут совпадать. id и productId должны быть не длиннее 255 символов. Просим вас обратить внимание, что идентификатор торгового предложения должен быть уникальным, и если при генерации скопировать идентификатор товара в идентификатор торгового предложения, то идентификатор может совпасть с идентификатором другого торгового предложения, это может привести к неисправимым последствиям.

<!-- Конфликт идентификаторов торговых предложений. -->
<offer id="115" productId="43" quantity="16"> … </offer>
<offer id="115" productId="115" quantity="18"> … </offer>

Элемент <offer> может содержать атрибут quantity, который соответствует количеству товара (торгового предложения) на складе. Для каждого торгового предложения может быть свое количество на складе. Количество должно быть целым или дробным числом с точностью до 3 знаков после запятой, в интервале от 0 до 99 999 999.

Торговое предложение (товар) описывается следующими элементами:

пример: color, size. Максимальная длина кода 50 символов. См. также параметры со специальной обработкой. Длина значения свойства товара не должна превышать 255 символов.


Значение элемента <xmlId> используется при обмене со складской системой (1C, МойСклад) данными о товарах и заказах.

Параметры со специальной обработкой

В списке представлены code параметров, которые имеют специальную обработку в системе:

Обратите внимание, что поле description в системе не выводится. Его можно использовать в twig-шаблонах. Например, для вывода в печатных формах.

<param name="Вес" code="weight">50</param>

также допускается указание значений веса с указанием сокращенных единиц измерения веса (г, кг, ц, т)

<param name="Вес" code="weight">1.02 кг</param>
<param name="Вес" code="weight">0.2 т</param>

при загрузке каталога вес будет переведен в граммы, т.к. единицей измерения веса в системе являются граммы.


Редакция от 14.07.2017 16:35