Импорт из YML-фида

YML - основной формат импорта товаров в Relavio Search. Фид должен быть доступен по URL и содержать категории в <categories> и товары в <offers>. Relavio читает файл потоково, поэтому формат подходит для больших каталогов.

Минимальный пример

xml

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2026-08-02 12:00">
    <shop>
        <name>Demo Shop</name>
        <company>Demo Company</company>
        <url>https://example.com</url>

        <categories>
            <category id="1">Смартфоны</category>
            <category id="2" parentId="1">iPhone</category>
        </categories>

        <offers>
            <offer id="iphone-15-128" available="true">
                <url>/products/iphone-15-128</url>
                <price>99990</price>
                <oldprice>109990</oldprice>
                <categoryId>2</categoryId>
                <picture>https://example.com/images/iphone-15.jpg</picture>
                <vendor>Apple</vendor>
                <name>iPhone 15 128GB Black</name>
                <description>Смартфон Apple iPhone 15 с памятью 128 ГБ.</description>
                <param name="Цвет">Черный</param>
                <param name="Память" unit="ГБ">128</param>
                <param name="Диагональ" unit="дюйм">6.1</param>
                <synonyms>айфон 15, iphone пятнадцать</synonyms>
            </offer>
        </offers>
    </shop>
</yml_catalog>

Требования к доступу

Фид должен открываться сервером Relavio по URL, указанному в настройках магазина.

Рекомендации:

используйте HTTPS;
отдавайте корректный XML без HTML-страницы авторизации;
не блокируйте сервер Relavio по User-Agent или IP;
не требуйте интерактивной авторизации;
обновляйте файл атомарно, чтобы Relavio не прочитал частично записанный XML.

Если URL недоступен или XML невозможно открыть, импорт завершится ошибкой.

Категории

Категории читаются из элементов <category>. Идентификатор берется из атрибута id, родительская категория - из parentId.

xml

<categories>
    <category id="10">Электроника</category>
    <category id="20" parentId="10">Смартфоны</category>
    <category id="30" parentId="20">Apple</category>
</categories>

Для товара указывается конечная категория:

xml

<categoryId>30</categoryId>

Relavio восстановит всю цепочку категорий: Электроника -> Смартфоны -> Apple. Эта цепочка используется в поиске, подсказках, описании карточки и фильтрах.

Если categoryId пустой или не найден в списке категорий, товар импортируется без категорий.

Товары

Каждый товар описывается элементом <offer>. Количество товаров в импорте считается по числу элементов <offer>.

xml

<offer id="product-123" available="true">
    ...
</offer>

Атрибут id используется как внутренний идентификатор товара и как externalId. Он должен быть стабильным между импортами.

Атрибут available преобразуется в булево значение. Используйте true или false.

Поддерживаемые поля offer

Поле	Обязательность	Как используется
`id` на `<offer>`	Рекомендуется	Идентификатор товара и внешний ID.
`available` на `<offer>`	Нет	Наличие товара.
`<name>`	Рекомендуется	Основное название товара.
`<model>`	Нет	Запасное название и синоним.
`<typePrefix>`	Нет	Запасное название и синоним.
`<vendor>`	Нет	Бренд товара.
`<description>`	Нет	Описание карточки и поисковый контекст.
`<categoryId>`	Нет	Привязка к дереву категорий.
`<price>`	Рекомендуется	Текущая цена.
`<oldprice>`	Нет	Старая цена.
`<picture>`	Нет	Изображения товара.
`<url>`	Рекомендуется	Ссылка на товар.
`<param>`	Нет	Атрибуты и фильтры.
`<synonym>` / `<synonyms>`	Нет	Дополнительные поисковые термины.
`<keyword>` / `<keywords>`	Нет	Дополнительные поисковые термины.

Если <name> пустой, Relavio использует первое непустое значение из <model>, <typePrefix> или offer id.

Ссылки на товары

Поле <url> может быть абсолютным или относительным.

xml

<url>https://example.com/products/iphone-15</url>

xml

<url>/products/iphone-15</url>

Если ссылка относительная, Relavio добавит к ней базовый URL магазина из настроек. Например при URL магазина https://example.com значение /products/iphone-15 станет https://example.com/products/iphone-15.

Изображения

Можно передать несколько элементов <picture>.

xml

<picture>https://example.com/images/iphone-front.jpg</picture>
<picture>https://example.com/images/iphone-back.jpg</picture>

Relavio удаляет дубли и сохраняет список изображений. Виджет использует первое доступное изображение для карточки товара.

Характеристики и фильтры

Характеристики передаются через <param>.

xml

<param name="Цвет">Черный</param>
<param name="Память" unit="ГБ">128</param>
<param name="Поддержка 5G">true</param>

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

Код атрибута формируется из name в slug-формате с нижним подчеркиванием. Например Объем памяти станет obem_pamyati.

Тип атрибута определяется автоматически:

числовое значение становится number;
остальные значения становятся string.

Атрибуты используются в фильтрах режима catalog-with-filters и как дополнительный поисковый контекст.

Синонимы и ключевые слова

Дополнительные поисковые термины можно передать отдельными полями:

xml

<synonyms>айфон 15, iphone пятнадцать, apple phone</synonyms>
<keywords>смартфон apple; телефон apple</keywords>

Также можно использовать <param> с названием synonym, synonyms, keyword, keywords, синонимы или ключевые слова.

xml

<param name="Синонимы">айфон, айфончик</param>
<param name="Ключевые слова">смартфон apple|iphone</param>

Разделители: запятая, точка с запятой, вертикальная черта или перенос строки.

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

Подсказки

Для подсказок Relavio строит фразы из названия товара по словам.

Например для товара iPhone 15 128GB Black будут сформированы подсказки:

iPhone;
iPhone 15;
iPhone 15 128GB;
iPhone 15 128GB Black.

Эти данные используются endpoint-ом /api/v1/search/suggests и виджетом в режиме suggests.

Индексация и прогресс

Перед импортом Relavio создает временный поисковый индекс. Товары индексируются пачками по 1000. После успешного завершения алиас магазина переключается на новый индекс.

Это снижает риск показать пользователям частично обновленную выдачу: старый индекс продолжает работать, пока новый импорт не завершится успешно.

Прогресс считается по отношению количества проиндексированных товаров к общему числу <offer>.

Частые ошибки

Фид не открывается

Проверьте URL, SSL-сертификат, редиректы, firewall и ограничения доступа. Relavio должен получить XML без ручной авторизации.

Ошибка XML

Проверьте закрывающие теги, экранирование спецсимволов и кодировку. Значения с &, < и > должны быть корректно экранированы или помещены в CDATA.

xml

<description><![CDATA[Скидка 10% & подарок при покупке]]></description>

Нет категорий в поиске

Проверьте, что <categoryId> товара совпадает с id категории в <categories>.

Нет фильтров

Проверьте, что характеристики передаются через <param name="...">. Пустые name игнорируются.

Неверные ссылки в карточках

Если в <url> передается относительный путь, проверьте базовый URL магазина в настройках Relavio.

Чек-лист перед запуском

У каждого товара есть стабильный offer id.
Основные товары имеют <name>, <price>, <url> и <picture>.
Категории описаны в <categories>, а товары ссылаются на них через <categoryId>.
Бренд передается в <vendor>.
Характеристики передаются через <param> с понятными названиями.
Синонимы и ключевые слова добавлены для популярных альтернативных запросов.
Фид доступен по публичному HTTPS URL.
XML проходит проверку валидности.

Импорт из YML-фида ​

Минимальный пример ​

Требования к доступу ​

Категории ​

Товары ​

Поддерживаемые поля offer ​

Ссылки на товары ​

Изображения ​

Характеристики и фильтры ​

Синонимы и ключевые слова ​

Подсказки ​

Индексация и прогресс ​

Частые ошибки ​

Фид не открывается ​

Ошибка XML ​

Нет категорий в поиске ​

Нет фильтров ​

Неверные ссылки в карточках ​

Чек-лист перед запуском ​