Перейти к основному содержимому

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

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

Публичные эндпоинты только для чтения доступны на 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": {}
}
ПолеНазначение
statusРезультат операции внутри ShopStory API
serverTimeСерверное время в UTC, ISO 8601
bodyДанные, пустое состояние или описание ошибки

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

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

validation-error.json
{
  "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.

HTTP, конверт и содержимое ответаК следующей проверке переходите только после успеха предыдущей.
  1. 1. HTTP
    Ответ не получен или HTTP с ошибкой

    Обработайте сетевую или HTTP-ошибку.

    Успешный HTTP-код

    Ответ получен. Теперь проверьте JSON и результат операции.

    При успешном HTTP
  2. 2. JSON-конверт
    Невалидный ответ или ошибка API

    Например, HTTP 200 и payload.status: 400 — ошибка API.

    JSON валиден, status успешен

    Проверьте body по схеме конкретного endpoint.

    При успешном результате в конверте
  3. 3. Данные конкретного ресурса
    stream-state: body.status

    active — есть данные для открытия плеера.

    no_active_stream и stream: null — штатно скрыть точку входа в видео.

    Каталог: коллекции в body

    Пустые массивы допустимы. Отсутствующая обязательная коллекция — невалидный ответ.

Структура body зависит от endpoint. active подтверждает наличие данных для открытия, а первый кадр и продолжение воспроизведения проверяются отдельно.

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

unwrap-shopstory-response.js
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.

Последнее обновление