документация

Каркас YML-фида ​

Фид — это XML-документ с обязательной иерархией. Соблюдение структуры — половина успеха интеграции.

Обязательная иерархия ​

yml_catalog                     ← корень (обязателен)
└── shop                        ← обязателен
    ├── url                     ← адрес магазина (желателен)
    ├── currencies              ← блок валют (необязателен)
    ├── categories              ← дерево категорий
    │   └── category            ← повторяется
    └── offers                  ← список товаров (обязателен)
        └── offer               ← повторяется
            ├── <тег>           ← стандартные поля
            └── <param>         ← характеристики

Порядок и вложенность важны

Корень документа обязан быть <yml_catalog>, внутри — <shop>, а уже внутри него — <categories> и <offers>. Если каркас нарушен, импорт не пройдёт. Категории берутся только из блока <categories>, товары — только из <offers>.

Импорт останавливается с ошибкой, если нет блока <offers> или в нём не оказалось ни одного <offer>: прежние товары остаются в поиске, чтобы оборвавшаяся выгрузка не опустошила каталог. Как это изменить — «Фид без товаров».

Заголовок и кодировка ​

xml
<?xml version="1.0" encoding="utf-8"?>
<yml_catalog date="2026-07-13 09:43">
  • Поддерживаются кодировки utf-8 и windows-1251 (cp1251). Windows-1251 определяется по атрибуту encoding и конвертируется автоматически — фид можно отдавать «как есть».
  • Атрибут date информационный, на разбор не влияет.

Блок магазина <shop> ​

Из метаданных магазина важен только адрес: хост берётся из ссылки на фид, указанной в проекте, и используется, чтобы достроить относительные ссылки на товар и картинки до абсолютных. Остальные метаданные (name, company, agency, cpa) на индекс не влияют. Валюта берётся не из блока <currencies>, а из тега <currencyId> каждого оффера.

Категории <categories> ​

xml
<categories>
  <category id="1">Одежда</category>
  <category id="42" parentId="1" url="https://example.com/catalog/yubki/">Юбки</category>
</categories>
Атрибут/значениеОбяз.Назначение
id✅Уникальный идентификатор: число, строка или UUID — подойдёт любой, лишь бы parentId и <categoryId> ссылались ровно на него. Категория без id игнорируется.
parentId—Родительская категория. Отсутствие/пустое значение → категория корневая.
url—Ссылка на страницу категории. Запасной источник для ссылки на товар (см. оффер → url).
текст элемента✅Название категории. Попадает в результаты поиска.

Дерево категорий и «цепочка предков» ​

Категории образуют дерево через parentId. Для каждого товара сервис строит полную цепочку предков от корня до его категории. Поэтому в результатах поиска доступны и категория товара, и все её родители.

Пример: товар с <categoryId>2</categoryId> при дереве Одежда(1) → Платья(2) будет находиться и по «Одежда», и по «Платья».

Если товар входит в несколько разделов каталога (типично для выгрузок из Битрикса), укажите несколько тегов <categoryId> — товар будет находиться и фильтроваться по каждому из них (вместе с их предками). Первым укажите основной раздел товара: он используется как запасной источник ссылки на карточку (см. оффер → url).

xml
<categoryId>79</categoryId>   <!-- основной раздел -->
<categoryId>88</categoryId>
<categoryId>93</categoryId>

Привязывайте товар к листовой категории

Указывайте в <categoryId> самую глубокую (листовую) категорию. Все её родители подставятся автоматически. Дублировать товар во всех уровнях одной ветки дерева не нужно и вредно — это размывает релевантность.

Блок офферов <offers> ​

Контейнер всех товарных предложений. Каждый <offer> — отдельный товар в выдаче. Подробный разбор атрибутов и полей — на следующей странице: «Оффер: атрибуты и поля».

xml
<offers>
  <offer id="5684" available="false" group_id="5652">
    <url>https://example.com/product/baska-.../</url>
    <categoryId>38</categoryId>
    <price>10100</price>
    <picture>https://example.com/upload/.../105b68.jpg</picture>
    <name>Баска на завышенной талии с кантом</name>
    <vendor>Acme</vendor>
    <param name="Цвет" picture="https://example.com/swatch/white.webp">белый</param>
    <param name="Размер">XS</param>
  </offer>
</offers>

Атрибут picture у характеристики

Необязательный, но заметный на витрине: по нему фильтр «Цвет» показывает образец рядом с названием значения вместо голого списка — см. «Вид значений в фильтре».