retailCRM Documentation

ICML format

ICML format allows to upload technical information on items into the system (ID and XML ID of items, information on leftover stock), and also the complicated structure of catalogs with offers (SKU). You can generate the uploading file yourself on the side of web-store according to description below. For number of CMS there are ready-made integration modules, which can generate ICML with catalog.

Format description

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2013-06-20 10:09:18"> 
    <shop> 
        <name>Web-store</name> 
        <company>Web-store</company> 
        <categories> 
            <category id="2">Office furniture</category> 
            <category id="3" parentId="2">Shelvings</category> 
            <category id="4" parentId="2">Workplaces</category> 
            <category id="5" parentId="2">Chairs and armchairs</category> 
            <category id="6">Cushioned furniture</category> 
            <category id="7" parentId="6">Sofas</category> 
            <category id="8" parentId="6">Beds</category> 
            <category id="9">Garden furniture</category> 
            <category id="10">Mirrors</category> 
            <category id="11">Lighting</category> 
            <category id="12">Textile</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>Shelving with 2 sections</name> 
                <xmlId>82</xmlId> 
                <productName>Shelving with 2 sections</productName> 
                <param name="Vendor code" code="article">789789</param> 
                <param name="Size" code="size">two-tier</param> 
                <param name="Color" code="color">white</param> 
                <vendor>Abagure</vendor> 
                <param name="Weight" code="weight">50 kg</param> 
                <unit code="pcs" name="Piece" sym="pcs." />
                <vatRate>18</vatRate>
                <dimensions>100/50.8/150</dimensions>
                <barcode>012485ab</barcode>
            </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>Shelving with 2 sections (orange)</name> 
                <xmlId>83</xmlId> 
                <productName>Shelving with 2 sections</productName> 
                <param name="Vendor code" code="article">789789</param>
                <param name="Size" code="size">two-tier</param> 
                <param name="Color" code="color">black</param> 
                <vendor>Cologio</vendor> 
                <param name="Weight" code="weight">60 kg</param>  
                <unit code="pcs" name="Piece" sym="pcs." />
                <vatRate>none</vatRate>
                <dimensions>100/50.8/150</dimensions>
                <barcode>012485ab</barcode>
            </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>Linen cloth</name>
                <xmlId>66</xmlId>
                <productName>Linen cloth</productName>
                <param name="Vendor code" code="article">151642</param>
                <param name="Width" code="width">150</param> 
                <param name="Color" code="color">beige</param> 
                <param name="Weight" code="weight">2.05</param>
                <unit code="meter" name="Meter" sym="m" />
                <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>Rocking chair</name>
                <xmlId>104</xmlId>
                <productName>Rocking chair</productName>
                <param name="Vendor code" code="article">891081</param>
                <vendor>Riotto</vendor> 
                <unit code="pcs" name="Piece" sym="pcs." />
            </offer>

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

XML-header

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

ICML-file is the XML-document, in the beginning should be located XML-header, for example, <?xml version="1.0" encoding="UTF-8"?>. For the encoding it is recommended to use UTF-8.

Element <yml_catalog>

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

As the root element in ICML format is used the element <yml_catalog>. In one file can be only one such element. The tag has one mandatory attribute date, its value should match date and time of file generation. For storage and transfer several catalogs it is recommended to use several similar xml-documents.

Element <shop>

<shop> 
    <name>My web-store</name> 
    <company>My company</company> 
    <categories> … </categories> 
    <offers> … </offers> 
</shop>

Element <shop> contains description of web-store and catalog. The store is described by the following elements:


The elements should not be duplicated.

Element <categories>

<categories> 
    <category id="2">Office furniture</category> 
    <category id="3" parentId="2">Shelvings</category> 
    <category id="4" parentId="2">Workplaces</category> 
    <category id="5" parentId="2">Chairs and armchairs</category> 
    <category id="6">Cushioned furniture</category> 
    <category id="7" parentId="6">Sofas</category> 
    <category id="8" parentId="6">Beds</category> 
    <category id="9">Garden furniture</category> 
    <category id="10">Mirrors</category> 
    <category id="11">Lighting</category> 
    <category id="12">Textile</category> 
</categories>

In element <categories> there is list of items categories. Element <category> describes one separate category and contains its name. The name should not exceed 255 symbols. Each element must have the attribute id, category id, it should be a unique sequence of symbols not more than 255 symbols. Also each element <category> should contain the attribute parentId parental category id, its value should be equal with one of existing categories. This attribute allows to describe the inserted structure of catalog. If item category description does not contain the attribute parentId, then the category is considered to be the root.

Element <offers>

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

Element <offers> contains the list of web-store items and offers. Each element <offer> describes item and the offer. Element <offers> must be one, and elements <offer> can be as much as desired.

Element <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>Shelving with 2 sections</name> 
    <xmlId>82</xmlId> 
    <productName>Shelving with 2 sections</productName> 
    <param name="Vendor code" code="article">789789</param> 
    <param name="Size" code="size">two-tier</param> 
    <param name="Color" code="color">white</param> 
    <vendor>Riotto</vendor> 
    <param name="Weight" code="weight">50 kg</param> 
    <unit code="pcs" name="Piece" sym="pcs." />
    <vatRate>none</vatRate>
    <dimensions>100/50.8/150</dimensions>
    <weight>50</weight>
    <barcode>012485ab</barcode>
</offer>

Element <offer> contains the fields, describing properties either of item or offer, that allows for element <offer> to be either item or offer. Element contains mandatory attributes id and productId , which match the offer or item id. If there are no offers in web-store, then id can be the same. id and productId must not be longer than 255 symbols. Pay attention that offer id must be unique. If to copy item id to the offer id when generating, then this id can match another offer id. It may lead to irreparable consequences.

<!-- Offer id conflict. -->
<offer id="115" productId="43" quantity="16"> … </offer>
<offer id="115" productId="115" quantity="18"> … </offer>

Element <offer> may consist the attribute quantity, which matches item (offer) quantity at the warehouse. For each offer the quantity can be different. Quantity has to be the whole or fractional number up to 3 signs after a comma, in the range from 0 to 99 999 999.

Offer (item) can be desribed by the following elements:

example: color, size. Maximum code length is 50 symbols. Read also parameters with special handling. The length of item property can not exceed 255 symbols.

Note: weight can be specified by this element and by the parameter with special handling <param name="weight" code="weight"></param>. The last one was left for reverse compatibility. The last value will be applied if product weight is specified at the same time by the element and the parameter. It is possible to specify the measurement unit of weight for the parameter, but the measurement unit for this element is kg by default.


The value of element <xmlId> is used when exchanging of items data and orders data between system and the warehouse system.

Parameters with special handling

In the list there are code of parameters, which have the special handling in system:

<param name="Weight" code="weight">50</param>

It is also permitted to specify weight with short names of units (g, kg, t)

<param name="Weight" code="weight">1.02 kg</param>
<param name="Weight" code="weight">0.2 t</param>

when downloading the catalog, weight will be transferred to gramms, since the gram is the weight unit in system.


PrintEditHistory
Page last modified on December 20, 2017, at 09:53 AM