Quickstart — первые запросы

Этот гайд поможет вам сделать первые запросы к ShopStory Public API и получить данные о трансляциях за 5-10 минут.

Вы на правильной странице?

Этот гайд для кастомной интеграции через API. Если вам нужно простое решение без программирования, используйте Web SDK — интеграция за 15 минут копипастой.

См. Сравнение методов для выбора подходящего подхода.

Перед началом

Для работы с API вам понадобится:

applicationId — выдаётся вашим аккаунт-менеджером или в панели (если включено). Используйте уникальные значения для каждого окружения.
Сервер или локальный прокси — мы рекомендуем делать запросы к ShopStory с бэкенда или serverless функции, чтобы не раскрывать applicationId.
HTTPS доступ — убедитесь, что исходящий трафик на app.shopstory.live не блокируется.
jq (опционально) — для красивого форматирования JSON в терминале.

Первый запрос

Самый простой способ проверить API — использовать интерактивный playground ниже. Он не требует установки дополнительных инструментов.

Аутентификация

Production-интеграции используют applicationId в query параметрах. Bearer токены доступны в закрытой бете — подробности и план перехода смотрите в гайде по аутентификации.

🎮 Интерактивный Playground

Попробуйте API прямо в браузере. Введите ваш applicationId и нажмите «Попробовать». Если вы участвуете в бете токенов, переключитесь на соответствующий режим.

GET

/v3/streams

Метод аутентификации

Application ID *

Limit

Offset

📋 Примеры запросов

Smoke-тест каталога

Проверим, что API доступен и возвращает данные о стримах:

Базовый запрос к каталогу
export SHOPSTORY_APPLICATION_ID="your-production-app-id"

curl -s "https://app.shopstory.live/v3/streams?applicationId=${SHOPSTORY_APPLICATION_ID}&limit=10" \
  | jq '{ status, planned: (.body.plannedStreams|length), available: (.body.availableStreams|length) }'

Ожидаемый результат:

{
  "status": 200,
  "planned": 3,
  "available": 12
}

Если вы получили status: 200 — поздравляем, API работает! 🎉

Безопасность

applicationId — приватный идентификатор. Храните его в переменных окружения и не публикуйте в фронтенд-коде. Для браузерных приложений обращайтесь к вашему бэкенду или serverless-прокси.

Пагинация

Используйте limit и offset для постраничной загрузки:

Получить первые 12 стримов
curl -s "https://app.shopstory.live/v3/streams?applicationId=${SHOPSTORY_APPLICATION_ID}&limit=12&offset=0" \
  | jq '{ total: .body.total, ids: (.body.availableStreams|map(.id)) }'

Параметры пагинации:

Параметр	Описание	Значение по умолчанию	Максимум
`limit`	Количество записей на странице	20	100
`offset`	Пропустить N записей	0	нет ограничений

Важно

Параметр offset работает только вместе с limit. Без limit будет возвращена ошибка валидации.

Фильтрация

API поддерживает фильтрацию по товарам и категориям:

Стримы с конкретным товаром
curl -s "https://app.shopstory.live/v3/streams?applicationId=${SHOPSTORY_APPLICATION_ID}&feedProductId=183966" \
  | jq '{ total: .body.total, streams: (.body.availableStreams|map(.name)) }'

Стримы по категории
curl -s "https://app.shopstory.live/v3/streams?applicationId=${SHOPSTORY_APPLICATION_ID}&categoryId=264" \
  | jq '.body.total'

Комбинация фильтров
curl -s "https://app.shopstory.live/v3/streams?applicationId=${SHOPSTORY_APPLICATION_ID}&feedProductId=183966&categoryId=264"

Логика фильтрации:

Все фильтры объединяются по AND логике
Неверные значения вернут status: 422 с кодом ошибки InvalidFilter
Можно комбинировать несколько фильтров одновременно

🌐 Пример на JavaScript

Простой HTML файл для загрузки и отображения стримов:

index.html
<!DOCTYPE html>
<html lang="ru">
<head>
  <meta charset="UTF-8">
  <title>ShopStory Streams</title>
  <style>
    body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 900px; margin: 0 auto; }
    .stream { padding: 1rem; margin: 0.5rem 0; border: 1px solid #ddd; border-radius: 8px; }
    .stream-name { font-weight: 600; font-size: 1.125rem; }
    .stream-status { color: #00d4aa; font-size: 0.875rem; }
  </style>
</head>
<body>
  <h1>Список стримов ShopStory</h1>
  <div id="streams"></div>

  <script>
    (async () => {
      try {
        // ⚠️ В production обращайтесь к своему backend-прокси.
        const response = await fetch('/api/shopstory/v3/streams?limit=10');
        const { status, body } = await response.json();

        if (status !== 200) {
          throw new Error(`API вернул status: ${status}`);
        }

        const container = document.getElementById('streams');
        const streams = body.availableStreams || [];

        if (streams.length === 0) {
          container.innerHTML = '<p>Стримов не найдено</p>';
          return;
        }

        streams.forEach(stream => {
          const div = document.createElement('div');
          div.className = 'stream';
          div.innerHTML = `
            <div class="stream-name">${stream.name}</div>
            <div class="stream-status">Статус: ${stream.status}</div>
          `;
          container.appendChild(div);
        });
      } catch (error) {
        console.error('Ошибка загрузки стримов:', error);
        document.getElementById('streams').innerHTML = `<p style="color: red;">Ошибка: ${error.message}</p>`;
      }
    })();
  </script>
</body>
</html>

Что делает этот код:

Обращается к вашему прокси /api/shopstory/v3/streams
Проверяет статус ответа
Отображает список стримов на странице
Обрабатывает ошибки

Безопасность в браузере

Не передавайте applicationId или токены в открытом фронтенд-коде. Используйте backend proxy, serverless-функции или edge middleware, чтобы скрыть секреты и добавлять дополнительные проверки (IP, referer, throttling).

🐍 Пример на Python

fetch_streams.py
import os
import requests

# Читаем applicationId из переменных окружения
SHOPSTORY_APPLICATION_ID = os.getenv("SHOPSTORY_APPLICATION_ID")
BASE_URL = "https://app.shopstory.live"

def get_streams(limit=10, offset=0):
    """Получить список доступных стримов"""
    if not SHOPSTORY_APPLICATION_ID:
        raise ValueError("SHOPSTORY_APPLICATION_ID environment variable not set")

    params = {
        "applicationId": SHOPSTORY_APPLICATION_ID,
        "limit": limit,
        "offset": offset
    }

    response = requests.get(f"{BASE_URL}/v3/streams", params=params, timeout=10)
    data = response.json()

    if data["status"] != 200:
        error = data.get('body', {}).get('error', {})
        raise Exception(f"API Error: {error.get('message', 'Unknown error')}")

    return data["body"]["availableStreams"]

if __name__ == "__main__":
    try:
        streams = get_streams(limit=5)

        for stream in streams:
            print(f"📺 {stream['name']} - {stream['status']}")
    except ValueError as e:
        print(f"❌ Ошибка конфигурации: {e}")
        print("Установите переменную окружения: export SHOPSTORY_APPLICATION_ID='your-app-id'")
    except Exception as e:
        print(f"❌ Ошибка API: {e}")

Запуск:

export SHOPSTORY_APPLICATION_ID="your-app-id"
python fetch_streams.py

✅ Проверка ответов

Все ответы API возвращаются в JSON-конверте:

{
  "status": 200,
  "serverTime": "2025-01-15T14:32:10.123Z",
  "body": {
    "total": 25,
    "availableStreams": [...],
    "plannedStreams": [...]
  }
}

Ключевые поля:

status — HTTP-статус (200, 422, 500 и т.д.)
serverTime — время сервера в ISO 8601
body — данные ответа или объект ошибки

Обработка ошибок

При ошибке валидации (status: 422) поле body.error содержит детали:

{
  "status": 422,
  "body": {
    "error": {
      "code": "InvalidFilter",
      "message": "Неверный feedProductId"
    }
  }
}

🚀 Следующие шаги

Теперь, когда вы сделали первые запросы, изучите:

Каталог стримов — детальное описание моделей данных и всех параметров
Архитектура API — формат ответов, версионность и правила именования
Мини-плеер — как встраивать виджеты с трансляциями
Инструменты — Postman коллекция, SDK и утилиты для тестирования

🔄 Готовимся к Bearer токенам

Переход на Bearer токены запланирован и сейчас тестируется с пилотными клиентами. До официального запуска используйте applicationId, а в коде держите возможность переключиться на токены — это упростит миграцию.

План действий:

Расположите логику аутентификации в одном месте (например, вспомогательный клиент, как в примерах выше).
Если участвуете в бете, добавьте заголовок Authorization: Bearer ... параллельно с applicationId.
Следите за обновлениями в гайде по аутентификации — там появится точная дата запуска и инструкции по ротации токенов.

Operational toolkit (roadmap)

📦 Официальные SDK (npm, pip) — в планах после GA токенов
🔔 Вебхуки для статусов стримов — обсуждаются с пилотными клиентами
🎬 Видео-туториалы для быстрого старта — появятся вместе с обновлением onboarding-процесса
📄 SLA и метрики доступности — готовим публичный документ для enterprise-клиентов

💬 Нужна помощь?

Email: support@shopstory.live
Статус платформы: /status
FAQ: Частые вопросы

Перед началом​

🎮 Интерактивный Playground​

📋 Примеры запросов​

Smoke-тест каталога​

Пагинация​

Фильтрация​

🌐 Пример на JavaScript​

🐍 Пример на Python​

✅ Проверка ответов​

🚀 Следующие шаги​

🔄 Готовимся к Bearer токенам​

Operational toolkit (roadmap)​

💬 Нужна помощь?​