Требования к товарному фиду

ShopStory использует товарный фид для каталога, связки товаров с эфирами и состояния кнопки покупки. Одно строковое значение feedProductId связывает товар в фиде, на web-PDP, в Mobile SDK и в product action. Основной формат — YML. Другие XML-схемы подключаются после согласования маппинга полей.

Доступ к источнику​

Фид должен быть доступен ShopStory по HTTPS одним из способов:

• публичный URL;
• URL с HTTP Basic Auth.

Для защищённого фида передайте реквизиты через согласованный защищённый канал. Не добавляйте логин и пароль в URL вида https://user:password@example.ru/feed.xml.

Источник должен возвращать валидный XML с кодировкой UTF-8. URL карточек и изображений также должны использовать HTTPS и открываться без пользовательской сессии.

Несколько версий фида​

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

Проект подключается к одной согласованной версии. Её цена и её состав отображаются в плеере и mini-player всем зрителям, независимо от того, где находится зритель.

Поэтому передайте при подключении:

Если цена или ассортимент зависят от региона покупателя, поведение для зрителей из других зон согласуется отдельно. Обработчик наличия эту разницу не покрывает: он отвечает за доступность покупки и не меняет цену, название и состав каталога.

Идентификаторы товара​

Для каждой позиции требуется стабильный строковый идентификатор:

• id у элемента offer — рекомендуемый источник feedProductId;
• vendorCode — артикул или SKU продавца.

Рекомендуется передавать оба поля, но во время подключения ShopStory и клиент выбирают одно значение как feedProductId. Оно без изменения формата используется в ShopStory, на сайте, в приложении и в действиях с товаром. vendorCode может оставаться внутренним SKU продавца; если commerce API принимает другой ключ, маппинг выполняется на стороне системы продавца.

Для ранее подключённых проектов может быть согласован поиск по vendorCode. Не смешивайте этот legacy-мэппинг с новым feedProductId в одной интеграции.

Правила для идентификаторов:

• не переиспользуйте значение для другого товара;
• не меняйте формат между выгрузками;
• сохраняйте ведущие нули и регистр, если они значимы;
• передавайте их как строки, даже если значение состоит только из цифр.

Изменение id или vendorCode может создать новую товарную запись. Уже существующая связка товара с эфиром автоматически на неё не переносится.

Поля YML​

«Для публикации» означает, что технически строка может быть прочитана без поля, но корректную карточку товара из неё сформировать нельзя. ShopStory проверяет состав полей и маппинг до первой синхронизации.

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

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2026-09-04 10:00:00">
  <shop>
    <offers>
      <offer id="0001001" available="true">
        <name>Крем для рук</name>
        <url>https://example.ru/products/0001001</url>
        <price>299.00</price>
        <oldprice>349.00</oldprice>
        <currencyId>RUB</currencyId>
        <picture>https://cdn.example.ru/products/0001001.webp</picture>
        <vendor>Example Brand</vendor>
        <vendorCode>ART-0001001</vendorCode>
      </offer>
    </offers>
  </shop>
</yml_catalog>

Не копируйте пример как готовый маппинг цен. Если ERP передаёт текущую и старую цену иначе, это фиксируется в клиентском приложении к интеграции.

Как обновляется доступность​

При стандартной синхронизации:

1. ShopStory успешно загружает и проверяет новую версию фида.
2. Для товара с теми же согласованными идентификаторами обновляются цена, карточка и available.
3. Оффер с available="false" становится недоступным для покупки.
4. Товар, исчезнувший из успешно обработанного полного фида, также может быть отмечен недоступным согласно согласованному правилу импорта.
5. Live и VOD используют одно состояние доступности: товар остаётся в эфире, но кнопка покупки блокируется.

Уже открытый плеер использует полученный ранее снимок товарных данных. Новое значение появляется после следующей полной загрузки данных или перезагрузки страницы; фид не опрашивается в реальном времени.

В Public API этот снимок возвращается в body.products[].feedProductAvailable ответа GET /v3/streams. Поле не содержит количество единиц и не подтверждает наличие в выбранном магазине.

Если требуется остаток конкретного магазина, снимок фида дополняется live-проверкой: Web SDK запрашивает наличие у обработчика на сайте ритейлера и обновляет карточки его ответом. Семантика available в вашем фиде при этом определяет приоритет источников — остаток или вывод товара из ассортимента. Оба режима описаны в разделе Наличие товара и остатки.

Проверка перед подключением​

1. URL открывается из внешней сети по HTTPS и возвращает XML, а не HTML-страницу входа.
2. XML проходит синтаксическую проверку.
3. В каждом offer есть значение в поле, выбранном источником feedProductId; оно совпадает с тестовой web- или mobile-PDP.
4. Ведущие нули в идентификаторах не потеряны.
5. url и picture доступны без cookie пользовательской сессии.
6. available принимает только согласованные значения и проверен на нескольких доступных и недоступных товарах.
7. Тестовый импорт подтверждён до включения регулярной синхронизации.

Связанные разделы​

• Наличие товара и остатки
• Каталог эфиров
• Mini-player
• Mobile SDK
• Добавление товара в корзину