Page tree
Skip to end of metadata
Go to start of metadata

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

Базовый формат товарной выгрузки 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обязательноПолное название товара. Для раздельного написания названия см. элементы: typePrefixvendormodel.
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.

  • No labels