Contenido
Importante!
En la tarifa gratuita se pueden gestionar como máximo 10 000 productos y servicios.
El formato ICML es una extensión del formato YML. Permite cargar en el sistema información técnica sobre productos y servicios, como sus ID, XML ID y existencias, además de catálogos complejos con variantes u ofertas comerciales (unidades de mantenimiento de existencias, SKU).
El archivo de exportación puede generarse en la tienda en línea de acuerdo con la descripción siguiente. Para algunos sistemas de gestión de contenidos (CMS) existen módulos de integración que generan archivos ICML con el catálogo de productos.
Descripción del formato
<?xml version="1.0" encoding="UTF-8"?><yml_catalog date="2013-06-20 10:09:18">
<shop>
<name>Tienda en línea</name>
<company>Tienda en línea</company>
<categories>
<category id="2">Muebles de oficina</category>
<category id="3" parentId="2">
<name>Estanterías</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">Puestos de trabajo</category>
<category id="5" parentId="2">Sillas y sillones</category>
<category id="6">Muebles tapizados</category>
<category id="7" parentId="6">Sofás</category>
<category id="8" parentId="6">Camas</category>
<category id="9">Muebles de jardín</category>
<category id="10">Espejos</category>
<category id="11">Iluminación</category>
<category id="12">Textil</category>
</categories>
<offers>
<offer type="service" id="132" productId="54">
<url>http://testbitrix.test/catalog/service/</url>
<price>3000.00</price>
<purchasePrice>1000.00</purchasePrice>
<categoryId>3</categoryId>
<picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec1501.JPG</picture>
<name>Grabado</name>
<xmlId>63</xmlId>
<productName>Grabado</productName>
<param name="Artículo" code="article">1234567</param>
<vatRate>none</vatRate>
</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>
<picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec6591.JPG</picture>
<name>Estantería de 2 secciones</name>
<xmlId>82</xmlId>
<productName>Estantería de 2 secciones</productName>
<param name="Artículo" code="article">789789</param>
<param name="Tamaño" code="size">dos niveles</param>
<param name="Color" code="color">blanco</param>
<vendor>Abagure</vendor>
<param name="Peso" code="weight">50</param>
<unit code="pcs" name="Unidad" sym="ud." />
<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>Estantería de 2 secciones (naranja)</name>
<xmlId>83</xmlId>
<productName>Estantería de 2 secciones</productName>
<param name="Artículo" code="article">789789</param>
<param name="Tamaño" code="size">dos niveles</param>
<param name="Color" code="color">negro</param>
<vendor>Cologio</vendor>
<param name="Peso" code="weight">60</param>
<unit code="pcs" name="Unidad" sym="ud." />
<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>Tela de lino beige</name>
<xmlId>66</xmlId>
<productName>Tela de lino beige</productName>
<param name="Artículo" code="article">151642</param>
<param name="Ancho" code="width">150</param>
<param name="Color" code="color">beige</param>
<unit code="meter" name="Metro" sym="m" />
<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>Sillón mecedora</name>
<xmlId>104</xmlId>
<productName>Sillón mecedora</productName>
<param name="Artículo" code="article">891081</param>
<vendor>Riotto</vendor>
<unit code="pcs" name="Unidad" sym="ud." />
</offer>
</offers>
</shop>
</yml_catalog>Encabezado XML
<?xml version="1.0" encoding="..."?>Un archivo ICML es un documento XML y debe comenzar con un encabezado XML, por ejemplo, <?xml version="1.0" encoding="UTF-8"?>. Se recomienda utilizar la codificación UTF-8.
Elemento <yml_catalog>
<yml_catalog date="2013-08-08 17:00">
<shop>
...
</shop>
</yml_catalog><yml_catalog> es el elemento raíz de ICML. Solo puede existir un elemento de este tipo en cada archivo. Su atributo obligatorio date debe contener la fecha y la hora de generación del archivo.
Para almacenar o transferir varios catálogos, es necesario utilizar varios documentos XML.
Elemento <shop>
<shop>
<name>Mi tienda en línea</name>
<company>Mi empresa</company>
<categories>...</categories>
<offers>...</offers>
</shop>El elemento <shop> contiene la descripción de la tienda en línea y de su catálogo:
<name>— nombre de la tienda en línea; longitud máxima de 255 caracteres.<company>— nombre de la empresa.<categories>— contenedor de las categorías de productos.<offers>— contenedor de las descripciones de todos los productos y servicios de la tienda.
Estos elementos no deben duplicarse.
Elemento <categories>
<categories>
<category id="2">Muebles de oficina</category>
<category id="3" parentId="2">
<name>Estanterías</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">Puestos de trabajo</category>
<category id="5" parentId="2">Sillas y sillones</category>
<category id="6">Muebles tapizados</category>
<category id="7" parentId="6">Sofás</category>
<category id="8" parentId="6">Camas</category>
<category id="9">Muebles de jardín</category>
<category id="10">Espejos</category>
<category id="11">Iluminación</category>
<category id="12">Textil</category>
</categories><categories> contiene la lista de categorías de la tienda. Cada elemento <category> describe una categoría y contiene su nombre, cuya longitud máxima es de 255 caracteres.
Cada categoría debe tener un atributo id: una secuencia única de hasta 255 caracteres. El atributo opcional parentId contiene el identificador de una categoría existente y permite crear una estructura anidada. Si no se especifica parentId, la categoría se considera raíz.
Una categoría también puede contener:
<name>— nombre de la categoría; longitud máxima de 255 caracteres.<picture>— URL de una imagen de la categoría. La etiqueta puede repetirse. La longitud máxima de cada enlace es de 2000 caracteres.
Elemento <offers>
<offers>
<offer>...</offer>
...
</offers><offers> contiene la lista de productos, servicios y variantes de la tienda en línea. Cada elemento <offer> describe un producto o servicio y su variante. El contenedor <offers> debe aparecer una sola vez; la cantidad de elementos <offer> no está limitada.
Elemento <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>Estantería de 2 secciones</name>
<xmlId>82</xmlId>
<productName>Estantería de 2 secciones</productName>
<param name="Artículo" code="article">789789</param>
<param name="Tamaño" code="size">dos niveles</param>
<param name="Color" code="color">blanco</param>
<vendor>Riotto</vendor>
<param name="Peso" code="weight">50</param>
<unit code="pcs" name="Unidad" sym="ud." />
<vatRate>none</vatRate>
<dimensions>100/50.8/150</dimensions>
<weight>50</weight>
<barcode>012485ab</barcode>
<markable>Y</markable>
</offer>
<offer type="service" id="132" productId="54">
<url>http://testbitrix.test/catalog/service/</url>
<price>3000.00</price>
<purchasePrice>1000.00</purchasePrice>
<categoryId>3</categoryId>
<picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec1501.JPG</picture>
<name>Grabado</name>
<xmlId>63</xmlId>
<productName>Grabado</productName>
<param name="Artículo" code="article">1234567</param>
<vatRate>none</vatRate>
</offer><offer> contiene propiedades del producto o servicio y de su variante. Para identificar un producto se puede especificar type="product" y, para un servicio, type="service". Si no se indica el atributo type, se utiliza product.
Los atributos obligatorios son:
id— identificador externo de la variante en el sistema.productId— identificador del producto.
Si la tienda no utiliza variantes, ambos identificadores pueden coincidir. La longitud máxima de id y productId es de 255 caracteres.
Importante!
El identificador de cada variante debe ser único. Si se copia el identificador del producto como identificador de una variante, puede coincidir con el de otra variante y provocar consecuencias irreversibles.
En los servicios, los valores de «Fabricante», «Peso», «Dimensiones» y «Unidad de medida» no se transfieren al sistema al crear ni al editar el servicio.
El siguiente ejemplo muestra un conflicto de identificadores de variantes:
<offer id="115" productId="43" quantity="16">...</offer>
<offer id="115" productId="115" quantity="18">...</offer>El atributo opcional quantity indica las existencias de la variante. Cada variante puede tener una cantidad diferente. El valor debe ser un número entero o decimal, con un máximo de tres decimales, comprendido entre 0 y 99 999 999.
Nota
Las existencias de ICML se transfieren al CRM únicamente cuando está desactivada la opción «Permitir editar Stock» en los ajustes principales del almacén. Consulte «Ajustes principales de almacenes».
Una variante o producto puede describirse mediante los siguientes elementos:
<activity>— indicador de actividad de la variante. Es opcional; si no se especifica, la variante se considera activa. Para desactivarla, se debe enviarN. Para una variante activa se puede enviarYu omitir el elemento.<productActivity>— indicador de actividad del producto. Es opcional; si no se especifica, el producto se considera activo. Para desactivar un producto, se debe incluir este elemento en todas sus variantes.<url>— página de la variante o del producto en la tienda en línea. Se debe especificar correctamente el protocolo (http://ohttps://) y el dominio, conwwwo sin él. La URL se utiliza para determinar qué productos ha visto el cliente en la integración con Google Analytics. Longitud máxima: 2000 caracteres.<price>— precio de la variante o del producto. Puede ser un número entero o decimal con un máximo de dos decimales, comprendido entre 0 y 99 999 999.
Transmisión de tipos de precio en la etiqueta <price>
La etiqueta <price> admite el atributo opcional type, que contiene el código simbólico de un tipo de precio del sistema.
<price>1000.00</price>
<price type="base">1000.00</price>
<price type="sale">900.00</price>El procesamiento depende de la opción «Actualizar los tipos de precio de los productos desde ICML», situada en Configuración → Tiendas → Tiendas → [tienda] → Catálogo.
Si la opción está desactivada:
- se ignora el atributo
type; - todos los valores de
<price>se guardan en el tipo de precio base; - si un mismo
<offer>contiene varias etiquetas<price>, se guarda el último valor para el tipo de precio base; - si no hay etiquetas
<price>, no se crean precios.
Si la opción está activada:
<price type="...">guarda el precio en el tipo cuyo código coincida, siempre que ese tipo exista y esté activo;<price>sin el atributotypeguarda el valor en el tipo de precio base;- si el código no existe o el tipo está inactivo, no se crea el precio y el registro de validación muestra un mensaje como
Unknown price type code "sale"; - si un
<offer>contiene varios valores para un mismo tipo de precio, se guarda el último; - si se envían simultáneamente
<price type="base">y<price>sintype, se utiliza el valor de<price type="base">y se ignoran para el tipo base los valores sin atributo; - si durante la importación se transmite al menos un precio para un
<offer>, sus precios se sincronizan con el archivo ICML y se eliminan los que no estén presentes en el archivo nuevo; - si durante la importación no se transmite ningún precio para un
<offer>, sus precios existentes no se eliminan.
Nota
Los precios cargados mediante ICML se guardan en la moneda del tipo de precio base.
<purchasePrice>— precio de compra de la variante o del producto. Es opcional; si la etiqueta no está presente, el valor existente no se restablece. Puede ser un número entero o decimal con un máximo de dos decimales, comprendido entre 0 y 99 999 999.<categoryId>— identificador de una categoría existente a la que pertenece la variante o el producto. Si pertenece a varias categorías, se pueden incluir varios elementos.<picture>— URL de una imagen de la variante o del producto. Es opcional y puede repetirse. Se admiten imágenes JPG y PNG de hasta 2 MB. La URL debe incluir el protocolo y el dominio correctos, ser directa y no producir redirecciones; de lo contrario, el sistema no podrá mostrar la vista previa. Longitud máxima: 2000 caracteres.<name>— nombre de la variante; longitud máxima de 255 caracteres.<productName>— nombre del producto; longitud máxima de 255 caracteres.<xmlId>— identificador externo opcional del producto; longitud máxima de 255 caracteres. Cuando la tienda exporta la nomenclatura desde un sistema de almacén, como 1C o MoySklad, este valor corresponde al identificador del producto en dicho sistema. También se utiliza al intercambiar datos de productos y pedidos.<param name="..." code="...">— parámetro del producto:name— nombre del parámetro; longitud máxima de 255 caracteres.code— código alfanumérico. Se admiten los caracteresa-Z0-9_; los demás se recortan. Ejemplos:colorysize. Longitud máxima: 50 caracteres. Consulte los parámetros con tratamiento especial. El valor del parámetro no debe superar los 255 caracteres.
<vendor>— fabricante del producto. Es opcional; longitud máxima de 255 caracteres.<unit>— unidad de medida opcional del producto:code— código alfanumérico de la unidad. Se admiten los caracteresa-Z0-9_-y el primer carácter debe pertenecer al intervaloa-z. Longitud máxima: 255 caracteres.name— nombre completo opcional. Al crear una unidad, si no se especifica, se utilizacode. No es necesario enviarlo para una unidad existente. Longitud máxima: 255 caracteres.sym— abreviatura opcional. Al crear una unidad, si no se especifica, se utilizacode. No es necesario enviarla para una unidad existente. Longitud máxima: 5 caracteres.
<vatRate>— tipo del impuesto sobre el valor añadido (IVA) del producto, expresado como porcentaje. Para indicar «Sin IVA», se utilizanone. Es opcional.<dimensions>— dimensiones del producto en el formato Largo/Ancho/Alto. Cada dimensión se expresa en centímetros. Se deben enviar tres números positivos con una precisión máxima de tres decimales y un punto como separador decimal. Los números se separan mediante/, sin espacios. Si se especifica una precisión mayor, el valor se redondea automáticamente a tres decimales. El valor máximo es de 999 999 999 cm. Al cargar el catálogo, las dimensiones se convierten a milímetros, que es la unidad utilizada en el sistema.<weight>— peso del producto en kilogramos. Debe ser un número positivo con una precisión de0.001o de0.000001, según el ajuste del sistema de gestión de relaciones con clientes (CRM) «Precisión del peso»: gramos o miligramos, respectivamente. El separador decimal es el punto. Los valores que superen la precisión permitida se redondean a la precisión admitida. El valor máximo es de 9 999 999 kg. Al cargar el catálogo, el peso se convierte a gramos.
Nota
El peso puede indicarse mediante
<weight>o mediante el parámetro con tratamiento especial<param name="Peso" code="weight"></param>, conservado por compatibilidad con versiones anteriores. Si se utilizan ambos para un mismo producto, se toma el último valor encontrado. En el parámetro se puede especificar una unidad de peso; en<weight>, la unidad siempre es el kilogramo y no debe indicarse.
<barcode>— código de barras del producto. También puede enviarse mediante el parámetro especial<param name="Código de barras" code="barcode"></param>. Debe ser una cadena de hasta 255 caracteres que contenga únicamente números y letras latinas.<markable>— indicador de que el producto requiere marcación. Se debe enviarYsi requiere marcación; de lo contrario, se puede enviarNu omitir el elemento. Si el valor difiere entre las variantes de un mismo producto, se utiliza el de la última variante.
Parámetros con tratamiento especial
Los siguientes valores de code reciben un tratamiento especial en el sistema:
article— referencia (SKU) de la variante; admite una cadena libre.weight— peso de la variante en gramos. El valor convertido a gramos puede ser entero o decimal, con un máximo de tres decimales, comprendido entre 0 y 9 999 999 999.description— descripción de la variante.barcode— código de barras de la variante.color— color de la variante.size— tamaño de la variante.
Para color y size, se muestra el nombre del campo del sistema y se ignora el nombre indicado en el archivo.
El campo description no se muestra en el sistema, pero puede utilizarse en las plantillas Twig, por ejemplo, para incluirlo en formularios impresos.
<param name="Peso" code="weight">50</param>El peso también puede incluir las abreviaturas de las unidades g, kg, q y t:
<param name="Peso" code="weight">1.02</param>
<param name="Peso" code="weight">0.2 kg</param>Al cargar el catálogo, el peso se convierte a gramos, ya que esta es la unidad utilizada por el sistema.