Каталог эфиров — GET /v3/streams

Эндпоинт возвращает запланированные, текущие и завершённые эфиры вместе с товарами, ведущими и категориями, которые нужны для их отображения.

Запрос​

GET https://app.shopstory.live/v3/streams?applicationId=<application-id>&limit=20&offset=0
Accept: application/json

Все переданные фильтры объединяются по логике AND.

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

Успешный ответ:

{
  "status": 200,
  "serverTime": "2025-01-15T10:00:00.000Z",
  "body": {
    "plannedStreams": [],
    "availableStreams": [],
    "products": [],
    "streamers": [],
    "categories": [],
    "total": 0
  }
}

plannedStreams содержит эфиры со статусом planned по возрастанию plannedDate. availableStreams сначала содержит эфиры online, затем записи finished; внутри каждой группы элементы отсортированы по startDate от новых к старым.

Пагинация и total​

• Без status пагинация применяется только к availableStreams; plannedStreams возвращается полностью.
• При status=planned пагинация применяется к plannedStreams, а availableStreams пуст.
• При status=online или status=finished пагинация применяется к соответствующей части availableStreams, а plannedStreams пуст.
• total — размер выбранного набора до применения limit и offset.
• total присутствует, если передан хотя бы один фильтр либо параметр пагинации. В запросе без фильтров, limit и offset поле может отсутствовать.

Offset pagination не создаёт snapshot. Новый эфир или смена статуса между запросами может сдвинуть элементы на следующих страницах. Для длительно открытого каталога периодически загружайте первую страницу заново и объединяйте элементы по строковому id; не используйте offset как механизм инкрементальной синхронизации.

Модель эфира​

Модель товара​

Идентификаторы товаров являются строками. Не преобразуйте их в числовой тип: это может удалить ведущие нули или снизить точность.

streamers содержит id, application и профиль ведущего. categories содержит id, application и name. Полная машинно-читаемая схема опубликована в OpenAPI.

Ошибки​

Для /v3/streams валидационные и внутренние ошибки передаются в общем конверте при транспортном HTTP 200. Проверяйте оба уровня: сначала возможность прочитать HTTP-ответ, затем верхнеуровневое поле status.

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

Не привязывайте обработку к точному тексту message. Для ветвления используйте status и body.error. Сетевой шлюз может вернуть собственный HTTP 4xx или 5xx, поэтому транспортные ошибки обрабатывайте отдельно.

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

GET /v3/streams

availableStreams — live и записи.
plannedStreams — анонсы.

Данные карточки

ЗаписьОбзор косметикиОткрыть плеер

Карточка вашего сайта

Название — stream.name, состояние — stream.status.

Клик «Открыть плеер»
stream.id → streamId

Полный плеер ShopStory

showPlayer() получает streamId и clientId — тот же applicationId проекта.

Товар связывается отдельно от эфира

stream.products[] → совпадающий body.products[].id → product.feedProductId в каталоге магазина.

Для перехода на PDP используйте product.url. Товарные ID сохраняйте строками, включая ведущие нули.

Анонсы можно показать в каталоге. В starter кнопка плеера доступна для online и finished на реальных данных; в fixture видео нет.

В API starter есть catalog.html — запускаемый пример Public API + основного Web SDK. После распаковки выполните из папки starter:

python3 -m http.server 8080 --bind 127.0.0.1

Откройте http://127.0.0.1:8080/catalog.html и нажмите «Открыть fixture». Появятся карточка Тестовая запись, статус finished и товар 0001001. Видео в fixture нет; кнопка player отключена и SDK не загружается.

Пример связывает данные так:

Для реального прогона разместите starter на зарегистрированном test origin, введите выданный applicationId и нажмите «Запросить API». Выберите online или finished и нажмите «Открыть плеер». SDK получает clientId этого же проекта и streamId карточки; playback URL не собирается из отдельных полей.

Убедитесь, что появился первый кадр и видео продолжает воспроизводиться. Promise showPlayer() подтверждает только внутреннюю инициализацию. Этот метод не принимает cart handlers из show(); контракт и ограничения описаны отдельно.

До сетевого прогона подтвердите consent-сценарий. Для production примените CSP проекта к коду примера. При пустом ответе или ошибке страница показывает соответствующее состояние, не подменяя его fixture.

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

• Требования к товарному фиду
• Mini-player
• OpenAPI и Postman