Каталог товаров (YML)

Требования к файлу каталога: структура YML, обязательные элементы, формирование названия товара, обновление и результаты импорта

Каталог товаров загружается в Aplaut файлом XML в формате YML, кодировка UTF-8. Большинство CMS генерируют такой файл автоматически; подходят и фиды, подготовленные для других платформ, если в них есть весь ассортимент, доступный на сайте.

Файл забирается по ссылке (http, https, ftp) или загружается вручную. Поддерживаются .xml, а также архивы .zip и .gzip. Автоматический импорт по активной настройке запускается раз в сутки в 00:00 по московскому времени.

Структура файла

Файл начинается с заголовка XML и корневого элемента yml_catalog:

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2025-11-01 17:22">
  <shop>
    <name>ACME Shop</name>
    <url>https://yoursite.ru</url>
    <categories>...</categories>
    <offers>...</offers>
  </shop>
</yml_catalog>

Атрибут date на импорт не влияет

Aplaut не читает атрибут date у yml_catalog. Изменился ли каталог, платформа определяет по контрольной сумме скачанного файла: она сравнивается с последней успешно выполненной задачей импорта по тому же имени файла.

Поэтому изменённый файл с прежней датой импортируется нормально, а файл с новой датой и прежним содержимым импорт отменит. Отсутствующий или некорректный date ни на что не влияет.

Внутрь <shop> помещаются список категорий <categories>, список товаров <offers> и, если вы работаете по модели маркетплейса, список продавцов <merchant>.

Элементы <name>, <company>, <url> и <platform> внутри <shop> Aplaut не импортирует: из файла обрабатываются только категории, товары и продавцы. Оставлять их в фиде можно, на импорт они не влияют.

Категории

Категории перечисляются в <categories> элементами <category> с атрибутом id. Вложенность задаётся атрибутом parentId:

<categories>
  <category id="1">Телефоны</category>
  <category id="10" parentId="1">Смартфоны</category>
</categories>

Блок <categories> располагается в файле до <offers>. Товары обрабатываются по мере чтения файла, поэтому категория, описанная после товаров, может не успеть создаться.

Структура и вложенность категорий повторяют сайт: по категории настраиваются дополнительные критерии оценки и поля формы отзыва в виджетах.

Товары

Товары перечисляются в <offers> элементами <offer>.

Атрибуты offer

Атрибут	Обязательный	Описание
`id`	Да	Уникальный идентификатор товара в рамках компании. Пробелы по краям обрезаются
`group_id`	Нет	Идентификатор группы товаров-вариантов. Принимаются написания `group_id`, `group-id` и `groupId`
`available`	Нет	Признак наличия товара. Товар считается отсутствующим только при значении `false`; любое другое значение, как и отсутствие атрибута, означает наличие
`type`	Нет	Способ формирования названия товара. Допустимые значения — `vendor.model` и `artist.title`

Вложенные элементы offer

Элемент	Обязательный	Описание
`name`	Да, если не задан `type`	Полное наименование товара
`url`	Да	URL карточки товара на сайте
`categoryId`	Нет	Идентификатор категории товара. Без него товар привязывается к корневой категории компании
`picture`	Нет	Ссылка на изображение товара. Можно передать несколько
`vendor`	Нет	Бренд товара
`model`	Нет	Модель товара
`typePrefix`	Нет	Тип или категория товара в названии
`vendorCode`	Нет	Артикул производителя
`alias`	Нет	Дополнительный идентификатор товара. По нему платформа ищет ранее импортированный товар, если эта настройка включена в параметрах импорта
`rec`	Нет	Рекомендованные товары: идентификаторы через запятую
`barcode`	Нет	Штрихкод товара. Можно передать несколько
`merchant`	Нет	Идентификаторы продавцов, которым принадлежит товар. Можно передать несколько; при повторном импорте новые значения добавляются к сохранённым, а не заменяют их
`custom_attributes`	Нет	Произвольные атрибуты товара в виде JSON-строки. При повторном импорте объединяются с сохранёнными
`artist`, `title`	Нет	Части названия при `type="artist.title"`
`price`	Нет	Не импортируется. Цена передаётся только через Platform API

Элементы <description> и <param> импортируются, только если в настройках импорта включены Импортировать описание товара и Импортировать свойства товара. По умолчанию оба тумблера выключены, и эти данные в платформу не попадают.

Формирование названия товара

Источник названия определяет атрибут type.

Значение `type`	Из чего собирается название
Не задан, пустой или любое другое значение	Элемент `name`
`vendor.model`	`typePrefix` + `vendor` + `model`, через пробел. Значение `name` игнорируется
`artist.title`	`artist` + `title`, через пробел

Правила сборки из частей:

typePrefix и vendor не подставляются, если они пустые или если такой текст уже есть внутри model. Совпадение ищется по подстроке без учёта регистра.
Если model пустой или не передан, сборка не срабатывает, и название берётся из name.
HTML-сущности в названии раскодируются: " превращается в ".

Пример: при vendor = Samsung и model = 750 EVO SATA 2.5" SSD 250ГБ (MZ-750250BW) название товара станет Samsung 750 EVO SATA 2.5" SSD 250ГБ (MZ-750250BW). Если бы model начиналась со слова Samsung, бренд второй раз не подставился бы.

Ограничения

Ограничение	Значение	Область действия
Длина названия товара	400 символов	Один товар
Длина `vendorCode`	400 символов	Один товар
Уникальность `id`	Идентификатор не повторяется	Одна компания
Категорий у товара	Одна основная, остальные дополнительные	Один товар

Товар создаётся, если у него есть id, название и url. Категория подставляется автоматически, если её нет в файле, поэтому товар без categoryId импортируется.

Повторный импорт ищет ранее загруженный товар не по самому id, а по его URL-безопасной форме. Из-за этого два разных идентификатора, которые приводятся к одинаковой форме, конфликтуют: второй товар не пройдёт проверку уникальности и попадёт в ошибки. Чтобы этого не было, используйте латиницу, цифры, дефис и подчёркивание.

Регистр id по умолчанию сохраняется. Если в фиде идентификаторы приходят в разном регистре, в настройках компании включается приведение id товара к нижнему регистру.

Если включена настройка поиска товара по alias, платформа ищет товар и по этому идентификатору тоже.

Несколько категорий у товара

Товар привязывается к первому элементу <categoryId> внутри <offer> — порядок в <categories> при этом не учитывается. Эта категория считается основной и используется для настроек формы отзыва.

Остальные значения <categoryId> сохраняются как дополнительные категории и учитываются в отчётах и фильтрах по категории.

Если categoryId ссылается на категорию, которой нет в <categories>, товар привязывается к корневой категории компании. Импорт при этом не прерывается и ошибку не возвращает. Дополнительные категории, которых нет в <categories>, отбрасываются.

Изображения

Ссылки из всех элементов <picture> сохраняются в порядке следования в файле. Для отображения используется первая. Если <picture> нет, подставляется изображение-заглушка Aplaut.

Изображения при импорте не скачиваются и не проверяются, платформа хранит только ссылку. Недоступная ссылка на импорт не влияет, товар просто отобразится без картинки.

Повторный импорт и обновление товаров

Если контрольная сумма файла совпадает с последним успешным импортом того же файла, задача завершается статусом «Отменён» с причиной «содержимое файла не изменилось», и товары не меняются.

Если group_id в файле пустой, поведение зависит от параметров импорта: платформа либо очистит группу у товара, либо оставит сохранённое значение.

При обновлении существующего товара пустые и отсутствующие в файле значения не затирают сохранённые: старое значение остаётся. По умолчанию товар обновляется, только если данные изменились. Принудительное обновление включает настройка Обновлять атрибуты ранее импортированных товаров.

Товары, пропавшие из новой версии фида, остаются в каталоге с прежними значениями. Автоматически они не удаляются и не скрываются, обновляется только дата последнего импорта — по ней в личном кабинете собирается сегмент товаров, которые перестали приходить. Полное удаление каталога — отдельная операция, частью импорта она не является.

Результат импорта и ошибки

Задачи импорта и их результаты находятся в разделе Настройки → Импорт данных.

Статус задачи	Что означает
В очереди	Задача создана и ждёт выполнения
В работе	Файл скачивается или обрабатывается
Выполнен	Файл обработан
Не выполнен	Файл не удалось скачать, распаковать или разобрать
Отменён	Импорт остановлен, причина указана в задаче

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

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

Расшифровку ошибок по товарам запрашивают у поддержки

В задаче импорта видно количество ошибок, но не то, какие именно товары их вызвали. Список идентификаторов с причинами доступен сотрудникам Aplaut — запросите его в поддержке.

Пример файла

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2025-11-01 17:22">
  <shop>
    <name>ACME Shop</name>
    <company>ACME inc.</company>
    <url>https://yoursite.ru</url>
    <platform>Bitrix24</platform>

    <categories>
      <category id="1">Телефоны</category>
      <category id="10" parentId="1">Смартфоны</category>
    </categories>

    <offers>
      <offer id="100" available="true" group_id="1000">
        <categoryId>10</categoryId>
        <name>Смартфон Apple iPhone 7 128GB Space Gray</name>
        <vendor>Apple</vendor>
        <url>https://yoursite.ru/100.html</url>
        <picture>https://yoursite.ru/1580.jpg</picture>
      </offer>

      <offer id="101" available="true" group_id="1000" type="vendor.model">
        <categoryId>10</categoryId>
        <typePrefix>Смартфон</typePrefix>
        <vendor>Apple</vendor>
        <model>iPhone 7 64GB Space Gray</model>
        <vendorCode>NWC22RU/A</vendorCode>
        <url>https://yoursite.ru/101.html</url>
        <picture>https://yoursite.ru/1581.jpg</picture>
        <picture>https://yoursite.ru/1582.jpg</picture>
      </offer>
    </offers>
  </shop>
</yml_catalog>

У товара 101 название соберётся из трёх элементов: Смартфон Apple iPhone 7 64GB Space Gray.

Структура файла​

Категории​

Товары​

Атрибуты offer​

Вложенные элементы offer​

Формирование названия товара​

Ограничения​

Несколько категорий у товара​

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

Повторный импорт и обновление товаров​

Результат импорта и ошибки​

Пример файла​