Формат запросов и ответов

Базовый адрес и версии​

Публичные эндпоинты только для чтения доступны на https://app.shopstory.live.

Версия в URL зависит от семейства ресурсов:

• /v3/streams и /v3/translation/quick-state — каталог и состояние трансляций;
• /v2/mini-player/* — выбор live или записи для товара.

Не заменяйте /v2 на /v3 механически.

JSON-конверт​

Ответ API обычно имеет три верхнеуровневых поля:

{
  "status": 200,
  "serverTime": "2025-01-15T10:15:30.000Z",
  "body": {}
}

Два уровня результата​

Проверяйте HTTP-код и status в JSON независимо. У некоторых /v3/* валидационная ошибка передаётся с HTTP 200 и status: 400 внутри конверта.

{
  "status": 400,
  "body": {
    "error": "invalid",
    "message": "invalid applicationId"
  },
  "serverTime": "2025-01-15T10:15:30.000Z"
}

Если для товара нет подходящего видео, mini-player возвращает пустое состояние: HTTP 200, body.status: "no_active_stream", body.stream: null.

Обрабатывайте ответ в таком порядке:

async function readShopStoryResponse(response) {
  if (!response.ok) {
    throw new Error(`ShopStory HTTP ${response.status}`);
  }

  const payload = await response.json();

  if (!Number.isInteger(payload.status)) {
    throw new Error('Invalid ShopStory response envelope');
  }

  if (payload.status < 200 || payload.status >= 300) {
    throw new Error(payload.body?.message || `ShopStory status ${payload.status}`);
  }

  return payload.body;
}

После распаковки отдельно проверяйте состояние ресурса, например body.status у mini-player.

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

applicationId, streamId, id, feedProductId, feedProductGroupId и vendorCode обрабатывайте как строки:

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

applicationId выбирает проект и его конфигурацию. Он передаётся в браузерных запросах и сам по себе не авторизует запрос. Браузерный доступ работает только для origins, зарегистрированных ShopStory.

Совместимость клиента​

• Игнорируйте незнакомые необязательные поля.
• Не считайте порядок полей частью контракта.
• Различайте отсутствующее поле, null, пустой массив и пустую строку.
• Устанавливайте собственный тайм-аут и обрабатывайте сетевой сбой отдельно от ответа API.
• Не подтверждайте изменение корзины по одному HTTP 200 или визуальному состоянию плеера: проверяйте результат в commerce-системе ритейлера.

Полные схемы и обязательные поля находятся в OpenAPI. Рабочий запрос: Quickstart.