Загрузка каталога в систему через 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">
   <name>Стеллажи</name>
   <picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec6589.JPG</picture> 
   <picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec6590.JPG</picture> 
  </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> 
   <picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec6590.JPG</picture> 
   <picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec6591.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>
   <dimensions>100/50.8/150</dimensions>
   <barcode>012485ab</barcode>
   <markable>Y</markable>
  </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>
   <dimensions>100/50.8/150</dimensions>
   <barcode>012485ab</barcode>
   <markable>Y</markable>
  </offer>
  <offer id="253" productId="155" quantity="20">
   <activity>Y</activity>
   <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>
   <weight>2.05</weight>
  </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> содержит описание интернет-магазина и каталога товаров. Магазин описывается следующими элементами:

<name> — название интернет-магазина; Максимальная длина 255 символов;
<company> — название компании;
<categories> — контейнер, который содержит категории товаров;
<offers> — контейнер, который содержит описания всех товаров интернет-магазина.

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

Элемент <categories>

<categories> 
 <category id="2">Офисная мебель</category> 
 <category id="3" parentId="2">
  <name>Стеллажи</name>
  <picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec6589.JPG</picture> 
  <picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec6590.JPG</picture> 
 </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, категория считается корневой. Также категория может быть описана следующими элементами:

  • <name> — название категории, максимальная длина 255 символов.
  • <picture> — URL картинки категории. Тег может повторяться. Максимальная длина ссылки 2000 символов.

Элемент

<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> 
 <picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec6590.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>
 <dimensions>100/50.8/150</dimensions>
 <weight>50</weight>
 <barcode>012485ab</barcode>
 <markable>Y</markable>
</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.

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

<activity> — показатель активности торгового предложения. Элемент не является обязательным. Если он не указан, то торговое предложение считается активным. Для неактивного торгового предложения необходимо передавать N, в остальных случаях можно передать Y или опустить элемент.

<productActivity> — показатель активности товара. Элемент не является обязательным. Если он не указан, то товар считается активным. Для деактивации товара необходимо указывать данный элемент у всех торговых предложений этого товара.

<url> — страница торгового предложения (товара) в интернет-магазине. Важно указывать корректный протокол (http:// или https://) и домен (с www или без него). Данный URL используется для определения просмотренных клиентом товаров в рамках интеграции с Universal Analytics; Максимальная длина ссылки 2000 символов;

<price> — цена торгового предложения (товара); Цена может быть целой или дробной с точностью до 2 знаков после запятой в промежутке от 0 до 99 999 999;

<purchasePrice> — закупочная цена торгового предложения (товара), не является обязательной; При отсутствии тега в файле значение не будет сбрасываться; Закупочная цена может быть целой или дробной с точностью до 2 знаков после запятой в промежутке от 0 до 99 999 999;

<categoryId> — идентификатор категории, к которой принадлежит торговое предложение (товар). Если торговое предложение (товар) находится в нескольких категориях, то таких элементов может быть несколько;

<picture> — URL картинки торгового предложения (товара), тег может повторяться, не является обязательным. Используется для отображения превью изображений. Можно указывать изображения в формате jpg, png размером не более 2Мб. Важно указывать корректный протокол (http:// или https://) и домен (с www или без него), иначе система не сможет отобразить превью товаров. Также важно, чтобы ссылка на товар была прямой и при переходе на нее не производились редиректы. Максимальная длина ссылки 2000 символов;

<name> — название торгового предложения; Максимальная длина 255 символов;

<productName> — название товара; Максимальная длина 255 символов;

<xmlId> — внешний идентификатор товара, элемент не является обязательным — в случае если интернет-магазин использует выгрузку номенклатуры товаров из складской системы (1С, МойСклад), то значение этого элемента соответствует идентификатору товара в данной системе; Поле представляет собой последовательность символов длиной не более 255;

<param name="..." code="..."> — параметр товара, где:

name — название параметра товара; Максимальная длина 255 символов;

code — буквенно-цифровой код параметра, допустимые символы: a-Z0-9_, прочие символы будут обрезаны пример: color, size. Максимальная длина кода 50 символов. См. также параметры со специальной обработкой. Длина значения свойства товара не должна превышать 255 символов.

<vendor> — производитель товара, элемент не является обязательным; Максимальная длина 255 символов;

<unit> - единица измерения для товара, элемент не является обязательным;

code - буквенно-цифровой код единицы измерения, допустимые символы: a-Z0-9_-, первый символ должен быть a-z; Максимальная длина 255 символов;

name - полное название единицы измерения, необязательный элемент - в случае отсутствия, при создании, в качестве названия берется код, для существующей единицы измерения передавать не требуется; Максимальная длина 255 символов;

sym - краткое название единицы измерения, необязательный элемент - в случае отсутствия, при создании, в качестве краткого названия берется код, для существующей единицы измерения передавать не требуется; Максимальная длина 5 символов;

<vatRate> - Ставка налога на добавленную стоимость (НДС) для товара в процентах; Для передачи значения "Без НДС" используйте none; элемент не является обязательным;

<dimensions> - Габариты товара в формате Длина/Ширина/Высота. Единица измерения для каждой размерности - сантиметр. Формат: три положительных числа с точностью до тысячных (0.001), разделитель целой и дробной части - точка. Числа должны быть разделены символом "/" без пробелов. При указании более высокой точности значение автоматически округляется до третьего знака (включительно) в дробной части. Максимально допустимое значение - 999 999 999 см. При загрузке каталога габариты будут переведены в миллиметры, так как единицей измерения габаритов в системе являются миллиметры.

<weight> - Вес товара. Единица измерения - килограмм. Формат: положительное число с точностью 0.001 (или 0.000001, в зависимости от настройки CRM "Точность веса": граммы или миллиграммы соответственно), разделитель целой и дробной части - точка. При указании более высокой точности значение автоматически округляется до третьего знака (включительно) в дробной части. Максимально допустимое значение - 9 999 999 кг. При загрузке каталога вес будет переведен в граммы, так как единицей измерения веса в системе являются граммы.

Примечание

Вес может быть указан как с помощью данного элемента, так и с помощью параметра со специальной обработкой <param name="Вес" code="weight"></param>. Последний был оставлен в целях обратной совместимости. Если для одного и того же товара вес будет указан одновременно и с помощью элемента, и с помощью параметра, то будет взято последнее встретившееся значение. Также обратите внимание на то, что для параметра возможно указание единицы измерения веса, для данного же элемента (<weight>) единица измерения - всегда килограмм, и её указывать не надо.

<barcode> - Штрих-код товара. Может быть указан как с помощью данного элемента, так и с помощью параметра со специальной обработкой <param name="Штрих-код" code="barcode"></param>. Формат: строка длиной до 255 символов включительно, состоящая только из цифр и латинских букв.

<markable> - признак необходимости маркировки товара. Если товар подлежит маркировке, необходимо передать Y, в противном случае нужно передать N или опустить элемент. Если данный признак будет отличаться для торговых предложений одного и того же товара, то будет установлено значение из последнего торгового предложения.

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

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

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

article — артикул торгового предложение; Произвольная строка;
weight — вес торгового предложение в граммах; Вес переведенный в граммы должен быть целым или дробным числом с точностью до 3 знаков после запятой в промежутке от 0 до 9 999 999 999;
description — описание торгового предложения;
barcode — штрих-код торгового предложения.

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

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

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

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

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

Благодарим за отзыв.
Была ли статья полезна?
Нет
  • Рекомендации не помогли
  • Нет ответа на мой вопрос
  • Текст трудно понять
  • Не нравится описанный функционал
Да
Предыдущая статья
Демон Collector
Демон Collector — специализированная системная служба, обеспечивающая тесное взаимодействие системы с пользователями, которые находятся на вашем сайте.
Не нашли ответа на свой вопрос?
Получить помощь
Не нашли ответ на вопрос?
Специалист службы поддержки готов помочь!

Обратная связь

Нажимая на кнопку, вы соглашаетесь с условиями пользовательского соглашения

Сообщение отправлено!

В ближайшее время специалист службы поддержки изучит ваше обращение и ответит вам.

Сообщение не отправлено!

Произошла непредвиденная ошибка. Мы уже уведомлены об инциденте и в ближайшее время всё починим.