Базовый формат
Базовый формат товарной выгрузки 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 | не обязательно | Ссылка на страницу категории. |
alias | не обязательно | Словесный идентификатор категории. |
Пример:
<?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> <category id="97" parentId="13" alias="men/shoes/leather" url="http://my-store.com/categories/men/shoes/leather">Leather Shoes</category> ... </categories> ... </shop> </yml_catalog>
Элемент "locations"
Элемент locations
содержит список локаций магазина. Каждая локация описывается отдельным элементом location
.
Доступные атрибуты элементы location
:
Атрибут | Обязательность | Описание |
---|---|---|
id | обязательно | Идентификатор локации. |
parentId | не обязательно | Идентификатор родительской локации. |
type | не обязательно | Тип локации. Доступные значения: state, city, store. |
name | не обязательно | Название локации. |
group | не обязательно | Признак группировки нескольких локаций в определенную группу. Любое строковое зачение. Пример: ХолодныеРегионы. |
Пример:
<?xml version="1.0" encoding="UTF-8"?> <yml_catalog date="2019-05-16 17:19"> <shop> ... <locations> <location id="1" type="city" name="Москва" group="ДенежныеГорода" /> <location id="2" type="city" name="Санкт-Петербург" group="ДенежныеГорода" /> <location id="145" parentId="1" type="store" name="Пункт выдачи на Арбате" /> ... </locations> ... </shop> </yml_catalog>
Элемент "offers"
Элемент offers
содержит список товаров магазина. Каждый товар описывается отдельным элементом offer
.
Обратите внимание, что элемент offer не может содержать вариант товара, а только сам товар. Если в вашем магазине все варианты одного товара находятся на одной странице сайта и нет общего идентификатора для вариантов товара, то вам необходимо использовать какой-то один из вариантов в качестве основного - его идентификатор, цену и пр. данные. Обычно выбирают самый дешёвый вариант товара в качестве основного, а флаг наличия в данном случае должен вписаться в следующую логику - если хотя бы один вариант товара есть в наличии, то товар должен считаться в наличии.
Доступные атрибуты элемента offer
:
Атрибут | Обязательность | Описание |
---|---|---|
id | обязательно | Идентификатор товара. |
available | обязательно | Флаг наличия товара. Доступные значения: true, false. |
leftovers | не обязательно | Остаток товара. Может принимать одно из значений:
|
Дочерние элементы offer
:
Элемент | Обязательность | Описание |
---|---|---|
name | обязательно | Полное название товара. Для раздельного написания названия см. элементы: typePrefix, vendor, model. |
picture | обязательно | Ссылка на изображение товара. |
price | обязательно | Базовая цена товара. |
url | обязательно | Ссылка на страницу товара. |
categoryId | обязательно | Категория товара. Этих элементов может быть несколько. |
locations | не обязательно | Элемент, описывающий свойства товара в разных локациях: наличие, цена. См. таблицу и пример ниже. |
accessories | не обязательно | Элемент, описывающий список аксессуаров текущего товара. См. пример ниже. |
customerRecommendations | не обязательно | Элемент, описывающий список собственных товаров, рекомендуемых к текущему товару. См. пример ниже. |
oldprice | не обязательно | Старая цена товара. |
price_margin | не обязательно | Относительная маржинальность (приоритет) товара (от 0 до 100). |
barcode | не обязательно | Штрих-код товара. |
typePrefix | не обязательно | Тип/категория товара (например, "мобильный телефон", "стиральная машина", "угловой диван"). |
vendor | не обязательно | Производитель/бренд. |
vendorCode | не обязательно | Код производителя для данного товара. |
model | не обязательно | Модель и название товара. |
seasonality | не обязательно | Сезонность товара. В качестве значения используется порядковый номер месяца ( от 1 до 12). Этих элементов может быть несколько. |
is_new | не обязательно | Может принимать только одно значение - "1", означающее, что товар является новинкой. |
rating | не обязательно | Рейтинг товара. Целочисленное значение от 0 до 5, где 0 - товар без рейтинга, 1-5 - рейтинг. |
description | не обязательно | Описание товара. |
stock_quantity | не обязательно | Количество товара. Целочисленное значение от 1 и более. |
tags | не обязательно | Элемент, описывающий связанные с товаром теги, для точного поиска. См. таблицу и пример ниже. |
Элемент "locations"
Элемент locations
содержит список локаций, а также доступность и цену текущего товара в локациях. Каждая локация описывается отдельным элементом location.
Атрибуты элемента location
:
Атрибут | Обязательность | Описание |
---|---|---|
id | обязательно | Идентификатор, соответствующий локации (идентификатору) из элемента locations элемента shop . Подробнее об описании локации см. в соответствующем подразделе этого документа и в примере ниже. |
weight | не обязательно | Вес товаров (приоритет) в локации (от 0 до 100). |
Обратите внимание, что товар будет считаться доступным к приобретению только в перечисленных в элементе offer
локациях, во всех остальных известных, но не перечисленных локациях, товар будет считаться недоступным к приобретению.
Дочерние элементы:
Элемент | Обязательность | Описание |
---|---|---|
price | не обязательно | Цена товара в локации. Если элемент отсутствует, то используется базовая цена товара. |
oldprice | не обязательно | Старая цена товара в локации. Если элемент отсутствует, то используется базовая старая цена товара (при наличии). |
stock_quantity | не обязательно | Количество товара. Целочисленное значение от 1 и более. |
Элемент "tags"
Элемент tags
содержит список тегов, соотносящихся с товаром. Каждое значение описывается отдельным элементом tag.
Элемент | Обязательность | Описание |
---|---|---|
tag | обязательно | Значение тега. |
Пример полного 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" alias="apple/phones" 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" weight="80"> <price>70000</price> <oldprice>75000</oldprice> <stock_quantity>10</stock_quantity> </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> <tags> <tag>телефон</tag> <tag>смартфон</tag> </tags> <customerRecommendations>18,21,146,100500</customerRecommendations> <barcode>123456</barcode> <picture>https://my-store.com/items/395532.jpg</picture> <name>Apple Iphone 6 128 gb</name> <typePrefix>Смартфон</typePrefix> <vendor picture="http://example.com/apple.jpg">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.57.203, 88.99.67.10, 88.99.70.186, 88.99.193.211, 94.130.49.248, 148.251.91.107 внесены в список исключений (белый список) в случае, если на сервере интернет-магазина используется защита от DDoS-атак или любой другой тип блокировки многократных обращений к серверу. В противном случае система REES46 не сможет получить доступ к изображениям товаров, и товары без изображений будут исключены из рекомендаций.
Правильный формат ссылок для триггерных web-push оповещений
Все web-push оповещения требуют наличия на сайте HTTPS протокола. Триггерные web-push оповещения также требуют ссылок на изображения товаров в XML-файле в https-формате.
Убедитесь, что ссылки на изображения начинаются с https:// !
В противном случае, ваши покупатели не увидят картинок в оповещениях:
Поддержка архивных файлов
Для того, чтобы ускорить выкачивание больших XML-файлов, вы можете архивировать их архиватором GZIP. REES46 автоматически определяет архивированный файл, распаковывает его и обрабатывает. Формат архива – GNU Gzip.