Товарная выгрузка (XML)

Базовый формат

Базовый формат товарной выгрузки REES46 основан на YML (Yandex Market Language), более подробное описание которого доступно в разделе помощи Яндекс по ссылке: https://yandex.ru/support/partnermarket/export/yml.html

Поддерживаемые кодировки

UTF-8
Windows-1251

Основные элементы

Элемент	Обязательность	Описание
xml	обязательно	Стандартный XML-заголовок. Должен начинаться с первой строки и нулевого символа в строке.
yml_catalog	обязательно	Корневой элемент XML-документа товарной выгрузки.
shop	обязательно	Основной элемент товарной выгрузки, содержащий описание магазина и товаров.

Элемент "xml"

Доступные атрибуты:

Атрибут	Обязательность	Описание
version	обязательно	Версия языка XML-документа. Необходимо использовать версию "1.0".
encoding	обязательно	Кодировка, используемая в XML-документе (из доступных).

Пример:

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

Элемент "yml_catalog"

Доступные атрибуты:

Атрибут	Обязательность	Описание
date	обязательно	Дата создания (генерации) XML-документа в формате YYYY-MM-DD hh:mm.

Пример:

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2019-05-16 17:19">
...
</yml_catalog>

Элемент "shop"

Дочерние элементы shop:

Элемент	Обязательность	Описание
name	обязательно	Краткое название магазина.
company	обязательно	Наименование компании, владеющей магазином.
url	обязательно	Ссылка на главную страницу магазина.
currencies	обязательно	Список курсов валют магазина.
categories	обязательно	Список категорий магазина.
locations	не обязательно	Список локаций, в которых представлен магазин.
offers	обязательно	Список товаров магазина.

Элемент "name"

Пример:

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2019-05-16 17:19">
    <shop>
        <name>Мой магазин</name>
    ...
    </shop>
</yml_catalog>

Элемент "company"

Пример:

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2019-05-16 17:19">
    <shop>
    ...
        <company>Компания моего магазина</company>
    ...
    </shop>
</yml_catalog>

Элемент "url"

Пример:

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2019-05-16 17:19">
    <shop>
    ...
        <url>https://my-store.com</url>
    ...
    </shop>
</yml_catalog>

Элемент "currencies"

Элемент currencies задает список курсов валют магазина. Каждая из валют описывается отдельным элементом currency.

Доступные атрибуты элемента currency:

Атрибут	Обязательность	Описание
id	обязательно	Код валюты.
rate	обязательно	Курс валюты по отношению к основной валюте. Значение данного атрибута для основной валюты должно быть равно 1 (rate="1"). В качестве десятичного разделителя может использоваться только символ точки.

Пример:

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2019-05-16 17:19">
    <shop>
    ...
        <currencies>
            <currency id="RUR" rate="1"/>
            <currency id="USD" rate="64.45"/>
            <currency id="EUR" rate="72.03"/>
            ...
        </currencies>
    ...
    </shop>
</yml_catalog>

Элемент "categories"

Элемент categories содержит список категорий магазина. Каждая категория описывается отдельным элементом category.

Доступные атрибуты элементы category:

Атрибут	Обязательность	Описание
id	обязательно	Идентификатор категории.
parentId	не обязательно	Идентификатор родительской категории.
url	не обязательно	Ссылка на страницу категории.

Пример:

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2019-05-16 17:19">
    <shop>
    ...
        <categories>
            <category id="2" url="http://my-store.com/categories/discount/">Распродажа</category>
            <category id="8" url="http://my-store.com/categories/men/">Мужчинам</category>
            <category id="13" parentId="8" url="http://my-store.com/categories/men/shoes/">Shoes</category>
            ...
        </categories>
    ...
    </shop>
</yml_catalog>

Элемент "locations"

Элемент locations содержит список локаций магазина. Каждая локация описывается отдельным элементом location.

Доступные атрибуты элементы location:

Атрибут	Обязательность	Описание
id	обязательно	Идентификатор локации.
parentId	не обязательно	Идентификатор родительской локации.
type	не обязательно	Тип локации. Доступные значения: city, store.
name	не обязательно	Название локации.

Пример:

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2019-05-16 17:19">
    <shop>
    ...
        <locations>
            <location id="1" type="city" name="Москва" />
            <location id="2" type="city" name="Санкт-Петербург" />
            <location id="145" parentId="1" type="store" name="Пункт выдачи на Арбате" />
            ...
        </locations>
    ...
    </shop>
</yml_catalog>

Элемент "offers"

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

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

Доступные атрибуты элемента offer:

Атрибут	Обязательность	Описание
id	обязательно	Идентификатор товара.
available	обязательно	Флаг наличия товара. Доступные значения: true, false.
leftovers	не обязательно	Остаток товара. Может принимать одно из значений: one - товар доступен в единственном экземпляре few - товар в ограниченном количестве (до 10 ед.) lot - доступно от 10 и более единиц товара

Дочерние элементы offer:

Элемент	Обязательность	Описание
name	обязательно	Полное название товара. Для раздельного написания названия см. элементы: typePrefix, vendor, model.
picture	обязательно	Ссылка на изображение товара.
price	обязательно	Базовая цена товара.
url	обязательно	Ссылка на страницу товара.
categoryId	обязательно	Категория товара. Этих элементов может быть несколько.
locations	не обязательно	Элемент, описывающий свойства товара в разных локациях: наличие, цена. См. таблицу и пример ниже.
accessories	не обязательно	Элемент, описывающий список аксессуаров текущего товара. См. пример ниже.
oldprice	не обязательно	Старая цена товара.
price_margin	не обязательно	Относительная маржинальность (приоритет) товара (от 0 до 100).
barcode	не обязательно	Штрих-код товара.
color	не обязательно	Дополнительное изображение товара для конкретного цвета. Ссылка на изображение указывается в атрибуте `picture`, а цвет - в значении. См. пример ниже.
typePrefix	не обязательно	Тип/категория товара (например, "мобильный телефон", "стиральная машина", "угловой диван").
vendor	не обязательно	Производитель/бренд.
vendorCode	не обязательно	Код производителя для данного товара.
model	не обязательно	Модель и название товара.
seasonality	не обязательно	Сезонность товара. В качестве значения используется порядковый номер месяца ( от 1 до 12). Этих элементов может быть несколько.
is_new	не обязательно	Может принимать только одно значение - "1", означающее, что товар является новинкой.
rating	не обязательно	Рейтинг товара. Целочисленное значение от 0 до 5, где 0 - товар без рейтинга, 1-5 - рейтинг.
description	не обязательно	Описание товара.

Элемент "locations"

Элемент locations содержит список локаций, а также доступность и цену текущего товара в локациях. Каждая локация описывается отдельным элементом location.

Атрибуты элемента location:

Атрибут	Обязательность	Описание
id	обязательно	Идентификатор, соответствующий локации (идентификатору) из элемента `locations` элемента `shop`. Подробнее об описании локации см. в соответствующем подразделе этого документа и в примере ниже.

Обратите внимание, что товар будет считаться доступным к приобретению только в перечисленных в элементе offer локациях, во всех остальных известных, но не перечисленных локациях, товар будет считаться недоступным к приобретению.

Дочерние элементы:

Элемент	Обязательность	Описание
price	не обязательно	Цена товара в локации. Если элемент отсутствует, то используется базовая цена товара.

Пример полного XML

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2019-05-16 17:19">
    <shop>
		<name>Мой магазин</name>
		<company>Компания моего магазина</company>
		<url>https://my-store.com</url>
		<!-- перечисление валют магазин и курсов валют -->
        <currencies>
            <currency id="RUR" rate="1"/>
            <currency id="USD" rate="64.45"/>
            <currency id="EUR" rate="72.03"/>
        </currencies>
		<!-- перечисление всех категорий магазина, их иерархии и ссылок -->
        <categories>
            <category id="2" url="http://my-store.com/categories/apple/">Apple</category>
            <category id="13" parentId="2" url="http://my-store.com/categories/apple/phones/>Телефоны</category>
        </categories>
		<!-- перечисление всех локаций магазина -->
        <locations>
            <location id="1" type="city" name="Москва" />
            <location id="2" type="city" name="Санкт-Петербург" />
			<location id="3" type="city" name="Новосибирск" />
        </locations>
		<offers>
			<offer id="395532" available="true" leftovers="few">
				<url>http://my-store.com/items/395532</url>
				<price>50000</price>
				<oldprice>55000</oldprice>
				<price_margin>67</price_margin>
				<!-- перечисление иерархий категорий, в которых присутствует данный товар -->
				<categoryId>2</categoryId>
				<categoryId>13</categoryId>
				<!-- Указана сезонность. Приоритетные месяцы для данного товара: январь, март, апрель, июнь. -->
				<seasonality>1</seasonality>
				<seasonality>3</seasonality>
				<seasonality>4</seasonality>
				<seasonality>6</seasonality>
				<!-- перечисление локаций, в которых данный товар доступен к приобретению, а также уточнение цены товара в локации -->
				<locations>
					<location id="1">
						<price>70000</price>
					</location>
					<!-- локация id="2" не указана, значит товар в этой локации отсутствует -->
					<!-- в локации id="3" не указан price, значит цена товара соответствует базовой -->
					<location id="3"></location>
				</location>
				<!-- Перечислены ID товаров, являющиеся аксессуарами для текущего товара -->
				<accessories>
					<accessory id="5574" />
					<accessory id="131" />
					<accessory id="99444" />
					<accessory id="334411" />
				</accessories>
				<barcode>123456</barcode>
				<picture>https://my-store.com/items/395532.jpg</picture>
				<!-- перечисление доступной расцветки товара с указанием ссылки на изображение соответствующего цвету -->
				<color picture="https://my-store.com/item/395532_white.jpg">Белый</color>
				<color picture="https://my-store.com/item/395532_black.jpg">Чёрный</color>
				<name>Apple Iphone 6 128 gb</name>
				<typePrefix>Смартфон</typePrefix>
				<vendor>Apple</vendor>
				<vendorCode>APPL</vendorCode>
				<model>iPhone 6 128Gb</model>
				<is_new>1</is_new>
				<rating>5</rating>
				<description><![CDATA[iPhone 6 не просто больше. Он лучше во всех отношениях. 4,7-дюймовый HD-дисплей Retina. Процессор A8 с 64-разрядной архитектурой уровня настольного компьютера. Новая 8-мегапиксельная камера iSight с технологией Focus Pixels. Сенсор идентификации по отпечатку пальца Touch ID. Скорость Wi-Fi выше. Время работы от аккумулятора дольше. А также iOS 8 и iCloud. Все это - в цельном корпусе толщиной всего 6,9 мм.]]></description>
			</offer>
			<offer id="395533" available="false">
				...
			</offer>
			...
		</offers>
    </shop>
</yml_catalog>

Дополнительные данные для отраслевых алгоритмов

Требования к дополнительным данным о товаров для отраслевых алгоритмах описаны в следующих документах:

Правила генерации

Если XML вашего магазина имеет размер больше 5 мегабайт и режиме реального времени создаётся дольше 20 секунд, будет лучше, если вместо того, чтобы указывать ссылку на скрипт генерации XML, вы поставите задачу генерации XML в расписание. Ваш скрипт должен генерировать статичный XML-файл, скачивание которого начнется сразу при обращении к нему, без затрат времени на генерацию. Это даст вам следующие преимущества:

снижение нагрузки на ваш сервер при больших XML (иначе будет очень легко устроить вам DDOS-атаку, сделав 20-30 одновременных запросов к этому ресурсоемкому скрипту);
ускорение загрузки вашего YML нашими серверами – вместо того, чтобы ждать генерации файла по 10-15 минут, REES46 сразу начнет их выкачивать и это повысит актуальность вашей товарной базы в рекомендательной системе.

Пример такого расписания для cron:

0 */2 * * * php /home/myuser/site/docs/xml.php > /home/myuser/site/docs/rees46.xml

Обратите внимание

Для загрузки изображений товаров система REES46 может многократно обращаться к серверу интернет-магазина. Убедитесь, что IP-адреса 88.99.193.211, 148.251.91.107 внесены в список исключений (белый список) в случае, если на сервере интернет-магазина используется защита от DDoS-атак или любой другой тип блокировки многократных обращений к серверу. В противном случае система REES46 не сможет получить доступ к изображениям товаров, и товары без изображений будут исключены из рекомендаций.

Правильный формат ссылок для триггерных web-push оповещений

Все web-push оповещения требуют наличия на сайте HTTPS протокола. Триггерные web-push оповещения также требуют ссылок на изображения товаров в XML-файле в https-формате.

Убедитесь, что ссылки на изображения начинаются с https:// !

В противном случае, ваши покупатели не увидят картинок в оповещениях:

Поддержка архивных файлов

Для того, чтобы ускорить выкачивание больших XML-файлов, вы можете архивировать их архиватором GZIP. REES46 автоматически определяет архивированный файл, распаковывает его и обрабатывает. Формат архива – GNU Gzip.

Page tree

Товарная выгрузка (XML)

Базовый формат

Поддерживаемые кодировки

Основные элементы

Элемент "xml"

Элемент "yml_catalog"

Элемент "shop"

Элемент "name"

Элемент "company"

Элемент "url"

Элемент "currencies"

Элемент "categories"

Элемент "locations"

Элемент "offers"

Элемент "locations"

Пример полного XML

Дополнительные данные для отраслевых алгоритмов

Правила генерации

Правильный формат ссылок для триггерных web-push оповещений

Поддержка архивных файлов