StreamShop Public API

Публичный API для внешних клиентов: каталог услуг, баланс и заказы «Живой чат». Аутентификация по заголовку x-api-key, все ответы — в едином конверте { success, data, ts, id }.

Base URL · https://shop-stream.ru/api — путь эндпоинта добавляется к базе (итоговый пример: https://shop-stream.ru/api/services). Версионирования нет.

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

Каждый запрос должен содержать заголовок:

x-api-key: <ключ>

• Ключ привязан к конкретному пользователю и даёт доступ ТОЛЬКО к его данным.
• Выпускается только администратором (admin/moder). Полный ключ показывается один раз при выпуске; список своих ключей пользователь видит в panel/settings.
• Cookie-сессии публичным API не принимаются.

Нет ключа / невалидный ключ → 401.

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

Успех:

{ "success": true, "data": { "...": "payload" }, "ts": "42ms", "id": "0f9c1b2e-..." }

Ошибка:

{ "success": false, "errors": { "...": "object|array" }, "ts": "42ms", "id": "0f9c1b2e-..." }

Поле	Тип	Описание
success	boolean	результат запроса
data	object	полезная нагрузка (при успехе)
errors	object | array	детали ошибки (при success:false)
ts	string | null	время обработки, напр. "42ms"
id	string (uuid)	идентификатор запроса для трассировки

Все SDK распаковывают конверт автоматически: методы возвращают сразу data, а при ошибке бросают типизированный ShopStreamApiError(status, errors, requestId).

Ошибки и лимиты

Код	Когда
400	ошибка валидации тела или недостаточно средств
401	нет ключа / невалидный ключ
404	чужой или несуществующий ресурс
422	бизнес-ограничение (напр. тип услуги вне теста)
429	превышен лимит запросов

Лимиты: ~60 запросов/мин на ключ + глобальный backstop 120/мин по IP. Превышение → 429 (рекомендуется экспоненциальный backoff).

Перечисления

• Platform: Twitch · Kick · Youtube · Wtv · Vkplay · Telegram
• ServiceType: Follow · Chat · Viewer · Comment — в POST /orders доступен только Chat
• OrderStatus: Searching · Accepted · InProgress · Paused · Cancelled · Completed

Список услуг

GET

/services

Возвращает все видимые услуги с тарификацией. Доступно по любому валидному ключу. Поле cost содержит параметры тарифа (например, price за час чата).

Authorizations

apiKey

Type

API Key (header: x-api-key)

Баланс

GET

/balance

Возвращает текущий баланс пользователя, которому принадлежит API-ключ.

Authorizations

apiKey

Type

API Key (header: x-api-key)

Создать заказ «Живой чат»

POST

/orders

Оформляет заказ на живой чат для стрима. В тестовом режиме поддерживается только тип Chat. Сумма рассчитывается сервером по тарифу услуги и списывается с баланса владельца ключа; указывать сумму не нужно. Время старта startAt трактуется как UTC.

Authorizations

apiKey

Type

API Key (header: x-api-key)

Request Body

application/json

{

  

"platform": "Twitch",

  

"channelUrl": "https://twitch.tv/somechannel",

  

"startAt": "2026-07-01T18:00:00Z",

  

"durationMinutes": 60,

  

"language": "Русский",

  

"comment": "Поддержка стрима",

  

"promoCode": "PROMO10"

}

Получить заказ по id

GET

/orders/{id}

Возвращает заказ, оформленный владельцем ключа. Чужой или несуществующий заказ → 404.

Authorizations

apiKey

Type

API Key (header: x-api-key)

Parameters

Path Parameters

id*

Type

string

Required

SDK

Готовые тонкие клиенты под 4 языка. Одинаковый набор методов, авто-распаковка конверта, типизированная ошибка ShopStreamApiError. Исходники — в директориях *-sdk/ репозитория.

JavaScript / TS

import { ShopStreamClient } from '@shopstream/sdk';

const client = new ShopStreamClient({
  apiKey: process.env.SHOPSTREAM_API_KEY!,
  baseUrl: 'https://shop-stream.ru/api',
});

const { services } = await client.listServices();
const { balance } = await client.getBalance();

const order = await client.createChatOrder({
  platform: 'Twitch',
  channelUrl: 'https://twitch.tv/example',
  startAt: '2026-07-01T18:00:00.000Z',
  durationMinutes: 120,
});

const fetched = await client.getOrder(order.id);

Python

from shopstream import ShopStreamClient, CreateChatOrderInput, Platform

client = ShopStreamClient(
    api_key="sk_live_...",
    base_url="https://shop-stream.ru/api",
)

services = client.list_services()
balance = client.get_balance()

order = client.create_chat_order(
    CreateChatOrderInput(
        platform=Platform.TWITCH,
        channel_url="https://twitch.tv/example",
        start_at="2026-07-01T18:00:00.000Z",
        duration_minutes=120,
    )
)

fetched = client.get_order(order.id)

PHP

use ShopStream\Client;
use ShopStream\CreateChatOrderInput;
use ShopStream\Enums\Platform;

$client = new Client('sk_live_...', 'https://shop-stream.ru/api');

$services = $client->listServices();
$balance = $client->getBalance();

$order = $client->createChatOrder(new CreateChatOrderInput(
    platform: Platform::Twitch,
    channelUrl: 'https://twitch.tv/example',
    startAt: '2026-07-01T18:00:00.000Z',
    durationMinutes: 120,
));

$fetched = $client->getOrder($order->id);

Go

import (
    "context"
    shopstream "github.com/shopstream/go-sdk"
)

client, _ := shopstream.NewClient("sk_live_...", "https://shop-stream.ru/api")
ctx := context.Background()

services, _ := client.ListServices(ctx)
balance, _ := client.GetBalance(ctx)

order, _ := client.CreateChatOrder(ctx, shopstream.CreateChatOrderInput{
    Platform:        shopstream.PlatformTwitch,
    ChannelURL:      "https://twitch.tv/example",
    StartAt:         "2026-07-01T18:00:00.000Z",
    DurationMinutes: 120,
})

fetched, _ := client.GetOrder(ctx, order.ID)

Метод	Запрос
listServices()	GET /services
getBalance()	GET /balance
createChatOrder(...)	POST /orders
getOrder(id)	GET /orders/{id}

Полные README — в javascript-sdk/, python-sdk/, php-sdk/, go-sdk/.