Товарная выгрузка (XML) - RU Документация - REES46 Manual
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не обязательноТип локации. Доступные значения: 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не обязательноОстаток товара. Может принимать одно из значений:
  • one - товар доступен в единственном экземпляре
  • few - товар в ограниченном количестве (до 10 ед.)
  • lot - доступно от 10 и более единиц товара


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

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


Элемент "locations"

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

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

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

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

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

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

Пример полного 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" weight="80">
						<price>70000</price>
						<oldprice>75000</oldprice>
					</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>
				<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.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