Cum funcționează API-ul pentru conectarea jocurilor live la platformă

1) Arhitectură comună și roluri componente

Platforma Operator (Platforma Casino): conturi, portofel, motor bonus, limite, KYC/AML, jurnalul de tranzacții.

Furnizor de jocuri live (Studio/Provider): studiouri, dealeri, fluxuri video (WebRTC Low-Latency HLS), runde de servere de jocuri.

Agregator (uneori): un singur API pentru zeci de furnizori, unificarea valutelor/limitelor/evenimentelor.

Client frontend: client web/mobil cu UI de pariuri, video player, chat, solicitări locale.

Servicii auxiliare: Risc/Antifraudă, exploatare forestieră, analiză, cozi de mesaje (Kafka/RabbitMQ), monitorizare.

Topologie tipică: → client (JWT) → → platformă (server-to-server) furnizor de →, în paralel, clientul primește un flux video de la CDN/media server pool.

2) Ciclul de viață al jucătorului și sesiuni

2. 1. Autentificare și „joc token”

1. Jucătorul se conectează la platformă.

2. Platforma apelează CreateGameSession de la furnizor (S2S), transmite 'player _ id',' valute ',' country ',' bet _ limits', steaguri ale jocului responsabil.

3. Furnizorul returnează o singură dată game_token și launch_url.

4. Clientul deschide 'launch _ url' in an iframe/new tab, adăugând' game _ token '(sau devine 302 la URL-ul final al jocului).

Exemplu de cerere de S2S:

http
POST/api/v1/sesiuni
Tip de conținut: aplicație/json
Autorizatie: Purtator <platform_api_key>

{
„player_id":” u-918273 „,” session_id": „sess-5f3b2”, „valută”: „EUR”, „țară”: „DE”, „lang”: „de”, „bet_limits"”: {„min”: 0. 5, „max”: 2000}, „responsible_gaming": {” self _ exclused „: fals', deposit_limit_left": 150}”, callback_urls": {
"balance": "https ://platform. exemplu. com/wallet/balance”, „debit”: „https ://platform. exemplu. com/wallet/debit”, „credit”: „https ://platform. exemplu. com/wallet/credit”, „rollback „: „https ://platform. exemplu. com/wallet/rollback”, „evenimente”: „https ://platform. exemplu. com/game/evenimente"
}
}

Răspunsul furnizorului:

json
{
"game_token": "gtkn_7f0...e2a," "launch_url": "https ://live. furnizor. com/launch/ruletă,” „expires_in": 900
}

2. 2. Autentificare în față

Jocul se încarcă, validează 'game _ token' prin backend-ul său.

WebSocket este instalat pe serverul de joc pentru pariuri/evenimente.

Fluxul video rulează peste WebRTC (latență redusă 0. 5-2 s) sau LL-HLS (2-5 s).

3) Bani și pariuri: API portofel și idempotence

3. 1. Soldul și debitul/creditul

Furnizorul nu stochează „banii” jucătorului - apelează API-ul Platformei Wallet:

"GET/portofel/echilibru? player_id' → curent disponibil.
„POST/PORTOFEL/DEBIT” → scrie pariul.
„POST/PORTOFEL/CREDIT” → câștiguri din credit/returnări.
„POST/portofel/rollback” → rularea înapoi a unei tranzacții atunci când o rundă este anulată.

Important: toate tranzacțiile monetare sunt 'transaction _ id'/' round _ id'. Repetarea aceleiași interogări nu schimbă rezultatul.

Exemplu de debit (rată):

http
POST/portofel/debit
Cheie Idempotency: trx-7a2df-001
Tip de conținut: aplicație/json

{
"player_id": "u-918273", "round_id": "r-2025-10-18-12:30:15Z-001," "transaction_id": "trx-7a2df-001", "suma": 25. 00, "valută": "EUR", "bet_type" ":" roulette_straight, "" meta ": {" table _ id':" ru-11", "selecție":" 17", "cote": 35}
}

3. 2. Sincronizări și stări de miză

. După 'WINDOW _ CLOSED', furnizorul interzice noi debite.

Ofertele târzii sunt respinse cu codul 'LATE _ BET'.

Dacă conexiunea este ruptă, clientul poate retrimite pariul - serverul trebuie să poată distinge duplicatul prin Idempotency-Key.

Statusurile tranzacţiei: 'ÎN AŞTEPTARE', 'DECONTAT', 'RULAT _ ÎNAPOI', 'RESPINS'.

4) Evenimente rotunde: Model și Ordine

4. 1. Schema de evenimente WebSocket

'round. a început '→ comes' round _ id', bet timer.

"bet. acceptată/respinsă "→ confirmare pentru fiecare ofertă.

'round. închis "→ pariurile nu mai sunt acceptate.

'round. rezultat "→ rezultat (ruletă/card/sectorul osos).

"payout. a creat suma → câștigată de jucător.

'round. a stabilit statutul → final, suma de control.

Exemplu de eveniment rezultat:

json
{
"tip": "rotund. rezultat", "round_id": "r-2025-10-18-12:30:15Z-001," "table_id": "ru-11", "sarcină utilă": {
"ruletă": {"număr": 17 ", culoare": "negru"}, "hash": "sha256: 8a7b... d1c'," video_ts": "2025-10-18T12:30:23. 450Z"
}
}

4. 2. Coerența și sumele de control

Fiecare eveniment este furnizat cu „seq” și „semnătură” (mTLS + semnătura organismului de solicitare).

Pentru reconciliere, se specifică 'payout _ checksum' - suma tuturor creditelor 'round _ id' trebuie să conveargă.

5) flux video și latență

WebRTC pentru pariuri de mână live (blackjack/baccarat/ruletă) - buget strict de întârziere <2 s pentru client.

LL-HLS/DASH pentru telespectatori/scară, permite 2-5 c.

Sincronizarea timpului: NTP/cronică, în sarcină utilă - 'video _ ts' pentru reluări și dispute.

Folback: când WebRTC se degradează, comutarea automată la → LL-HLS cu blocarea pariurilor târzii.

6) Erori, Retras, Timeouts

Reguli generale:

Toate apelurile S2S cu o perioadă de timp de 800-1500 ms, retraiele cu pauză exponențială și Jitter, dar fără a re-debita bani (idempotență).

Coduri de eroare portofel:

'INSUFICIENT _ FONDURI', 'LIMIT _ EXCEED', 'ACCOUNT _ LOCKED', 'DUPLICATE _ TRANSACTION', 'LATE _ BET', 'VALUTĂ _ NEPOTRIVIRE'.

Formatul de eroare:

json
{
"eroare": "INSUFFICIENT_FUNDS," "mesaj": "Echilibru 18. 00 <necesar 25. 00”, „transaction_id": „trx-7a2df-001”
}

7) Bonusuri, freespins, asigurare

În paralel cu portofelul „bani”, poate exista un sold bonus: sarcina utilă indică sursa sursei de deconectare: CASH	BONUS ".
Pentru jocurile live, asigurarea/pariul lateral nu este mai puțin frecventă (de exemplu, în blackjack) - acestea sunt tranzacții separate cu propriile limite și coeficienți.
Reguli de rotunjire: bancar (semi-la-chiar) sau în favoarea jucătorului/operatorului - trebuie să fie fixate în configurația de integrare.

8) Joc responsabil și limitări

Steaguri de sesiune: 'self _ exclused', 'cooldown _ to', 'loss _ limit _ left',' time _ limit _ left'.

Furnizorul poate solicita 'validate _ limits' înainte de fiecare debit.

Platforma poate iniția force_close_session: jucătorul este exclus/depășit limita → furnizorul închide fereastra de pariere și face returnări la pariuri nejustificate.

9) Siguranță și conformitate

mTLS pentru S2S, HSTS, strict IP-allowlist.

JWT/JWS cu scurt TTL pentru jetoane front-end, audiență/verificarea emitentului.

Semnarea webhookurilor furnizorului (HMAC-SHA256 peste corp).

Jurnalele activității dealerului, reluări rotunde, audit imuabil (stocare WORM).

Stocarea datelor cu caracter personal - minimizarea PII, tokenizarea 'player _ id', perioadele de păstrare a jurisdicției (GDPR și analogi).

Geo-blocarea și interdicțiile în funcție de jurisdicție la nivelul CreateGameSession.

10) Reconciliere și finanțe

10. 1. Rapoarte orare/zilnice

Furnizorul oferă un raport cu privire la 'round _ id → total_bets, total_wins, taxe'. Platforma combină:

Debitări = Σ pariuri, Credite = Σ câștiguri + returnări, Delta = GGR (inclusiv bonusuri/jackpoturi/comisioane).

Formatul raportului:

json
{
„date”: „2025-10-18”, „valută”: „EUR”, „tabele”: [{
"table_id": "ru-11", "runde": 1260 ", total_bets": "45230. 00", "total_payouts" ": 43012. 50", "jackpot_contrib": "302. 00", "provider_fee": "2. 5%"
}]
}

10. 2. Rollback-scenarii

Video/Storyboard → runda a eșuat. anulat: furnizorul trimite un 'rollback' tuturor pariurilor din rundă.

Procesare de debit dublu prins pe platforma → 'DUPLICATE _ TRANSACTION' și 200 OK cu același rezultat.

11) Chat, moderare și evenimente UI

Evenimentele de chat trec printr-un canal separat (WebSocket # 2) cu filtre de dop.

Anunțuri de sistem (pariuri închise, lista câștigătorilor) - numai de la o sursă de încredere furnizor, semnat/timestamped.

12) Testarea și certificarea

Furnizor Sandbox: rezultate fixe, capacitatea de a forța 'round. rezultat ".

Contur QA: tabel de testare cu ferestre de pariere trunchiate (5-8 c) și flux accelerat.

Încărcați: simularea a 5-10 mii de jucători simultani, debitele maxime pe secundă (TPS) ≥ programate × 1. 5.

Certificarea integrării: liste de verificare pentru idempotență, valute, rotunjire, întreruperi de procesare, respectarea limitelor și auto-excludere.

13) Măsurători și SLO

Acestea: latenta mediana/95p pentru 'debit/credit', WebSocket dus-intors, eroare de sincronizare a timpului, drop-rate WebRTC.

Продукт: rata de acceptare a pariului, rata de pariere târzie, rata de dispută, rata de chargeback, durata sesiunii, retenție, ARPU/LTV.

Exemple SLO:

99. 5% „debit” ≤ 1. 2 s, 99. 9% livrare 'rundă. rezultat '≤ 300 ms după fixare, Video delay ≤ 2. 5 s pentru 95p WebRTC.

14) Multicurrency, taxe, localizare

Conversie - în afara furnizorului: jocul funcționează strict în moneda de sesiune.

Impozite/deduceri - pe partea platformei cu „credit” (câmp „reținere la sursă”).

Localizare: 'lang', format număr/monedă, fus orar pentru cronometre și rapoarte.

15) Opțiuni de integrare

1. Direct-to-Provider: control maxim și caracteristică, dar contracte/certificări separate.

2. Prin agregator: acoperire rapidă de către furnizori, scheme unificate, uneori mai puțină flexibilitate.

3. Hibrid: mese de top direct, restul printr-un agregator.

16) Mini-specificații (total)

16. 1. Intrare WebSocket (client la furnizor)

json
{"type ":" pariu. loc", "pariu": {
„sumă”: 25, „selecție”:” 17”, „table_id":"ru-11”
}, „idempotency_key":"c3a2-...-001”}

16. 2. WebSocket outbound (furnizor către client)

json
{"type ":" pariu. acceptat", "bet_id":"b-8821," "seq ": 12031}
{"tip ":" rotund. închis", "round_id":"r-...001," "seq ": 12050}
{"tip ":" rotund. rezultat", "rezultat ": {"număr ": 17", culoare":" negru"}, "seq ": 12070}
{"type ":" payout. creat", "sumă": 875 ", monedă":" EUR", "seq ": 12075}

16. 3. Portofel S2S (platformă ↔ furnizor)

„POST/PORTOFEL/DEBIT” (idempotent)

„POST/portofel/credit” (idempotent)
'POST/portofel/rollback' (idempotent)

Semnătura HMAC, „Timestamp”, „Nonce”, protecție repetată (TTL ≤ 60 c).

17) Cazuri de margine și cum să le închideți

Deconectarea jucătorului: pariu trimis, nici o confirmare → repeta cu aceeași 'Idempotency-Key'; serverul va răspunde cu același statut.

Schimbare dealer/punte în rundă: anulare automată și „rollback” complet.

Neconcordanță valutară: 'VALUTĂ _ MISMATCH' + jurnal de evenimente; jocul este blocat până când sesiunea este relansată.

Auto-excludere la momentul jocului: imediat 'force _ close _ session', retur nejustificat.

Schimbarea calității video: doar client, fără impact asupra cronometrelor/pariurilor.

WebSocket re-strângere de mână: fără pierderi de ordine - coadă de evenimente cu 'seq', „prinde din urmă” ratat.

18) Lista de verificare a lansării producției

Siguranță

mTLS + certificat de fixare, IP-allowlist.
Semnaţi toate cărţile web şi verificaţi 'Timestamp '/' Nonce'.
Mini-PII: numai 'player _ id' (tokenizat).

Fiabilitate

Identitatea tuturor tranzacțiilor monetare.
Reluări rotunde și audit de neschimbat.
WebRTC → LL-HLS auto-folback.

Produs

Limite/joc responsabil aplicat în timp real.
Solicitări native în momentul pariului.
Tablouri de bord SLO + alerte 24/7.

API-ul de integrare a jocurilor live este un pachet de flux de latență scăzută, autobuz de evenimente și portofel idempotent cu cerințe stricte pentru ordinea mesajelor, temporizări și securitate. Implementarea cu succes se bazează pe: un ciclu strict de viață al pariurilor și rundelor, consistență verificabilă (reconciliere), protecția datelor și limite de joc responsabile - și transformă „frumoasa difuzare” într-un produs financiar fiabil și certificat.