Лайв ойындарын платформаға қосудың 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. Клиент 'game _ token' қосу арқылы iframe/жаңа қойындысында 'launch _ url' ашады (немесе соңғы URL ойынына 302 алады).

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 с кідіртудің қатаң бюджеті.

Көрермендер/масштаб үшін LL-HLS/DASH, 2-5 с рұқсат етеді.

Уақытты үндестіру: 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) Қауіпсіздік және комплаенс

S2S, HSTS, қатаң IP-allowlist үшін mTLS.

JWT/JWS алдыңғы белгілер үшін қысқаша TTL, audience/issuer тексеру.

Провайдердің қолы (дененің үстінен 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 с) және жеделдетілген флоу бар тест-кесте.

Жүктеме: бір мезгілде 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', ойналмағандарды қайтару.

Бейне сапасының өзгеруі: тек клиенттік, таймерге/мөлшерлемеге әсер етпейді.

Re-хэндшейк WebSocket: тәртіпті жоғалтпай - оқиғалар кезегі 'seq', өткізіп жіберілгендермен.

18) Продакшн-ұшырудың чек-парағы

Қауіпсіздік

mTLS + pin сертификаты, IP-allowlist.
Барлық webhook 'тар қолтаңбасы және' Timestamp '/' Nonce 'дегенді тексеру.
Шағын PII: тек 'player _ id' (токенизацияланған).

Сенімділік

Барлық ақша операцияларының ұқсастығы.
Раундтардың репликалары және өзгермейтін аудит.
Авто-фолбэк WebRTC → LL-HLS.

Өнім

Лимиттер/жауапты ойын нақты уақытта қолданылады.
Ставка сәтіндегі ұлттық кеңестер.
SLO дашбордтары + алерта 24/7.

Лайв ойындарының API интеграциясы - бұл хабарламалар тәртібіне, таймингтерге және қауіпсіздікке қатаң талаптары бар төмен ағымды, оқиғалық шинаны және демпотенттік әмиянды біріктіру. Табысты іске асыру: ставкалар мен раундтардың қатаң өмірлік цикліне, тексерілетін тұрақтылыққа (reconciliation), деректерді қорғауға және жауапты ойынның лимиттеріне сүйенеді - және «әдемі трансляцияны» сенімді, сертификатталатын қаржылық өнімге айналдырады.