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 мс, ретраї з експоненціальною паузою і 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), захист даних і ліміти відповідальної гри - і перетворює «красиву трансляцію» в надійний, сертифікований фінансовий продукт.