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

ShopStory работает с двумя разными состояниями товара, и их важно не смешивать.

Каталог — какие товары показаны в эфире, с какими названием, изображением и ценой. Источник каталога всегда товарный фид.

Наличие — можно ли купить товар прямо сейчас.

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

Какой вариант ваш​

Проверок две, и они независимы. Достаточно одной сработавшей, чтобы ваш вариант был B.

1. Цены. Если каталог выгружается в нескольких версиях по регионам или ценовым зонам — это вариант B. Плеер показывает цену подключённой версии всем зрителям, поэтому версию нужно выбирать осознанно: Несколько версий фида.
2. Наличие. Откройте выгрузку и поищите available="false". Если в вашем фиде нет ни одного available="false", признак наличия в нём отсутствует — так устроены рекламные выгрузки вроде Yandex smart feed и Google Merchant: отсутствующий товар просто не попадает в файл. Тогда вариант A вам не подойдёт независимо от цен, и увеличение частоты синхронизации ничего не изменит.

Вариант A. Один фид и единые цены​

Ничего дополнительно подключать не нужно.

ShopStory синхронизирует фид по согласованному расписанию и берёт из него название, изображение, цену и признак available. Товар с available="false" остаётся в эфире, но действие покупки заблокировано. Проверку в момент покупки выполняет ваша корзина: Добавление в корзину.

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

Если сработала только проверка про цены, вам нужна из варианта B лишь его первая часть — выбор версии выгрузки. Обработчик наличия при этом не требуется.

Вариант B. Разные цены и живые остатки​

Вариант состоит из двух независимых частей, и подключать их можно по отдельности.

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

Наличие приходит от обработчика наличия — функции на стороне сайта ритейлера, которая обращается к его собственному stock API с выбранным магазином покупателя. Это штатная возможность Web SDK: отдельная разработка на стороне ShopStory для неё не нужна.

Что делает каждая сторона​

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

Требование к stock API одно: он должен отвечать по всем товарам эфира внутри дедлайна обработчика. Если API отвечает по одному товару за запрос, посчитайте: число товаров в эфире, делённое на допустимую параллельность, умноженное на время ответа. Не укладывается — понадобится пакетный метод или обёртка над существующим.

Чего интеграция не требует:

• открывать stock API во внешнюю сеть — запрос идёт из браузера покупателя к тому же origin, что и остальные запросы сайта;
• передавать ShopStory учётные данные, ключи или адреса внутренних сервисов;
• отдавать ShopStory остатки, справочник магазинов или привязку покупателей к ним;
• менять товарный фид, добавлять в него поля или увеличивать частоту выгрузки;
• поддерживать отдельный контракт для записей: live и VOD работают одинаково.

Как устроен процесс​

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

Кто определяет магазин покупателя​

ShopStory не определяет город, регион и магазин покупателя, не запрашивает геолокацию и не хранит выбор магазина.

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

Обработчик наличия — это функция в коде сайта ритейлера. Она читает то же состояние, что и остальные его страницы, и сама подставляет магазин в свой запрос. Контекст покупателя не является аргументом обработчика, в ответе не возвращается и на серверы ShopStory не уходит.

Сопоставление на стороне ShopStory только товарное: ключи карты ответа сверяются с feedProductId из фида. Это тот же идентификатор, который уже используется в действии корзины, поэтому отдельного сопоставления покупателей, магазинов или сессий не возникает.

Контракт обработчика​

Обработчик передаётся вместе с действиями корзины в вызов ShopStorySDK.show().

type ProductAvailabilityMap = Record<string, boolean>;

type ClientActions = {
  resolveProductsAvailability?: (
    feedProductIds: string[],
    callback: (availability: ProductAvailabilityMap) => void,
  ) => void;
  // Обработчики корзины передаются в тот же объект actions
  // и описаны отдельно: ./add-to-cart.md#web-sdk-callback
};

feedProductIds — массив строковых идентификаторов в том же формате, что и в фиде. Обрабатывайте ровно тот список, который пришёл в аргументе, и не додумывайте его состав.

Обычно это все товары текущего эфира. Но когда товары добавляются в уже идущий эфир, SDK передаёт только добавленные идентификаторы, чтобы не перезапрашивать то, что уже известно. Полный перечень поводов для вызова — в разделе Когда SDK запрашивает наличие.

Чего не бывает никогда: вызова на один товар при показе карточки. Обработчик всегда получает список.

Контекст покупателя в аргументы не входит — см. Кто определяет магазин покупателя.

Карта ответа​

Верните объект, ключи которого — идентификаторы из запроса:

Возвращайте ключ только для тех товаров, по которым получен достоверный ответ. Не подставляйте false вместо неизвестного результата: ошибка API — это не подтверждённое отсутствие товара.

Обратное тоже важно. Отсутствие ключа означает «не удалось узнать», а не «товар покупателю не положен». Если вы знаете, что товар недоступен — не входит в ассортимент его региона, снят с продажи, недоступен для выбранного способа получения, — возвращайте false. Пропущенный товар останется доступным к покупке по снимку фида.

Ключи, которых не было в запросе, игнорируются. Повторный вызов callback игнорируется.

Пример​

// Пример для stock API, который отвечает по одному товару за запрос.
// Если у вашего API есть пакетный метод, замените checkOne и очередь
// одним запросом со всем списком — остальная часть обработчика не изменится.
const STOCK_CONCURRENCY = 4;
const STOCK_DEADLINE_MS = 4000;

function checkOne(feedProductId, storeId, signal) {
  return fetch(
    '/api/stock/' + encodeURIComponent(feedProductId) + '?store=' + encodeURIComponent(storeId),
    { credentials: 'same-origin', signal },
  )
    .then(function (response) {
      if (!response.ok) return null;
      return response.json();
    })
    .then(function (data) {
      // null => «не смогли узнать»: ключ в карту не попадёт
      return data && typeof data.inStock === 'boolean' ? data.inStock : null;
    })
    .catch(function () {
      return null;
    });
}

ShopStorySDK.show({
  containerElement: document.getElementById('shopstory'),
  config: { clientId: 'assigned-application-id' },
  cartUrl: '/cart/',
  actions: {
    resolveProductsAvailability: function (feedProductIds, callback) {
      const storeId = readSelectedStoreId();
      const controller = new AbortController();
      const deadline = setTimeout(function () { controller.abort(); }, STOCK_DEADLINE_MS);

      const availability = {};
      const queue = feedProductIds.slice();

      function worker() {
        const id = queue.shift();
        if (id === undefined) return Promise.resolve();
        return checkOne(id, storeId, controller.signal).then(function (inStock) {
          if (inStock !== null) availability[String(id)] = inStock;
          return worker();
        });
      }

      const workers = [];
      for (let i = 0; i < STOCK_CONCURRENCY; i += 1) workers.push(worker());

      Promise.all(workers)
        .catch(function () { /* частичный результат сохраняем */ })
        .then(function () {
          clearTimeout(deadline);
          callback(availability);
        });
    },
  },
});

Обратите внимание: обработчик вызывает callback один раз, отдавая то, что успел собрать к дедлайну. Товары, по которым ответа не пришло, в карту не попадают и остаются в состоянии по фиду. Поэтому дедлайн внутри обработчика должен быть меньше тайм-аута SDK — иначе весь ответ потеряется целиком.

Если ваш stock API отвечает по одному товару, оцените заранее: число товаров в эфире, делённое на допустимую параллельность, умноженное на время ответа, должно укладываться в этот дедлайн. Не укладывается — нужен пакетный метод или backend-for-frontend, который его изобразит.

AbortController и setTimeout использованы вместо AbortSignal.timeout() намеренно: последний недоступен в Safari до 16.4, а исключение внутри обработчика SDK не отличит от отказа API.

В этом примере показан только обработчик наличия. Обработчик корзины передаётся в тот же объект actions.

callback({}) — корректный ответ «данных нет». Он не ломает плеер и не помечает товары отсутствующими.

Адаптируйте пример к своей платформе: имена полей, защиту сессии и способ получения выбранного магазина. Пример рассчитан на same-origin endpoint ритейлера. Если stock API находится на другом origin или требует серверной авторизации, вызывайте его через backend-for-frontend ритейлера: учётные данные не должны попадать в JavaScript или в конфигурацию ShopStory.

Смена магазина​

Когда покупатель меняет магазин, регион или способ получения, сайт сообщает об этом SDK:

function onStoreChanged() {
  if (window.ShopStorySDK && window.ShopStorySDK.refreshProductsAvailability) {
    window.ShopStorySDK.refreshProductsAvailability();
  }
}

Метод делает три вещи: снимает уже применённые ответы, отменяет незавершённые запросы и вызывает обработчик заново. Ответы прежнего магазина на карточку попасть не могут — ни те, что были показаны, ни те, что придут с опозданием.

До прихода новых данных карточки показывают состояние по снимку фида.

Метод ничего не возвращает и безопасен для повторных вызовов — быстрое переключение города подряд не создаёт гонки. Если обработчик не задан, вызов не делает ничего. Обновляйте выбранный магазин на своей стороне до вызова метода, а не после.

Метод относится к плееру, созданному вызовом show(). Контракт рассчитан на один такой экземпляр на странице; сценарий с двумя одновременными плеерами на одной странице не поддержан.

Когда SDK запрашивает наличие​

Других поводов нет. Обработчик не вызывается при показе или открытии отдельной карточки, не опрашивается по расписанию и не работает при закрытом плеере. Единственный внутренний таймер — тайм-аут запроса.

Полученный ответ живёт до смены магазина, смены эфира или закрытия плеера. Срока давности у него нет: ответ не «протухает» сам по себе, потому что состояние, придуманное таймером, было бы хуже честного ответа мерчанта. Если наличие должно обновляться чаще, вызывайте refreshProductsAvailability() из своего кода.

Тайм-аут обработчика — 5 секунд, значение фиксировано. Он ограничивает ожидание одного вызова, не частоту вызовов.

Приоритет источников​

Обработчик может только снять доступность. Товар, закрытый фидом, остаётся недоступным независимо от ответа обработчика; товар, открытый фидом, обработчик может закрыть.

Правило одностороннее намеренно. Оно исключает случай, когда live-ответ возвращает в продажу позицию, снятую с ассортимента или ограниченную к обороту.

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

Это важно для каталогов с ценовыми зонами: если у вас несколько версий выгрузки, плеер показывает цену и состав той версии, которая подключена к проекту. Обработчик наличия этого не меняет — см. Несколько версий фида.

Ошибки и неизвестное наличие​

Проверка наличия не должна ломать просмотр. Поведение рассчитано на то, что stock API ритейлера временно недоступен.

Обновление наличия не отменяет уже запущенное добавление в корзину. Начатая операция доводится до своего результата — успеха, ошибки или тайм-аута, — даже если в это время карточка сменила состояние доступности.

Карточки отрисовываются сразу по данным фида и обновляются при получении ответа. Первый показ плеера и старт видео не ждут stock API.

Что ShopStory не делает​

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

• не обращается к stock API ритейлера напрямую и не хранит его учётные данные;
• не запрашивает и не хранит остатки магазинов и товаров за пределами текущего эфира;
• не записывает пользовательский остаток в общее поле feedProductAvailable: ответ обработчика живёт в памяти открытой вкладки, относится только к этому покупателю, не уходит на серверы ShopStory и не сохраняется;
• не передаёт в обработчик персональные данные покупателя и не получает их в ответе — ответ это карта «идентификатор → доступность», и ничего больше;
• не требует открывать stock API во внешнюю сеть и не требует сетевого доступа со стороны ShopStory;
• не опрашивает API по таймеру и не создаёт фоновый трафик при закрытом плеере.

Верхняя граница нагрузки на stock API считается просто: один вызов обработчика на открытие эфира, один на смену магазина и один на добавление товаров в идущий эфир. Размер вызова — число товаров, по которым запрашивается наличие. Вызовов при показе отдельной карточки нет.

Поверхности​

Обработчик не переносится между поверхностями: заданный в show() на одной странице, он не действует в плеере, открытом из standalone PiP, и в нативном приложении. Каждая поверхность получает его в своей точке инициализации, которая фиксируется в integration handoff проекта.

Public API без SDK​

GET /v3/streams возвращает снимок фида в body.products[].feedProductAvailable. Значение содержит булев признак и не передаёт количество единиц, остаток магазина или время обновления товара; serverTime — время ответа API, а не время синхронизации.

Отдельного endpoint проверки остатков в Public API нет: остаток по магазину — данные ритейлера, и правильное место их запроса — его собственный код. При интеграции через Public API проверку наличия выполняет интерфейс клиента до показа действия покупки.

Данные для подключения​

Обработчик — штатная возможность SDK, но стыковка с конкретным stock API требует согласования:

Точные URL, схемы запросов, учётные данные, лимиты и правила магазинов не публикуются: они фиксируются в закрытом приложении к интеграции. Порядок согласования — в разделе Кастомные commerce-интеграции.

Проверка перед production​

1. Обработчик получает те же строковые идентификаторы, что переданы в фиде, без числового преобразования и потери ведущих нулей.
2. Товар с наличием показывает доступное действие покупки, товар без наличия — состояние «Нет в наличии».
3. Товар, закрытый фидом, остаётся заблокированным, даже когда обработчик вернул true.
4. Смена магазина обновляет карточки, а ответ для прежнего магазина на них не попадает.
5. Недоступный stock API не блокирует покупку целиком, не показывает ложное «Нет в наличии» и не прерывает видео.
6. Тайм-аут обработчика не задерживает первый показ карточек и старт воспроизведения.
7. Добавление в корзину во время обновления наличия завершается ожидаемым результатом.
8. Endpoint остатков не отдаёт данные без действующей пользовательской сессии и не раскрывает внутренние ошибки.
9. Поведение проверено на desktop и mobile web в целевых браузерах проекта.

Диагностика​

При обращении в поддержку передайте URL страницы, applicationId, время, идентификаторы проверяемых товаров и выбранный магазин. Учётные данные, cookies и персональные данные покупателя в обращение не включайте.

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

• Требования к товарному фиду
• Добавление товара в корзину
• Web SDK
• Кастомные commerce-интеграции
• Каталог эфиров
• OpenAPI и Postman