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

В этом руководстве описаны все необходимые элементы YML-файлов.

Файлы для обновления каталога и файлы для управления размещениемФайлы для обновления каталога и файлы для управления размещением

С помощью YML-файлов можно решать две задачи:

• добавлять товары в каталог и обновлять информацию о них;
• управлять размещением товаров в магазинах.

YML-файлы, решающие разные задачи, отличаются набором обязательных элементов.

ЗаголовокЗаголовок

Нужен в любом YML-файле.

Пишется так:

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

Заголовок занимает первую строку и начинается с нулевого символа. Подойдут кодировки UTF-8 и Windows-1251.

Корневой элементКорневой элемент <yml_catalog>

Нужен в любом YML-файле.

В любом XML-документе есть корневой элемент. Формат YML в качестве корневого использует элемент <yml_catalog> с атрибутом date.

В атрибуте укажите дату и время момента, на который актуальны данные в файле. Загружаемая версия каталога должна быть не старше 10 дней.

Дату и время нужно указать согласно стандарту RFC 3339, вот так:

                <yml_catalog date="2022-05-22T14:37+03:00">

Обязательно указывайте часовой пояс. Он отсчитывается от UTC — например, красноярское время записывается так:

                <yml_catalog date="2022-05-22T15:08+07:00">

Дату и время в будущем указывать нельзя.

Если файл долго генерируется, указывайте в атрибуте момент начала генерации. Почему?

ЭлементЭлемент <shop>

Нужен в любом YML-файле.

В элемент <yml_catalog> в единственном экземпляре входит элемент <shop> без атрибутов. Он описывает магазин, для которого вы готовите файл.

В него вложены:

ЭлементЭлемент <categories>

Нужен только в YML-файле, управляющем товарами

Вложен в элемент <shop>, не имеет атрибутов. Помещается перед элементом <offers>. Содержит сколько угодно элементов <category>, каждый из которых описывает одну из категорий доступных в магазине товаров.

При создании категорий следуйте рекомендациям:

• указывайте конкретные категории — например, набор ножей лучше отнести к категории Столовые приборы, а не просто Посуда;
• выбирайте категории, которые описывают товар, а не абстрактный признак — например, лучше указать Духи, а не Подарки.

Каждой категории нужно присвоить уникальный идентификатор — целое положительное число длиной до 18 цифр — и записать его в атрибут id. Запись числа не должна начинаться с нуля — например, 055 не подойдет.

Чтобы вложить одну категорию в другую, используйте атрибут parentId.

Получится так:

<categories>
    <category id="1">Книги</category>
    <category id="2" parentId="1">Детективы</category>
    <category id="3" parentId="1">Боевики</category>
    <category id="4">Видео</category>
    <category id="5" parentId="4">Комедии</category>
    <category id="6">Принтеры</category>
    <category id="7">Оргтехника</category>
</categories>

ЭлементЭлемент <offers>

Нужен в любом YML-файле. Содержимое вложенных элементов <offer> зависит от задачи, которую решает YML-файл.

Помещается после элемента <categories>. Не имеет атрибутов. Содержит сколько угодно элементов <offer>, каждый из которых описывает один товар в магазине. У <offer> есть обязательный атрибут id, который содержит ваш SKU товара. Что такое SKU

Внутри <offer> нужно указать характеристики товара (название, описание, производителя и так далее) или параметры размещения (цену, скидки, остатки и так далее).

Параметры доставки и самовывозаПараметры доставки и самовывоза

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

• перед <offers>, чтобы задать параметры для всего магазина;
• внутри <offer>, если нужно переопределить параметры для конкретного товара.

Чтобы Маркет учитывал параметры, заданные в YML-файле, нужно включить опцию Использовать данные из прайс-листа в кабинете. Инструкция

Элементы иЭлементы <delivery> и <pickup>

Нужны только в YML-файле, управляющем размещением.

<delivery><delivery>

Указывает, доступна ли курьерская доставка. Значение по умолчанию — true.

Добавьте в файл <delivery>false</delivery>, если магазин не доставляет товары.

<pickup><pickup>

Указывает, доступен ли самовывоз. Значение по умолчанию — true.

Добавьте в файл <pickup>false</pickup>, если самовывоз недоступен.

ЭлементЭлемент <delivery-options>

Нужен только в YML-файле, управляющем размещением.

Не имеет атрибутов. Содержит до пяти элементов <option>, каждый из которых описывает один из способов курьерской доставки (например, обычная, ускоренная и так далее).

Может быть вложен в <shop> и в <offer>.

Внутри <shop> элемент <delivery-options> определяет способы доставки, которые магазин предлагает по умолчанию.

Внутри <offer> элемент <delivery-options> указывает, что для конкретного товара действуют не общие условия доставки, а специальные.

Параметры способа доставки <option> задаются атрибутами:

• cost — не используется. Задайте любое число, чтобы файл прошел техническую проверку.
• days — срок в рабочих днях, целое число или интервал, записанный через дефис. Для доставки в день заказа укажите 0, для доставки на следующий день — 1. Максимальное значение — 60. На Маркете нельзя продавать товары с неизвестным сроком доставки. Если поле days оставить пустым, то товар будет скрыт с витрины.
• order-before — до которого часа можно оформить доставку этим способом, чтобы срок начал отсчитываться с сегодняшнего дня. Целое число от 0 до 24. Это необязательный атрибут, значение по умолчанию — 13.

Получится так:

<delivery-options>
    <option cost="123" days="4" order-before="18"/>
</delivery-options>

Здесь указано, что покупатель может оформить доставку в течение 4 дней. Если он оформляет заказ после 18:00, срок начнет отсчитываться со следующего дня.

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

ЭлементЭлемент <pickup-options>

Нужен только в YML-файле, управляющем размещением.

Не имеет атрибутов. Содержит до пяти элементов <option>, каждый из которых описывает один из способов самовывоза.

Может быть вложен в <shop> и в <offer>.

Внутри <shop> элемент <pickup-options> определяет способы самовывоза, которые магазин предлагает по умолчанию.

Внутри <offer> элемент <pickup-options> указывает, что для конкретного товара действуют не общие условия самовывоза, а специальные.

Параметры способа самовывоза задаются атрибутами:

• cost — не используется. Задайте любое число, чтобы файл прошел техническую проверку.
• days — срок в рабочих днях, целое число или интервал, записанный через дефис. Для самовывоза в день заказа укажите 0, для самовывоза на следующий день — 1. Максимальное значение — 60. На Маркете нельзя продавать товары с неизвестным сроком самовывоза. Если поле days оставить пустым, то товар будет скрыт с витрины.
• order-before — до которого часа можно оформить самовывоз этим способом, чтобы срок начал отсчитываться с сегодняшнего дня. Целое число от 0 до 24. Это необязательный атрибут, значение по умолчанию — 13.

Получится так:

<pickup-options>
    <option cost="123" days="2" order-before="18"/>
</pickup-options>

Здесь указано, что товар приедет на пункт выдачи в течение двух дней. Если покупатель оформляет заказ с самовывозом после 18:00, срок начнет отсчитываться со следующего дня.

Примеры готовых файловПримеры готовых файлов

Можно ли разбить файл на несколько?Можно ли разбить файл на несколько?

Да, можно, если магазин работает по модели DBS. Это полезно, если файл слишком большой или если, например, сведения о разных товарах у вас хранятся в разных базах данных — и генерировать отдельные файлы проще.

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

Полезные ссылки

• Документация API Маркета
• Новости для партнеров
• Наш Телеграм-канал
• Обучающие видеоролики