Требования и частые ошибки
Чек-лист для клиента и контент-менеджера перед подключением фида и при его сопровождении.
Требования к доступности файла
- Прямая HTTPS-ссылка без редиректов. Ссылка должна вести на сам XML, а не на страницу-заглушку.
- Анонимно или под авторизацией. Проще всего отдавать фид анонимно, но закрытый фид сервис тоже умеет — см. «Закрытый фид» ниже. Cookie-сессии и формы логина не поддерживаются.
- Не заархивирован и не под паролем. Отдаётся как
text/xml/application/xml. - Стабильная генерация. Если фид собирается динамически — он должен успевать отдаться в пределах таймаута (15 минут при регулярном импорте, 30 с при анализе в мастере создания проекта). Крупные каталоги лучше генерировать в статический файл по расписанию: анализ в мастере — самое узкое место, за 30 с многогигабайтный фид успевает отдаться только с быстрой отдачей.
- Размер до 2 ГБ.
Закрытый фид
Если выгрузка не должна быть доступна публично, закройте её авторизацией и укажите доступ в ЛК: карточка проекта → блок «Источник фида» → «Изменить» → поле «Авторизация фида». Тот же блок есть в мастере создания проекта — фид анализируется уже с доступом.
Поддерживаются два способа.
Базовая авторизация. Логин и пароль; сервис отправляет их стандартным заголовком Authorization: Basic ….
Авторизация по заголовку. Выбираете имя заголовка — Authorization, X-Api-Key, X-Auth-Token, Api-Key или «свой заголовок» с произвольным именем — и вводите значение.
Значение уходит в запрос как введено: если фид ждёт схему, пишите её в том же поле.
| Заголовок | Значение в поле | Что уходит в запросе |
|---|---|---|
| Authorization | Bearer eyJhbGciOi… | Authorization: Bearer eyJhbGciOi… |
| Authorization | Token abc123 | Authorization: Token abc123 |
| X-Api-Key | abc123 | X-Api-Key: abc123 |
Свой заголовок X-Feed-Token | abc123 | X-Feed-Token: abc123 |
Что стоит знать:
- Кнопка «Проверить доступ» рядом с полями — и в карточке, и в мастере — сходит по указанной ссылке с введёнными реквизитами и сразу скажет, пустил фид или нет, ещё до сохранения. Она проверяет именно доступ: содержимое фида разбирает импорт.
- Доступ хранится в зашифрованном виде и после сохранения в интерфейсе не показывается. Пустое поле пароля или значения при редактировании означает «оставить прежний», а не «стереть».
- Секрет не уходит на чужой хост: если фид отвечает редиректом на другой домен (или понижает
httpsдоhttp), заголовки с доступом снимаются. Редиректы внутри своего домена сервис проходит с доступом. - 401/403 в ответ на скачивание — отдельная ошибка «Фид отверг наш доступ»: ссылка жива, проверять надо логин или значение заголовка.
- Cookie-авторизация, формы логина и OAuth-редиректы не поддерживаются.
Требования к структуре
- Корень —
<yml_catalog>, внутри —<shop>, внутри —<categories>и<offers>(см. «Каркас YML»). - Кодировка
utf-8(илиwindows-1251— сервис сконвертирует). Кодировка в заголовке<?xml … encoding="…"?>должна соответствовать реальной. - Валидный XML: закрытые теги, экранированные
&,<,>в значениях.
Требования к данным офферов
- У каждого
<offer>— непустой уникальныйid. Оффер безidпропускается. - Заполнены данные под шесть обязательных ролей: имя, цена, ссылка, категория, изображение (идентификатор берётся из атрибута
id). См. «Обязательные роли». <price>— число без символов валюты и пробелов, дробная часть через точку (7990,79.50). Диапазоны недопустимы.<categoryId>указывает на листовую категорию; все её предки объявлены в<categories>. Товар в нескольких разделах — несколько тегов<categoryId>, первым — основной раздел.- Ссылки в
<url>и<picture>— абсолютные (или относительные от/, тогда достраиваются по хосту проекта).
Частые ошибки
| Ошибка | Последствие | Как исправить |
|---|---|---|
| Неверный корень/каркас | Импорт падает (expected yml_catalog/shop) | Привести иерархию к каркасу. |
| Ссылка отдаёт не XML (HTML, страница логина) | HTML-страница вместо XML → падение на разборе (expected yml_catalog) | Дать прямую HTTPS-ссылку на сам XML (обычные редиректы сервис проходит). |
| Фид закрыт, доступ не указан или неверен | 401/403 → «Фид отверг наш доступ» в карточке проекта | Заполнить доступ в блоке «Источник фида» — см. «Закрытый фид». |
| Товар добавлен во все уровни дерева категорий | Дубли, размывание релевантности | Привязывать только к листовой категории — предки развернутся сами. |
Пустой или нестабильный id / group_id | Оффер пропущен / варианты не группируются | Задать стабильные уникальные id; общий group_id вариантам. |
Плавающие имена <param> (Цвет/цвет) | Дубли фильтров | Держать имена и регистр постоянными. |
| Разные картинки у одного значения фильтра | Значение остаётся без картинки, строка в «Проблемах импорта» | Отдавать одну картинку на значение; галерея товара — это <picture>, а не картинка значения. |
| Оригинал 200×200 в картинке значения | Панель фильтров весит мегабайты: сервис картинки не уменьшает | Отдавать уменьшенную копию 48×48 (webp/png). |
| Пустые категории без товаров | Мусор в дереве | Не выгружать категории без офферов. |
| Цена с валютой/пробелами/диапазоном | Некорректная цена (или 0) | Отдавать чистое число. |
| Нестандартный тег «не виден» в поиске | Поле не задействовано | Включить нужную роль в ЛК (подробнее). |
| Битая кодировка (заголовок ≠ факт) | Кракозябры в выдаче | Согласовать encoding с реальной кодировкой. |
| Фид > 2 ГБ / медленная отдача | Не проходит анализ при создании проекта; регулярный импорт завершается ошибкой | Уменьшить/статически кэшировать фид. |
Что улучшает качество, но не обязательно
<vendor>— для фильтра по бренду и синтеза имени.<oldprice>— для подсветки скидок.<description>— расширяет полнотекстовый поиск (HTML будет вычищен).- Богатый набор
<param>(Цвет,Размер,Материал,Стиль…) — фасетные фильтры и лучшее ранжирование. - Атрибут
pictureу<param>— выбор цвета картинкой в фильтре вместо списка названий. - Несколько
<picture>— галерея в карточке. - Стабильные
group_id— группировка вариантов.
Мини-проверка перед подключением
bash
# Доступность, тип, размер (без прокси для локальных проверок)
curl -sI --noproxy '*' "https://example.com/feed.xml"
# Корень и первые теги
curl -s "https://example.com/feed.xml" | head -c 400
# Число офферов и категорий
curl -s "https://example.com/feed.xml" | grep -c "<offer "
curl -s "https://example.com/feed.xml" | grep -c "<category "
# Есть ли офферы без id (должно быть 0)
curl -s "https://example.com/feed.xml" | grep -oE "<offer [^>]*>" | grep -vc 'id="'