Torrent Gear

Как работает API подключения лайв-игр к платформе

1) Общая архитектура и роли компонентов

Платформа оператора (Casino Platform): аккаунты, кошелёк, бонусный движок, лимиты, KYC/AML, журнал транзакций.

Провайдер live-игр (Studio/Provider): студии, дилеры, видеопотоки (WebRTC/Low-Latency HLS), игровой сервер раундов.

Агрегатор (иногда): единый API к десяткам провайдеров, унификация валют/лимитов/событий.

Фронтенд клиента: веб/мобильный клиент с UI ставок, видеоплеер, чат, локальные подсказки.

Вспомогательные сервисы: Risk/Anti-fraud, логирование, аналитика, очереди сообщений (Kafka/RabbitMQ), мониторинг.

Типовая топология: клиент → (JWT) → платформа → (server-to-server) → провайдер, параллельно клиент получает видеопоток от CDN/пула медиасерверов.

2) Жизненный цикл игрока и сессии

2.1. Логин и «игровой токен»

1. Игрок авторизуется на платформе.

2. Платформа вызывает CreateGameSession у провайдера (S2S), передаёт `player_id`, `currency`, `country`, `bet_limits`, флаги ответственной игры.

3. Провайдер возвращает одноразовый game_token и launch_url.

4. Клиент открывает `launch_url` в iframe/новой вкладке, добавляя `game_token` (или получает 302 на конечный URL игры).

Пример S2S-запроса:

http
POST /api/v1/sessions
Content-Type: application/json
Authorization: Bearer <platform_api_key>

{
"player_id": "u-918273",  "session_id": "sess-5f3b2",  "currency": "EUR",  "country": "DE",  "lang": "de",  "bet_limits": {"min": 0.5, "max": 2000},  "responsible_gaming": {"self_excluded": false, "deposit_limit_left": 150},  "callback_urls": {
"balance": "https://platform.example.com/wallet/balance",   "debit":  "https://platform.example.com/wallet/debit",   "credit": "https://platform.example.com/wallet/credit",   "rollback":"https://platform.example.com/wallet/rollback",   "events": "https://platform.example.com/game/events"
}
}

Ответ провайдера:

json
{
"game_token": "gtkn_7f0...e2a",  "launch_url": "https://live.provider.com/launch/roulette",  "expires_in": 900
}

2.2. Аутентификация на фронте

Игра загружается, валидирует `game_token` через свой бекенд.

Устанавливается WebSocket к игровому серверу для ставок/событий.

Видеопоток идёт по WebRTC (низкая задержка 0.5–2 с) или LL-HLS (2–5 с).

3) Деньги и ставки: Wallet API и идемпотентность

3.1. Баланс и дебет/кредит

Провайдер не хранит «деньги» игрока — он вызывает Platform Wallet API:

`GET /wallet/balance?player_id` → текущее доступное.
`POST /wallet/debit` → списать ставку.
`POST /wallet/credit` → зачислить выигрыш/возврат.
`POST /wallet/rollback` → откат транзакции при отмене раунда.

Важное: все денежные операции идемпотентны по `transaction_id`/`round_id`. Повтор одного и того же запроса не меняет результат.

Пример дебета (ставка):

http
POST /wallet/debit
Idempotency-Key: trx-7a2df-001
Content-Type: application/json

{
"player_id": "u-918273",  "round_id": "r-2025-10-18-12:30:15Z-001",  "transaction_id": "trx-7a2df-001",  "amount": 25.00,  "currency": "EUR",  "bet_type": "roulette_straight",  "meta": {"table_id":"ru-11", "selection":"17", "odds":35}
}

3.2. Тайминги и статусы ставки

WINDOW_OPEN → WINDOW_CLOSING → WINDOW_CLOSED. После `WINDOW_CLOSED` провайдер запрещает новые дебеты.

Поздние ставки отклоняются с кодом `LATE_BET`.

При разрыве связи клиент может отправить ставку повторно — сервер должен уметь отличать дубликат по Idempotency-Key.

Статусы транзакций: `PENDING`, `SETTLED`, `ROLLED_BACK`, `REJECTED`.

4) События раунда: модель и очередность

4.1. Схема событий по WebSocket

`round.started` → приходит `round_id`, таймер ставок.

`bet.accepted/rejected` → подтверждение по каждой ставке.

`round.closed` → ставки больше не принимаются.

`round.result` → исход (сектор рулетки/карты/кости).

`payout.created` → сумма выигрыша по игроку.

`round.settled` → финальный статус, контрольная сумма.

Пример события результата:

json
{
"type": "round.result",  "round_id": "r-2025-10-18-12:30:15Z-001",  "table_id": "ru-11",  "payload": {
"roulette": {"number":17, "color":"black"},   "hash": "sha256:8a7b...d1c",   "video_ts": "2025-10-18T12:30:23.450Z"
}
}

4.2. Согласованность и контрольные суммы

Каждое событие снабжается `seq` и `signature` (mTLS + подпись тела запроса).

Для reconciliation указывается `payout_checksum` — сумма всех кредитов по `round_id` должна сходиться.

5) Видеопоток и задержка

WebRTC для ставок «на живую руку» (блэкджек/баккара/рулетка) — строгий бюджет задержки <2 c до клиента.

LL-HLS/DASH для зрителей/масштаба, допускает 2–5 c.

Синхронизация времени: NTP/chrony, в payload — `video_ts` для реплеев и споров.

Фолбэк: при деградации WebRTC → авто-переключение на LL-HLS с блокировкой поздних ставок.

6) Ошибки, ретраи, таймауты

Общие правила:

Все S2S-вызовы с таймаутом 800–1500 мс, ретраи c экспоненциальной паузой и Jitter, но без повторного списания денег (идемпотентность).

Коды ошибок кошелька:

`INSUFFICIENT_FUNDS`, `LIMIT_EXCEEDED`, `ACCOUNT_LOCKED`, `DUPLICATE_TRANSACTION`, `LATE_BET`, `CURRENCY_MISMATCH`.

Формат ошибки:

json
{
"error": "INSUFFICIENT_FUNDS",  "message": "Balance 18.00 < required 25.00",  "transaction_id": "trx-7a2df-001"
}

7) Бонусы, фриспины, страховки

Параллельно с «денежным» кошельком может быть бонусный баланс: в payload указывается источник списания `source: CASH	BONUS`.
Для лайв-игр нередки страховки/сайд-бет (например, в блэкджеке) — это отдельные транзакции с собственными лимитами и коэффициентами.
Правила округления: банковское (half-to-even) или в пользу игрока/оператора — должно быть зафиксировано в конфиге интеграции.

8) Ответственная игра и ограничения

Флаги сессии: `self_excluded`, `cooldown_until`, `loss_limit_left`, `time_limit_left`.

Провайдер перед каждым дебетом может запрашивать `validate_limits`.

Платформа может инициировать force_close_session: игрок исключён/превысил лимит → провайдер закрывает окно ставок и делает возвраты по неразыгранным ставкам.

9) Безопасность и комплаенс

mTLS для S2S, HSTS, строгая IP-allowlist.

JWT/JWS с кратким TTL для фронтовых токенов, audience/issuer проверка.

Подпись webhook’ов провайдера (HMAC-SHA256 над телом).

Логи действий дилеров, реплеи раундов, неизменяемый аудит (WORM-хранилище).

Хранение персональных данных — минимизация PII, токенизация `player_id`, сроки хранения по юрисдикции (GDPR и аналоги).

Гео-блокировки и запреты по юрисдикциям на уровне CreateGameSession.

10) Reconciliation и финансы

10.1. Почасовые/суточные отчёты

Провайдер отдаёт отчёт по `round_id → total_bets, total_wins, fees`. Платформа сводит:

Сумма дебетов = Σ ставок, Сумма кредитов = Σ выигрышей + возвраты, Дельта = GGR (с учётом бонусов/джекпотов/комиссий).

Формат отчёта:

json
{
"date": "2025-10-18",  "currency": "EUR",  "tables": [{
"table_id": "ru-11",   "rounds": 1260,   "total_bets": "45230.00",   "total_payouts": "43012.50",   "jackpot_contrib": "302.00",   "provider_fee": "2.5%"
}]
}

10.2. Rollback-сценарии

Сбой видео/раскадровки → round.cancelled: провайдер шлёт `rollback` всем ставкам в раунде.

Двойная обработка дебета, пойманная на платформе → `DUPLICATE_TRANSACTION` и 200 OK с прежним результатом.

11) Чат, модерация и события UI

События чата идут через отдельный канал (WebSocket №2) с фильтрами по стоп-словам.

Системные объявления (close bets, winner list) — только из доверенного источника провайдера, подписаны/таймстампированы.

12) Тестирование и сертификация

Sandbox провайдера: фиксированные результаты, возможность форсировать `round.result`.

Контур QA: тест-таблица с урезанными окнами ставок (5–8 c) и ускоренным флоу.

Нагрузка: имитация 5–10 тыс. одновременных игроков, пиковые дебеты в секунду (TPS) ≥ планового ×1.5.

Сертификация интеграции: чек-листы по идемпотентности, валютам, округлению, обработке отключений, соответствию лимитам и self-exclusion.

13) Метрики и SLO

Тех: median/95p latency для `debit/credit`, WebSocket round-trip, ошибка синхронизации времени, drop-rate WebRTC.

Продукт: bet acceptance rate, late-bet rate, dispute rate, chargeback rate, session duration, retention, ARPU/LTV.

SLO примеры:

99.5% `debit` ≤ 1.2 с, 99.9% доставка `round.result` ≤ 300 мс после фиксации, Видеозадержка ≤ 2.5 с для 95p WebRTC.

14) Мультивалюта, налоги, локализация

Конвертация — вне провайдера: игра работает строго в валюте сессии.

Налоги/удержания — на стороне платформы при `credit` (поле `withholding`).

Локализация: `lang`, формат чисел/валюты, часовой пояс для таймеров и отчётов.

15) Варианты интеграции

1. Direct-to-Provider: максимум контроля и фич, но отдельные контракты/сертификации.

2. Через агрегатор: быстрое покрытие провайдерами, унифицированные схемы, иногда меньше гибкости.

3. Гибрид: топ-столы напрямую, остальное через агрегатор.

16) Мини-спецификация (суммарно)

16.1. WebSocket входящие (от клиента к провайдеру)

json
{ "type":"bet.place", "bet":{
"amount": 25, "selection":"17", "table_id":"ru-11"
}, "idempotency_key":"c3a2-...-001" }

16.2. WebSocket исходящие (от провайдера к клиенту)

json
{ "type":"bet.accepted", "bet_id":"b-8821", "seq":12031 }
{ "type":"round.closed", "round_id":"r-...001", "seq":12050 }
{ "type":"round.result", "result":{"number":17,"color":"black"}, "seq":12070 }
{ "type":"payout.created", "amount":875, "currency":"EUR", "seq":12075 }

16.3. Wallet S2S (платформа ↔ провайдер)

`POST /wallet/debit` (идемпотентно)

`POST /wallet/credit` (идемпотентно)
`POST /wallet/rollback` (идемпотентно)

Подпись HMAC, `Timestamp`, `Nonce`, защита от повторов (TTL ≤ 60 c).

17) Краевые кейсы и как их закрыть

Разрыв соединения у игрока: ставка отправлена, подтверждения нет → повтор с тем же `Idempotency-Key`; сервер ответит прежним статусом.

Смена дилера/колоды в раунде: автоматическая отмена и полный `rollback`.

Несовпадение валюты: `CURRENCY_MISMATCH` + журнал события; игра блокируется до перевыпуска сессии.

Self-exclusion в момент игры: немедленный `force_close_session`, возврат неразыгранных.

Смена качества видео: только клиентская, без влияния на таймеры/ставки.

Ре-хэндшейк WebSocket: без потери порядка — очередь событий с `seq`, «догонка» пропущенных.

18) Чек-лист продакшн-запуска

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

mTLS + pinning сертификата, IP-allowlist.
Подпись всех webhook’ов и проверка `Timestamp`/`Nonce`.
Мини-PII: только `player_id` (токенизированный).

Надёжность

Идемпотентность всех денежных операций.
Реплеи раундов и неизменяемый аудит.
Авто-фолбэк WebRTC → LL-HLS.

Продукт

Лимиты/ответственная игра применяются в реальном времени.
Нативные подсказки в момент ставки.
Дашборды SLO + алерты 24/7.

API интеграции лайв-игр — это связка низкозадержочного стрима, событийной шины и идемпотентного кошелька с жёсткими требованиями к порядку сообщений, таймингам и безопасности. Успешная реализация опирается на: строгий жизненный цикл ставок и раундов, проверяемую консистентность (reconciliation), защиту данных и лимиты ответственной игры — и превращает «красивую трансляцию» в надёжный, сертифицируемый финансовый продукт.