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

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

Запрос

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

Параметр	Обязательно	Описание
`applicationId`	Да	Выданный ShopStory идентификатор приложения. Он выбирает область данных и не авторизует запрос.
`feedProductId`	Нет	Стабильный строковый идентификатор товара из согласованного фида. Ведущие нули значимы.
`categoryId`	Нет	Числовой идентификатор категории эфира.
`status`	Нет	`planned`, `online` или `finished`.
`limit`	Нет	Размер страницы. `0` отключает пагинацию; значения выше `100` сервер обрабатывает как `100`.
`offset`	Нет	Смещение от начала набора. Передавайте вместе с положительным `limit`.

Все переданные фильтры объединяются по логике 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 как механизм инкрементальной синхронизации.

Модель эфира

Поле	Тип	Описание
`id`	string	Идентификатор эфира.
`application`	string	Идентификатор приложения.
`name`, `description`	string	Название и описание эфира.
`streamer`	string	Идентификатор ведущего из `streamers`.
`status`	string	`planned`, `online` или `finished`.
`plannedDate`, `startDate`, `endDate`	string \| null	Временные метки ISO 8601. Отсутствующая дата передаётся как `null`.
`previewImages`	array	Изображения эфира.
`products`	string[]	Внутренние идентификаторы товаров из `products`.
`productFeedIds`	string[]	Идентификаторы этих товаров из фида. Поле может отсутствовать, если сопоставлений нет.
`categories`	integer[]	Идентификаторы категорий.

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

Поле	Тип	Описание
`id`	string	Внутренний идентификатор ShopStory.
`application`	string	Идентификатор приложения.
`name`	string	Название товара.
`feedProductAvailable`	boolean	Доступность из последней успешно обработанной версии товарного фида.
`feedProductId`	string	Идентификатор из фида; может отсутствовать для ранее загруженных данных.
`vendorCode`	string	Артикул продавца; может отсутствовать.
`feedProductGroupId`	string	Идентификатор группы или варианта; может отсутствовать.
`url`	string	URL карточки товара.
`previewImages`	array	Изображения товара.

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

Доступность из фида

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

Остаток выбранного магазина в Web SDK приходит от обработчика наличия на стороне сайта ритейлера. При интеграции через Public API эту проверку выполняет интерфейс клиента: Наличие товара и остатки.

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, поэтому транспортные ошибки обрабатывайте отдельно.

Запрос​

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

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

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

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

Ошибки​

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