YML

 

Эта статья — о структуре YML-файлов. Чтобы узнать, как задать конкретный параметр товара, найдите его в справочнике.

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

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

Совет.

Если вы пользуетесь популярной CMS, возможно, для нее есть готовый модуль, который умеет генерировать 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">
            

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

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

Внимание. Если вы передаете с помощью YML остатки или цены, атрибут date нужно указывать обязательно.

Элемент <shop>

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

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

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

Элемент Тип данных Смысл
<name>

Текст:

<name>BestSeller</name>
Название вашего магазина
<company>

Текст:

<company>Tne Best inc.</company>
Название вашей компании
<url>

Текст:

<url>http://best.seller.ru</url>

Адрес сайта магазина, записанный согласно стандарту RFC 3986
<platform>

Текст:

<platform>uCoz</platform>
Название системы управления контентом
<categories> Содержит вложенные элементы <category> Список категорий товаров, продаваемых в магазине
<offers> Содержит вложенные элементы <offer> Список предложений — товаров, продающихся в магазине, с ценами

Элемент <categories>

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

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

Лучше всего пользоваться деревом категорий Маркета — оно включает практически все.

Если брать категории из дерева неудобно, указывайте свои. Делайте их понятными и логичными:

Неправильно Хорошо
Товары → Склад_1 Игрушки → Конструкторы
Одежда → Женская одежда → Верхняя одежда → Платья Товары для детей → Одежда → Детские комбинезоны

Каждой категории нужно присвоить уникальный идентификатор — целое положительное число длиной до 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-файл.

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

Примечание. Элемент <shop-sku> устарел, его лучше не использовать. Если он есть, значение вашего SKU берется из него, а не из атрибута id элемента <offer>.

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

Посмотрите справочник.

Он подскажет, какие параметры обязательны и как их задать в YML-файле.

Если YML-файл предназначен для добавления товаров, смотрите таблицу с характеристиками. Если для управления размещением — таблицу с параметрами размещения.

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

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

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

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

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

Добавьте в файл <delivery>false</delivery>, если магазин не доставляет товары, и <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, срок начнет отсчитываться со следующего дня.

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

Для управления товарами Скачать
Для управления размещением Скачать