YML (Yandex Market Language) — это стандарт, разработанный Яндексом на основе XML, для передачи данных о товаре и размещения его на маркетплейсе или в CMS.
С помощью этого инструмента вы можете загружать товары и обновлять основную информацию о товарах. Формат YML предоставляет больше возможностей и преимуществ, чем форматы XLS, CSV.
Требования к YML‑файлу
1. В YML нельзя использовать:
непечатаемые символы с ASCII-кодами от 0 до 31 (за исключением символов с кодами 9, 10, 13 — табуляция, перевод строки, возврат каретки);
эмодзи и другие специальные символы Юникода.
2. Символы » & > < ‘ нужно заменять на эквивалентные коды:
| __ | Символ в тексте | Код для YML-файла |
| « | " | |
| & | & | |
| > | > | |
| < | < | |
| ‘ | ' |
Примечание: Вы можете использовать символы «&><‘в блоке CDATA в описании предложения.
3. Допустимые кодировки YML-файла: UTF-8, windows-1251.
4. В качестве разделителя целой и дробной частей любых чисел, указанных в качестве значений YML‑элементов, независимо от региональных установок используется только точка.
Структура файла
<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2020-11-22T14:37:38+03:00">
<shop>
<name>BestSeller</name>
<company>Tne Best inc.</company>
<url>http://best.seller.ru</url>
<currencies>
<currency id="RUR" rate="1"/>
</currencies>
<categories>
<category id="1">Бытовая техника</category>
<category id="10" parentId="1">Мелкая техника для кухни</category>
</categories>
<delivery-options>
<option cost="200" days="1"/>
</delivery-options>
<offers>
offer id="12346" bid="60" type="vendor.model">
<sku>662</sku>
<vendor>Brand</vendor>
<model>K220Y9</model>
<typePrefix>Сэндвичница</typePrefix>
<vendorCode>A1234567B</vendorCode>
<price>1099</price>
<categoryId>7</categoryId>
<picture>http://best.seller.ru/img/device56789.jpg</picture>
<pickup>true</pickup>
<param name="Мощность">750 Вт</param>
<param name="Цвет">Бардо</param>
<description>Сэндвичница 2 в 1: можно приготовить как сэндвичи, так и вафли.
</description>
<manufacturer_warranty>true</manufacturer_warranty>
<weight>1.03</weight>
<dimensions>20.800/23.500/9.000</dimensions>
<count>23</count>
</offer>
</offers>
</shop>
</yml_catalog>Основные элементы YML
| __ | Элемент | ________ | Описание | |||||
| xml header | Стандартный XML-заголовок. Должен начинаться с первой строки, с нулевого символа. | |||||||
| yml_catalog | Любой XML-документ может содержать только один корневой элемент. Формат YML в качестве корневого использует элемент <yml_catalog> с атрибутом date. | |||||||
Атрибут date: Дата и время момента, на который актуальны данные в файле. Внимание! Убедитесь, что указываете в файле правильные дату и время. Не указывайте будущие дату и время — вместо них Маркет будет использовать дату и время загрузки файла. Неактуальное значение атрибута date приведет к проблемам в работе с предложениями. Рекомендуется всегда заполнять атрибут date. Если файл генерируется автоматически, желательно указывать дату и время начала генерации. Допустимый формат значения основан на стандарте RFC 3339 (см. раздел 5.6) со следующими особенностями: — Между датой и временем должна стоять латинская буква T или пробел. — Можно не указывать секунды и часовой пояс. — По умолчанию используется 0 секунд и часовой пояс домашнего региона магазина. — Примеры значений: 2020-11-22T14:37:38+03:00 (рекомендуется). 2020-11-22T14:37:38. 2020-11-22 14:37. | ||||||||
| shop | В элементе shop содержатся: — Элементы с информацией о магазине: названием, списком категорий и т. п. — Элемент offers со списком предложений магазина. В этот элемент нужно вставить по одному элементу offer для каждого предложения. Элемент offer может быть упрощенного типа (полное название товара — тип, производитель и модель — указывается в одном элементе) или произвольного типа (название товара составляется из трех разных элементов). Подробнее о различии типов см. в разделе Информация о товарах в форматах YML и CSV (offers, offer). |
Описание входящих элементов
| __ | Элемент | ________ | Описание |
| name | Короткое название магазина. В названии нельзя использовать слова, которые не относятся к наименованию магазина (например «лучший», «дешевый»), указывать номер телефона и т. п. | ||
| company | Полное наименование компании, владеющей магазином. Не публикуется. | ||
| categories | Список категорий магазина. Обязательно должен быть перед списком предложений (offers). Используйте свои собственные типы описаний. | ||
| offers | Список предложений магазина. Каждое предложение описывается в отдельном элементе offer. Здесь не приводится список всех элементов, входящих в offer, так как он зависит от типа предложения. Для большинства категорий товаров подходят следующие типы: Упрощенный тип Произвольный тип |
Различие между упрощенным и произвольным типами
Упрощенный тип: название предложения — name
Полное название товара — тип, производитель и модель — указывается в элементе name. Например:
<offer id="9012">
<name>Мороженица Brand 3811</name>
...
</offer>
Произвольный тип: название предложения — должен быть указан атрибут type со значением vendor.model
Название товара составляется из трех элементов — типа товара typePrefix, производителя vendor и модели model (подробнее об этих элементах см. в разделе vendor, model, typePrefix). Чтобы Маркет мог отличить предложение произвольного типа от упрощенного, к элементу offer нужно добавить атрибут type=<<vendor.model>>. Например:
<offer id="9012" type="vendor.model">
<typePrefix>Мороженица</typePrefix>
<vendor>Brand</vendor>
<model>3811</model>
...
</offer>В упрощенном и произвольном типах по-разному формируется название предложения: в упрощенном типе полное название товара — тип, производитель и модель — указывается в одном элементе, а в произвольном оно составляется из трех разных элементов.
Список и описание элементов
Элементы не должны быть пустыми — обязательно указывайте их значения, иначе предложения с ними обрабатываются некорректно и попадут в отчет об ошибках. Например, такая запись <sku></sku> приведет к ошибке.
По закону о защите прав потребителей продавец должен предоставить покупателю достоверную информацию о товаре, например срок годности или службы товара, страну производства и т. п. Вы можете передать эту информацию в прайс-листе, указать на сайте или сообщить ее покупателю иным образом.
| __ | Элементы, специфичные для упрощенного типа описания | __ | Описание элемента | __ | Обязательность |
| name | Полное название предложения, в которое входит: тип товара, производитель, модель и название товара, важные характеристики. Составляйте по схеме: что (тип товара) + кто (производитель) + товар (модель, название) + важные характеристики. Данные в name влияют на привязку к карточке товара. Рекомендуем ознакомиться с подробным описанием элемента. | Обязательно | |||
| Стандартные элементы | Описание | Обязательность | |||
| sku | Атрибут sku — идентификатор товарного предложения. Идентификатор предложения должен быть уникальным среди всех товарных предложений одного прайс-листа. Один из вариантов заполнения sku – артикул товара в системе Партнера. Может быть указан в offer id и тогда становится необязательным. | Необязательно | |||
| vendor | Название производителя | Обязательно | |||
| model | Модель товара | ||||
| vendorCode | Код товара, который ему присвоил производитель. | Необязательно | |||
| offer id | Идентификатор предложения или может быть sku – артикул товара в системе Партнера. Может состоять только из цифр и латинских букв. Максимальная длина — 20 символов. Должен быть уникальным для каждого предложения. В YML является атрибутом для offer. Подробное описание элемента. | Обязательно | |||
| bid | Размер ставки.В YML является атрибутом для offer. Подробное описание элемента. | Необязательно | |||
| count | Кол-во товара в наличии | Необязательно | |||
| categoryId | Идентификатор категории товара, присвоенный магазином (целое число, не более 18 знаков). | Обязательно | |||
| category | Название категории товара. | Необязательно | |||
| picture | URL-ссылка на картинку товара. Вы можете указать до 11 ссылок на картинки друг за другом. Первое изображение станет основным: его пользователи увидят на Маркете по умолчанию. Остальные изображения — дополнительные: вместе с основным они будут собраны в галерею на карточке товара. <picture>…</picture> <picture>…</picture> | Обязательно | |||
| video | URL — ссылка на видео на ютуб | Необязательно | |||
| description | Описание товара. В описании запрещено указывать: — Номера телефонов — адреса электронной почты — почтовые адреса, номера ICQ — логины мессенджеров — любые ссылки. — слова «скидка», «распродажа», «дешевый», «подарок» (кроме подарочных категорий), «бесплатно», «акция», «специальная цена», «новинка», «new», «аналог», «заказ», «хит». Информацию о разных модификациях товара (например, нельзя писать «товар в ассортименте»). Для каждой модификации нужно создать отдельное предложение. | Необязательно | |||
| country_of_origin | Страна производства товара. Информацию необходимо указывать по закону. Если поле будет не заполнено, товар может быть скрыт с витрины. | Необязательно | |||
| barcode | Штрихкод товара от производителя в одном из форматов: EAN-13, EAN-8, UPC-A, UPC-E.В YML элемент offer может содержать несколько элементов barcode.Данные в barcode влияют на привязку предложения к карточке товара и отображение правильных характеристик, которые соответствуют модификации товара на его карточке. Рекомендуем ознакомиться с подробным описанием элемента. | Необязательно | |||
| param | Все важные характеристики товара — цвет, размер, объем, материал, вес, возраст, пол, и т. д. Элемент не должен быть пустым.В YML элемент offer может содержать несколько элементов param (один элемент param — одна характеристика).Подробное описание элемента. | Обязательно | |||
| price | Стоимость товара | Необязательно | |||
| manufacturer_warranty | Официальная гарантия производителя.Возможные значения:true — товар имеет официальную гарантию производителя;false — товар не имеет официальной гарантии производителя. | Необязательно | |||
| weight | Вес товара в килограммах с учетом упаковки.В любой категории вес можно указывать с точностью до тысячных (например, 1.001 кг; разделитель целой и дробной части — точка).Если минимальное значение указано 0, ограничений по минимальному весу нет, и можно указывать начиная с одного грамма (0.001 кг). | Обязательно | |||
| dimensions | Габариты товара (длина, ширина, высота) в упаковке. Размеры укажите в сантиметрах.Формат: три положительных числа с точностью 0.001, разделитель целой и дробной части — точка. Числа должны быть разделены символом «/» без пробелов. | Обязательно |
