Идентификация приложения

Для выбора клиентского окружения передайте выданный ShopStory идентификатор в query-параметре. Имя параметра зависит от семейства API:

• /v3/streams использует applicationId;
• /v2/mini-player/* использует application.

Оба параметра указывают клиентское окружение и направляют запрос к его данным. Они не заменяют пароль, API-ключ или проверку прав. Для каждого запроса используйте имя параметра из OpenAPI-схемы конкретного эндпоинта.

curl --fail-with-body \
  "https://app.shopstory.live/v3/streams?applicationId=<assigned-application-id>&limit=10"

Точное значение выдаёт команда ShopStory при подключении. Не подбирайте идентификатор по названию компании и не переносите его между test и production.

Граница безопасности​

applicationId виден в браузерных запросах, мобильном трафике, журналах доступа и ссылках. На его секретности нельзя строить контроль доступа.

• Не используйте applicationId для защиты персональных данных, административных операций или изменения корзины.
• Не добавляйте в URL токены, cookies и другие секретные данные.
• Для операций в системе ритейлера используйте её штатную сессию, CSRF-защиту и серверную авторизацию.
• CORS ограничивает браузерные origins, но не заменяет аутентификацию.

В публичном контракте нет Bearer-токена. Не отправляйте произвольный Authorization и не вводите production credentials в сторонние API-консоли.

Где выполнять запрос​

Выбор зависит от сценария:

Через backend-прокси клиент может кэшировать и нормализовать ответ, а правила повторов задавать в одном месте. Такой прокси не превращает applicationId в учётные данные.

Обработка ответа​

Проверяйте транспортный HTTP-код и поле status JSON-конверта. Для части ошибок валидации /v3/streams текущий контракт возвращает HTTP 200 и бизнес-код 400 внутри ответа.

Пример ниже выполняется на backend. Пятисекундный deadline — политика этого клиента, а не SLA ShopStory.

export async function getStreams() {
  const applicationId = process.env.SHOPSTORY_APPLICATION_ID;
  if (!applicationId) {
    throw new Error('SHOPSTORY_APPLICATION_ID is not configured');
  }

  const url = new URL('https://app.shopstory.live/v3/streams');
  url.searchParams.set('applicationId', applicationId);
  url.searchParams.set('limit', '10');

  const response = await fetch(url, {
    headers: { Accept: 'application/json' },
    signal: AbortSignal.timeout(5000),
  });

  if (!response.ok) {
    throw new Error(`ShopStory transport error: ${response.status}`);
  }

  const payload = await response.json();
  if (payload.status !== 200) {
    throw new Error(payload.body?.message || 'ShopStory API error');
  }

  return payload.body;
}

Пример ошибки идентификации:

{
  "status": 400,
  "body": {
    "error": "invalid",
    "message": "invalid applicationId"
  },
  "serverTime": "2026-09-04T12:00:00Z"
}

Не повторяйте такой запрос автоматически: сначала исправьте конфигурацию.

Эксплуатационный минимум​

1. Храните разные значения для test и production в конфигурации приложения.
2. Не записывайте полный query string в аналитику и клиентские crash-отчёты без фильтрации.
3. Проверяйте status в конверте и ограничивайте тайм-аут.
4. Обрабатывайте временные ошибки по правилам Rate limiting.
5. Для кэша используйте рекомендации из раздела Кэширование.

Общая модель ответственности описана в разделе Безопасность.