# Технические требования к прайс-листам

Ваш прайс-лист может быть в одном из таких форматов:

– XLSX (прайс-лист должен быть расположен на первом листе файла XLSX и не должен содержать формул, а также скрытых строк и столбцов) – XML (или YML)

Для автоматической загрузки прайс-листа его необходимо опубликовать на сайте интернет-магазина и предоставить доступ для загрузки по протоколу HTTP. Для доступа к прайс-листу запрещено использовать авторизацию, использование скриптов для перенаправления или загрузки файлов (в частности, файлов фото).

# Общие рекомендации по формированию прайс-листа

Прайс-лист может содержать перечень товарных позиций, который должен строго соответствовать своему формату(XLSX, ibud-XML, hotline-XML, YML).

Все товарные позиции в файле должны иметь набор обязательных и дополнительных полей, которые должны быть заполнены.

К названиям, описаниям, фото товарных позиций в прайс-листе выдвигаются не только технические но и информационные требования, которым они должны соответствовать.

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

Товарные предложения, на которые заказы не принимаются, не должны присутствовать в прайс-листе.

Поскольку сайт ibud.ua двуязычный (украинский и русский), то в форматах ibud-XML и Excel-файлах прайс-листов содержатся поля для перевода.

Товарная позиция должна содержать обязательные поля:

идентификатор товара (id), должен быть уникальным для всего интернет-магазина
название товара (одно наименование модели)
цену
валюту
идентификатор каталога (category/catecoryId), к которому будет отнесен товар

Перечень категорий, брендов и наименований в одной товарной позиции запрещается.

# Требования к значениям полей товаров в файлах импорта

# ID

Должен быть уникальным для всего интернет-магазина. Может состоять из из букв кириллического или латинского алфавита, десятичных цифр, знаков препинания, математических символов и небуквенных орфографических знаков.

Максимальная длина – 19 символов, включая пробелы и специальные символы.

Не должен содержать знаков перехода на новую строку.

# Название

Должно состоять из букв кириллического или латинского алфавита, десятичных цифр, знаков препинания, математических символов и небуквенних орфографических знаков.

Максимальная длина – 100 символов, включая пробелы и специальные символы.

Не должна содержать знаков перехода на новую строку.

# Цена

Должно указываться десятичными цифрами. Допускаться дробная часть указана через запятую. Большое количество знаков после запятой при импорте округлиться до двух.

# Валюта

Должна задаваться в соответствующем формате, набором символов: USD, UAH, EUR, RUR.

# Единица измерения

Должна задаваться в соответствующем формате, набором символов: шт, м2, кг, кг/м2 и тому подобное. Должна состоять из букв кириллического алфавита или спецсимволов. В файле можно ознакомиться с единицами измерения, которые доступны для использования.

# Наличие

Должно задаваться одним из нескольких значений, в соответствии с форматом, например:

В наличии
Нет в наличии
Под заказ

При вводе наличия недопустимыми значениями или символами – импортируемый товар будет иметь статус "В наличии".

# Категория

Идентификатор категории должен быть целым положительным числом. Не должен содержать никаких других символов.

Максимальная длина – 9 цифр.

# Ссылка

Должна задаваться в стандартном формате интернет-ссылок. Не должно иметь запрещенных для интернет-ссылок символов и пробелов.

# Изображение

Должно задаваться ссылкой на графический файл.

WARNING

Ссылка на изображение товара, должна указывать прямой путь к графическому файлу на сервере, а не формироваться скриптом при переходе по ссылке.

Изображение должно соответствовать следующим требованиям:

8192х8192 px – максимальные размеры изображения
350х350 px – минимальные размеры изображения
gif, jpg, jpeg, png – формат графического файла
20 Мб – максимальный размер графического файла

WARNING

В некоторых случаях, указанное раcширение файла-изображения, может не соответствовать его реальному формату. В таких случаях, фото может отображаться неверно.

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

Недопустимо давать ссылку на «заглушку», то есть на страницу, где написано "изображение отсутствует", или на логотип магазина.

# Производитель

Должен состоять из букв кириллического или латинского алфавита, десятичных цифр, математических символов и небуквенних орфографических знаков.

Максимальная длина – 100 символов, включая пробелы и специальные символы.

# Описание

Должно состоять из букв кириллического или латинского алфавита, десятичных цифр, знаков препинания, математических символов и небуквенных орфографических знаков.
Описание импортируется одной строкой.
Допускается использование HTML-разметки для форматирования текста, добавления переходов на новую строку, абзацев, отступов, списков.

Максимальная длина – 3800 символов, включая пробелы и специальные символы.

# Формат ibud-XML

Пример в формате ibud-XML: загрузить.

Стандарт xml требует замены некоторых символов на эквивалентные им символьные примитивы:

Символ	Замена
<	`<`
>	`>`
&	`&`
'	`'`
"	`"`

Структура файла состоит из нескольких элементов:

    <?xml version="1.0" encoding="utf-8"?>
    <!DOCTYPE ibud_catalog SYSTEM "shops.dtd">

Стандартный XML-заголовок со ссылкой на файл описания формата (DTD). Заголовок должен начинаться с первой строки, с нулевого символа и содержать объявление версии xml и информацию о кодировании документа. Вторую строчку заголовка XML-документа определяет ссылку на файл описания формата данных (DTD). Здесь достаточно отметить лишь имя файла shops.dtd.

    <yml_catalog date="2019-03-05 15:00">

XML-документ может содержать только один корневой элемент. Формат ibud-XML, как и YML, в качестве корневого элемента использует <yml_catalog>. Атрибут date элемента <yml_catalog> должен соответствовать дате и времени генерации XML-файла на стороне магазина. Дата должна иметь формат YYYY-MM-DD hh: mm.

    <shop>
        <categories>...</categories>
        <offers>
        <offer>...</offers>
        <offer>...</offers>
        ...
        </offers>
    </shop>

Элемент <shop> содержит описание категорий и товарных предложений.

    <categories>
        <category>
            <id>239065</id>
            <picture></picture>
            <name_uk>Дискова пила</name_uk>
            <name_ru>Дисковая пила</name_ru>
            <parentId></parentId>
            <description_uk><![CDATA[ Опис категорії Дискова пила ]]></description_uk>
            <description_ru><![CDATA[ Описание категории Дисковая пила ]]></description_ru>
        </category>
        <category>...</category>
    </categories>

В элементе <categories> содержится список категорий магазина. Каждая категория описывается отдельным элементом <category>. Описание категории должно содержать ее идентификатор (атрибут id) для всех категорий и идентификатор категории более высокого уровня для подкатегорий. Идентификатор категории должен быть уникальным положительным целым числом и неизменным от загрузки к загрузке прайса. Ни у одной категории параметр id не может равняться «0». Если элемент <parentId> не указан, то категория считается корневой.

id — идентификатор вашей категории, должен быть уникальным.

name_uk — название категории на украинском языке.

name_ru — название категории на русском языке.

parentId — идентификатор вышей по иерархии (родительской) категории товаров.

description_uk — описание категории на украинском языке..

description_ru — описание категории на русском языке.

Все товарные предложения находятся в теге <offers>. Отдельное товарное предложение находится в теге <offer>.

    <offer>...</offer>

    <id>7561443</id>

Идентификатор товарной позиции, который должен быть уникальным для всего интернет-магазина и оставаться неизменным от экспорта к экспорту прайс-листа. Значение атрибута id может принимать только положительные целые числа (например 154707) и буквы латинского алфавита (например ibud111). Обязателен.

    <article>V117</article>

Артикул товара.

    <name_uk>Відрізна машина Vulkan BNMG8006 380 3 кВт</name_uk>

Название товара на украинском языке.

    <name_ru>Отрезная машина Vulkan BNMG8006 380 3 кВт</name_ru>

Название товара на русском языке.

    <price>8700</price>

Цена товара.

    <currencyId>UAH</currencyId>

Валюта, в которой выводится цена.

    <measure>шт</measure>

Единицы измерения товара.

<availability>В наличии</availability>

Статус наличия, отражает наличие соответствующего товара. Данный элемент может принимать следующие значения:

"нет в наличии" или "0";
"в наличии" или "1", либо "true";
"под заказ" или "2", либо "false";
"наличие уточняйте" или "3".

    <min_order>1</min_order>

Значение минимального заказа.

    <max_order>5</max_order>

Значение максимального заказа.

    <category>239886</category>

Идентификатор категории товара. Должен отвечать одной из категорий в соответствующем блоке. Иначе позиция будет считаться позицией без категории.

    <picture>
        https://imageserver.ibud.ua/first/2019/02/08/original/5c5d3cdda07595567-598876a4025f05292-1502114951-AyiIXC.jpg
    </picture>

Ссылка на фото товара. Путь к картинкам должен состоять из латинских букв, цифры, знак «минус», подчеркивания. Форматы картинок jpg, jpeg, png или gif (без прозрачных частей).
Если есть несколько ссылок на изображения — нужно размещать каждое в отдельном теге.

    <description_uk>
    <![CDATA[ <p>Споживана потужність: 3 Вт. </p> <p>Діаметр диску: 400 мм. </p> <p><strong>Відрізна машина Vulkan BNMG8006</strong> має високий ресурс ріжучого диску і, відповідно, низьку ціну різання.</p> ]]>
    </description_uk>

Описание товара на украинском языке.

    <description_ru>
    <![CDATA[ <p>Потребляемая мощность: 3 Вт. </p> <p>Диаметр диска: 400 мм. </p> <p><strong>Отрезная машина Vulkan BNMG8006 380 3 кВт </strong> имеет высокий ресурс режущего диска и, соответственно, низкую цену резки.</p> ]]>
    </description>

Описание товара на русском языке.

    <producer_uk>Vulkan</producer_uk>

Наименование производителя товара на украинском языке.

    <producer_ru>Vulkan</producer_ru>

Перевод наименования производителя товара на русском языке.

    <url>...</url>

Ссылка на страницу товара на внешнем сайте. Обьязательное поле для компаний, размещающихся на условиях с внешними переходами.

<seo_title_uk>Відрізна машина Vulkan BNMG8006 220 3 кВт ціна | Компанія ibud.ua</seo_title_uk>

Заголовок для товара на украинском языке.

<seo_title_ru>Отрезная машина Vulkan BNMG8006 220 3 кВт цена | Компания ibud.ua</seo_title_ru>

Заголовок для товара на русском языке.

<seo_description_uk>...</seo_description_uk>

СЕО-описание для товара на украинском языке.

<seo_description_ru>...</seo_description_ru>

СЕО-описание для товара на русском языке.

<seo_keywords_uk>...</seo_keywords_uk>

Ключевые слова для товара на украинском языке.

<seo_keywords_ru>...</seo_keywords_ru>

Ключевые слова для товара на русском языке.

# Формат hotline-XML

Пример у формата XML: загрузить.

Структура файла состоит из нескольких элементов:

    <?xml version="1.0" encoding="utf-8"?>

Стандартный XML-заголовок, начинается с первой строки, с нулевого символа и содержит объявление версии xml и информацию о кодировании документа.

    <price>
        <date>2019-03-05 15:00</date>
        <firmName>BudResurs</firmName>
        <firmId>0001</firmId>
        <categories>...</categories>
        <items>
            <item>...</item>
            <item>...</item>
            ...
        </items>
    </price>

Элемент <price> содержит описание магазина и его товарных предложений.

    <date>2018-05-25 17:00</date>

Дата генерации файла в формате ГГГГ-ММ-ДД ЧЧ:ММ.

    <firmName>BudResurs</firmName>

Название магазина (например, BudResurs).

    <firmId>0001</firmId>

уникальный ID (код) интернет-магазина с которого делалась выгрузка.

    <categories>
        <category>
            <id>239069</id>
            <name>Бензиновые генераторы</name>
        </category>
        <category>
            <id>239062</id>
            <name>Бензопилы</name>
        </category>
        <category>
	    <id>239877</id>
            <parentId>239062</parentId>
            <name>Vulkan</name>
        </category>
        ...
    </categories>

Описание категорий товаров является обязательным. В элементе <categories> содержится список категорий магазина. Каждая категория описывается отдельным элементом <category>. Описание категории должно содержать ее идентификатор (параметр <id>) для всех категорий и идентификатор категории более высокого уровня для подкатегорий. Идентификатор категории должен быть уникальным положительным целым числом и неизменным от загрузки к загрузке прайса. Ни у одной категории параметр id не может равняться «0». Если элемент <parentId> не указан, то категория считается корневой (можно обойтись без иерархической структуры). В параметр <name> указывается название категории.

Параметры:

<id> — идентификатор вашей категории товаров, должен быть уникальным.

<parentId> — идентификатор высшей по иерархии (родительской) категории.

<name> — название категории.

    <items>...</items>

В элементе <items> содержится список товарных предложений магазина. Каждое товарное предложение описывается отдельным элементом <item>.

    <item>
    ...
    </item>

Начало описания одной товарной позиции.

    <item>
    <id>7561442</id>

Идентификатор товарной позиции должен быть уникальным для всего интернет-магазина и оставаться неизменным от экспорта к экспорту прайс-листа. Значение атрибута <id> может принимать только положительные целые числа (например 154707) и буквы латинского алфавита (например ibud111). Обязателен.

    <categoryId>239886</categoryId>

Идентификатор категории товарной позиции.

    <code>V117</code>

Код модели (артикул производителя).

    <vendor>Vulkan</vendor>

Наименование производителя. Допускается указание только одного производителя товара. В элементе <vendor> не разрешается указание страны-производителя товара.

    <name>Отрезная машина Vulkan BNMG8006 380 3 кВт</name>

Наименование модели. Допускается указание только одной модели товарной позиции, без перечислений. Запрещается указывать любую рекламную и другую информацию, не относящуюся к наименованию. Название товарной позиции должно быть уникальным для всего интернет-магазина.

    <description>
    <![CDATA[ <p>Потребляемая мощность: 3 Вт. </p> <p>Диаметр диска: 400 мм. </p> <p><strong>Отрезная машина Vulkan BNMG8006 380 3 кВт </strong> имеет высокий ресурс режущего диска и, соответственно, низкую цену резки.</p> ]]>
    </description>

Описание товара. Запрещается указывать слова, не относящиеся к описанию товара (кроме определения размера, конфигурации, комплектации).

    <url>...</url>

    <image>https://imageserver.ibud.ua/first/2019/02/08/original/5c5d3cdda07595567-598876a4025f05292-1502114951-AyiIXC.jpg</image>

Ссылка на изображение товара в Вашем сайте. Путь к картинкам должен состоять из латинских букв, цифры, знак «минус», подчеркивания. Форматы картинок jpg, jpeg, png или gif (без прозрачных частей).
Если есть несколько ссылок на изображения — нужно размещать каждое в отдельном теге.

    <priceRUAH>8700</priceRUAH>

Действующая розничная цена в гривнах. Может быть указана в долларах, тогда используется тег <priceRUSD>. Если цены в прайс-листе даны только в долларах, обязательно указывать курс пересчета в элементе <rate>.

    <stock>В наличии</stock>

Наличие товара на сайте. Принимаются следующие значения:

"в наличии"
"под заказ"

# Формат YML

Пример в формате YML: загрузить.

YML (Yandex Market Language) — это стандарт, разработанный Яндексом для принятия и размещения информации от магазинов. YML базируется на стандарте XML (XML DTD). Единый формат представления данных позволяет быстро и качественно обрабатывать информацию о товарах и услугах, предоставляемой магазинами.

В ссылках, указанных в YML-файле, не рекомендуется использовать пробелы и кириллические символы. Это может привести к невалидности файла.

Стандарт YML не допускает использования в текстовых данных непечатаемых символов с ASCII-кодами в диапазоне значений от 0 до 31 (за исключением символов с кодами 9, 10, 13 – табуляция, перевод строки, возврат каретки). Это требует обязательной замены некоторых символов на эквивалентные им символьные коды:

Символ в тексте Код для YML-файла

Символ в тексте	Код для YML-файла
"	`"`
&	`&`
>	`>`
<	`<`
'	`'`

Структура файла состоит из нескольких элементов:

    <?xml version="1.0" encoding="utf-8"?>

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

    <yml_catalog date="2019-03-05 15:00">
        <shop>
        <...>
        </shop>
    </yml_catalog>

XML-документ может содержать только один корневой элемент. Формат YML как корневой использует элемент <yml_catalog>. Атрибут date элемента <yml_catalog> должен соответствовать дате и времени генерирования YML-файла на стороне магазина. Дата должна иметь формат ГГГГ-MM-ДД чч:мм.

    <shop>
        <name>Manager</name>
        <company>BudResurs</company>
        <url>http://BudResurs.ua/</url>
        <currencies> ... </currencies>
        <categories> ... </categories>
        
        <offers> ... </offers>
    </shop>

Элемент <shop> содержит описание магазина и его товарных предложений. Тег <name> в корне <shop> отвечает за название интернет-магазина. Тег <company> отвечает за название компании. Тег <url> в корне <shop> отвечает за внешнюю ссылку на интернет-магазин.

    <currencies>
        <currency id="UAH" rate="1"/>
        <currency id="USD" rate="28"/>
        <currency id="EUR" rate="31"/>
    </currencies>

Элемент <currencies> задает валюты, в которой передаются цены на товары магазина. Элемент <currency> отвечает за одну валюту, его атрибут id отвечает за название, а rate – за курс перерасчета.

Данные о ценах принимаются в гривнах (UAH), долларах (USD) и евро (EUR).

    <categories>
      <category id="239062">Бензопилы</category>
      <category id="239065">Дисковая пила</category>
      <category id="239069">Бензиновые генераторы</category>
      <category id="239877" parentId="239062">Vulkan</category>
      <category id="239878" parentId="239062">Intertool</category>
      <category id="239879" parentId="239069">Vulkan</category>
      <category id="239881" parentId="239069">Intertool</category>
      <category id="239882" parentId="239069">Hitachi</category>
      <category id="239886" parentId="239065">Vulkan</category>
      <category id="239888" parentId="239065">Intertool</category>
    </categories>

В элементе <categories> содержится список категорий магазина. Каждая категория описывается отдельным элементом <category>. Описание категории должно содержать ее идентификатор (атрибут id) для всех категорий и идентификатор категории более высокого уровня для подкатегорий. Идентификатор категории должен быть уникальным положительным целым числом, и неизменным от загрузки к загрузке прайса. Ни у одной категории параметр id не может равняться «0». Если элемент <parentId> не указан, то категория считается корневой.

Атрибуты:

id — идентификатор вашей категории, уникальный для всего интернет-магазина.

parentId — идентификатор высшей по иерархии (родительской) категории.

    <offers>
        <offer>...</offer>
        <offer>...</offer>
        ...
    </offers>

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

Описание одного товара:

    <offer id="7561442" available="true">

Атрибуты:

id — уникальный идентификатор товара, который должен быть уникальным для всего интернет-магазина и неизменным от загрузки к загрузке прайса. Значение атрибута id может принимать только положительные целые числа (например 154707) и буквы латинского алфавита (например ibud111). Обязателен.

available — элемент, который отражает наличие соответствующего товара. Данный атрибут может принимать следующие значения:

true — определяет статус "В наличии"
false — определяет статус "Под заказ"

    <url>...</url>

Ссылка на страницу товара на внешнем сайте (в ссылках, указанных в YML-файле, не рекомендуется использовать пробелы и кириллические символы. Это может привести к невалидности файла.)

    <price>8700</price>

Цена товара. Цена округляется до двух знаков после запятой.

    <currencyId>UAH</currencyId>

Идентификатор валюты товара (UAH, EUR, USD).

    <categoryId>239886</categoryId>

Идентификатор категории товара. Один товар может относиться только к одной категории.

    <picture>https://imageserver.ibud.ua/first/2019/02/08/original/5c5d3cdda07595567-598876a4025f05292-1502114951-AyiIXC.jpg</picture>

Ссылка на изображение соответствующего товарного предложения. Путь к картинкам должен состоять из латинских букв, цифры, знак «минус», подчеркивания. Форматы картинок jpg, jpeg, png или gif (без прозрачных частей).
Если есть несколько ссылок на изображения — нужно размещать каждое в отдельном теге.

    <name>Отрезная машина Vulkan BNMG8006 380 3 кВт</name>

Название товара. Должно быть уникальным для всего интернет-магазина.

    <vendor>Vulkan</vendor>

Производитель товарной позиции. Пишется оригинальное название, без транслита.

    <vendorCode>V117</vendorCode>

Артикул товарной позиции.

    <description>
    <![CDATA[ <p>Потребляемая мощность: 3 Вт. </p> <p>Диаметр диска: 400 мм. </p> <p><strong>Отрезная машина Vulkan BNMG8006 380 3 кВт </strong> имеет высокий ресурс режущего диска и, соответственно, низкую цену резки.</p> ]]>
    </description>

Описание товарной позиции.

# Формат Excel

Пример в формате xlsx: загрузить.

Файл должен иметь два листа:

с товарными единицами products должен идти первым
с категориями categories должен идти вторым

# Перечень колонок на листе товарных единиц (products):

id – уникальный идентификатор товара, должен быть уникальным для всего интернет-магазина. Значение id может принимать только положительные целые числа (например 154707) и буквы латинского алфавита (например ibud111). Обязательное поле.

article – артикул товарной позиции.

name – название товара, должно быть уникальным для всего прайс-листа. Обязательное поле.

name_translate – перевод названия товара (не обязательно поле).

price – цена товара, обязательное поле.

currency – идентификатор валюты товара (UAH, RUR, USD), обязательное поле.

measure – единицы измерения товара (шт, кг и т.п).

availability – наличие товара. Данное поле принимает следующие значения:

"нет в наличии" или "0";
"в наличии" или "1";
"под заказ" или "2";
"наличие уточняйте" или "3".

min_order – числовое значение "минимального заказа".

max_order – числовое значение "максимального заказ".

category – идентификатор категории товара. Должен быть уникальным и неизменным от загрузки к загрузке прайса, обязательное поле.

picture – ссылка на изображение соответствующей товарной единицы.

description_uk – описание товарной единицы украинском языке.

description_ru – описание товарной единицы на русском языке.

producer_uk – производитель товарной единицы украинском языке.

producer_ru – производитель товарной единицы на русском языке.

url – ссылка на внешний сайт.

only_for_IM – метка "только в интернет-магазине".

recommended – метка рекомендованный товар.

seo_title_uk – заголовок страницы товарной единицы в интернет-магазине на украинском языке.

seo_title_ru – заголовок страницы товарной единицы в интернет-магазине на русском языке.

seo_description_uk – описание страницы товарной единицы в интернет-магазине на украинском языке.

seo_description_ru – описание страницы товарной единицы в интернет-магазине на русском языке.

seo_keywords_uk – ключевые слова страницы товарной единицы в интернет-магазине на украинском языке.

seo_keywords_ru – ключевые слова страницы товарной единицы в интернет-магазине на русском языке.

# Перечень колонок на листе категорий (categories):

id – уникальный идентификатор категории. Значение id может принимать только положительные целые числа, например 154707.

parent_id – уникальный идентификатор родительской категории. Показывает куда, будет вложена даная категория..

name_uk – название категории на украинском языке.

name_ru – название категории на русском языке.

description_uk – описание категории на украинском языке.

description_ru – описание категории на русском языке.

picture – ссылка на изображение категории.