Архитектура и формат ответов

Хосты и версии

• Базовый домен публичного API: https://app.shopstory.live.
• Версии API представляют отдельные пространства:
  • /v2 — мини‑плеер (живой стрим, deep link по товару).
  • /v3 — каталог трансляций, быстрый статус, справочники.
• Префикса /api нет: путь начинается сразу с /v2 или /v3.

Конверт ответа

Все ответы оборачиваются в конверт вида:

{
  "status": 200,
  "serverTime": "2025-09-03T20:46:14.043Z",
  "body": {}
}

• status — фактический код бизнес-ответа. HTTP-статус практически всегда равен 200, что упрощает работу через браузер и CORS.
• serverTime — ISO-время, которое можно использовать для синхронизации кэшей.
• body — полезная нагрузка, где лежат данные либо объект error.

Ошибки

{
  "status": 422,
  "body": {
    "error": {
      "code": "InvalidFilter",
      "message": "feedProductId must be numeric"
    }
  }
}

Проверяйте body.error и status. HTTP-код отличен от 200 только при технических авариях.

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

• ID трансляций и сущностей передаются строками, даже если выглядят как числа — так сохраняются ведущие нули.
• vendorCode, feedProductId, feedProductGroupId могут отсутствовать, если приложение не передаёт их в фид.
• В справочниках все URL абсолютные и готовы к использованию на клиенте.

Кэширование

Некоторые ответы обслуживаются из приложенческого кэша. Это помечается заголовком:

X-Response-From-Application-Cache-Header: true

Если вам требуется свежий ответ, используйте query-параметры, меняющие ключ кэша (limit, offset, feedProductId и т.д.).

Требования к авторизации

В production-запросах указывается applicationId в query параметре. Это текущий стандарт:

GET /v3/streams?applicationId=your-app-id&limit=10

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

• держите applicationId в секрете и проксируйте запросы через бэкенд;
• добавьте поддержку заголовка Authorization: Bearer ... в клиентском коде заранее, но активируйте его только после публикации токенов.

Подробнее см. Руководство по аутентификации.

Следующий шаг — пройти Quickstart и сделать первый запрос.