Come funziona la connettività API dei giochi di lieve alla piattaforma

1) Architettura e ruoli comuni dei componenti

Piattaforma Operatore (Casino Platform): account, portafogli, motore bonus, limiti, KYC/AML, registro delle transazioni.

Provider di giochi live (Studio/Provider) - Studi, concessionari, flussi video (WebRTC/Low-Latency HLS), server di round.

Aggregatore (talvolta): un'unica API per decine di provider, unificazione valuta/limiti/eventi.

Frontand client: client web/mobile con puntata UI, lettore video, chat, suggerimenti locali.

Servizi di supporto: Risk/Anti-fraud, Loging, Analisi, Code di messaggi (Kafka/RabbitMQ), Monitoraggio.

Tipica topologia: Client (JWT) Piattaforma di (server-to-server) provider ; parallelamente, il client riceve un flusso video da CDN/pool di media.

2) Ciclo di vita del giocatore e sessioni

2. 1. Login e token di gioco

1. Il giocatore è autorizzato sulla piattaforma.

2. La piattaforma richiama il provider (S2S), trasmette «player _ id», «currency», «country», «bet _ limits», le bandiere del gioco responsabile.

3. Il provider restituisce game _ token e launch _ url.

4. Il client apre «launch _ url» in iframe/nuova scheda aggiungendo «game _ token» (o riceve 302 per l'URL finale del gioco).

Esempio di query 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"
}
}

Risposta del provider:

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

2. 2. Autenticazione sul fronte

Il gioco è caricato, valida «game _ token» attraverso il suo backend.

Installa il server di gioco per le scommesse/eventi.

Il flusso video segue il WebRTC (ritardo basso 0. 5-2 c) o LL-HLS (2-5 c).

3) Denaro e scommesse: API Wallet e Idempotia

3. 1. Saldo e debito/credito

Il provider non conserva il «denaro» del giocatore - chiama Platform Wallet API:

`GET /wallet/balance? player _ id '→ l'attuale.
«POST/wallet/debit» è il modo di cancellare la puntata.
«POST/wallet/credit» → iscrivere vincite/rimborsi.
'POST/wallet/rollback', annullamento della transazione.

Importante: tutte le transazioni in contanti sono idipotenti per «trasmissione _ id »/« round _ id». Ripetere la stessa query non cambia il risultato.

Esempio di debito (puntata):

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. Timing e stato della puntata

WINDOW_OPEN → WINDOW_CLOSING → WINDOW_CLOSED. Dopo WINDOW _ CLOSED, il provider vieta nuovi debiti.

Le puntate tardive vengono rifiutate con il codice «LATE _ BET».

In caso di interruzione, il client può rispedire la puntata - il server deve essere in grado di distinguere il duplicato da Idempotency-Key.

Stati transazioni: «PENDING», «SETTLED», «ROLLED _ BACK», «REJECTED».

4) Eventi del round: modello e priorità

4. 1. Schema eventi WebSocket

`round. started' → arriva 'round _ id', il timer delle scommesse.

`bet. accetted/rejected "conferma per ogni puntata.

`round. closed'non si accettano più le scommesse.

`round. result'esodo (settore roulette/mappe/ossa).

`payout. create' → l'importo della vincita del giocatore.

`round. settled'lo stato finale, la somma di controllo.

Esempio di evento risultato:

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. Coerenza e checksum

Ogni evento è dotato dì seq «e dì firma» (mTLS + firma corpo query).

Per la recordcilation è specificato'payout _ checksum '- l'importo di tutti i crediti per' round _ id 'deve corrispondere.

5) Flusso video e ritardo

WebRTC per le scommesse a mano viva (blackjack/baccara/roulette) è un budget rigoroso per il ritardo <2 c fino al cliente.

LL-HLS/DASH per il pubblico/scala, consente 2-5 c.

Sincronizzazione temporale: NTP/crony, in payload - 'video _ ts'per repliche e controversie.

Folback: in caso di deterioramento, il passaggio automatico a LL-HLS con il blocco delle scommesse tardive.

6) Errori, retrai, timeout

Regole generali:

Tutte le chiamate S2S con timeout 800-1500 ms, retrai con pausa esponenziale e Jitter, ma senza nuovo prelievo di denaro (idampotenza).

Codici errori portafoglio:

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

Formato errore:

json
{
"error": "INSUFFICIENT_FUNDS",  "message": "Balance 18. 00 < required 25. 00",  "transaction_id": "trx-7a2df-001"
}

7) Bonus, polpette, assicurazioni

Parallelamente al portafoglio "valuta" può essere un saldo bonus: payload indica l'origine di prelievo "source: CASH	BONUS`.
Per i giochi live, le assicurazioni/side bet (ad esempio in blackjack) non sono frequenti, sono transazioni separate con limiti e coefficienti personalizzati.
Regole di arrotondamento: bancario (half-to-even) o a favore del giocatore/operatore - deve essere registrato nella configurazione di integrazione.

8) Gioco responsabile e vincoli

I flag della sessione sono «self _ excluded», «cooldown _ untile», «loss _ limit _ left», «time _ limit _ left».

Il provider può richiedere «validate _ limits» prima di ogni debito.

La piattaforma può avviare forza _ close _ sessions: il giocatore è escluso/ha superato il limite, il provider chiude la finestra delle scommesse e effettua i rimborsi a scommesse non vincolate.

9) Sicurezza e compliance

mTLS per S2S, HSTS, allowlist IP rigoroso.

JWT/JWS con TTL breve per token frontali, audition/issuer convalida.

Firma webhook del provider (HMAC-SHA256 sopra il corpo).

Riepilogo delle attività dei rivenditori, repliche dei round, controllo invariato (WORM).

Conservazione dei dati personali - Riduzione del PI, tokenizzazione «player _ id», conservazione giurisdizionale (GDPR e analogie).

Blocchi geo e restrizioni giurisdizionali a livello CreateGameSession.

10) Ricomposizione e finanza

10. 1. Rapporti orari/giornalieri

Il provider riporta il rapporto dì round _ id total _ bets, total _ wins, fees ". La piattaforma riassume:

Importo dei debiti = Scommesse, Importo dei prestiti = Vincite + rimborsi, Delta = GGR (con bonus/jackpot/commissioni).

Formato report:

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. Script Rollback

Video/storyboard → round non riuscito. cancelled, il provider invia un'rollback "a tutte le scommesse del round.

Doppia elaborazione dei debiti catturati sulla piattaforma «DUPLICATE _ →» e 200 OK con il risultato precedente.

11) Chat, moderazione ed eventi UI

Gli eventi di chat attraversano un canale separato (numero 2) con filtri a parole.

Annunci di sistema (close bets, winner list) - Solo dall'origine attendibile del provider, firmato/timestampato.

12) Test e certificazione

Sandbox provider: risultati fissi, possibilità di forzare'round. result`.

Contorno QA: tabella di prova con finestre di puntata tagliate (5-8 c) e flow accelerato.

Carico di lavoro: simulazione di 5-10.000 giocatori simultanei, debiti di punta al secondo (TPS) ≥ di pianificazione x 1. 5.

Certificazione di integrazione: assegno di idempotenza, valute, arrotondamento, elaborazione dei blackout, conformità ai limiti e self-exclusion.

13) Metriche e SLO

Quelli: median/95p latency per «debit/credit», WebSocket round-trip, errore di sincronizzazione temporale, drop-rate WebRTC.

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

SLO esempi:

99. 5% `debit` ≤ 1. 2 c, 99. 9% di spedizione'round '. result' 300 ms dopo l' , 2. 5 c per 95p.

14) Multivaluta, tasse, localizzazione

Conversione - fuori dal provider: il gioco funziona rigorosamente nella valuta della sessione.

Tasse/detrazioni - sul lato della piattaforma con «credit» (campo «withholding»).

Localizzazione: «lang», formato numero/valuta, fuso orario per timer e rapporti.

15) Opzioni di integrazione

1. Direct-to-Provider: massimo controllo e fich, ma contratti/certificati separati.

2. Tramite aggregatore: copertura rapida dei provider, schemi unificati, a volte meno flessibilità.

3. I tavoli top, il resto tramite aggregatore.

16) Minigrafica (totale)

16. 1. WebSocket in arrivo (da client a provider)

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

16. 2. WebSocket in uscita (da provider a client)

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 (provider)

«POST/wallet/debit» (idipotente)

«POST/wallet/credit» (idipotente)
«POST/wallet/rollback» (idipotenziale)

Firma HMAC, Timestamp, Nonce, Protezione da ripetizione (TTL-60 c).

17) Valigette di bordo e come chiuderle

Interruzione della connessione del giocatore: puntata inviata, nessuna conferma con lo stesso «Idempotency-Key»; il server risponderà allo stato precedente.

Cambio dealer/mazzo nel round: annullamento automatico e completò rollback ".

La valuta non corrisponde: 'CURRENCY _ MISMATCH' + registro evento; la partita viene bloccata fino al riavvio della sessione.

Self-exclusion al momento del gioco: immediata «forza _ close _ sessions», restituzione dei non vantaggiosi.

Cambia qualità video: solo client, senza impatto su timer/scommesse.

Il Re Handshake dice che, senza perdere l'ordine, è la fila di eventi sù seq "," raggiungimento "mancati.

18) Assegno-foglio di produzione-avvio

Sicurezza

mTLS + pinning del certificato, IP-allowlist.
Firma tutti i webhook e convalida Timestamp/Nonce.
Mini-PII: solo «player _ id» (tornizzato).

Affidabilità

Idimpotenza di tutte le transazioni di denaro.
Repliche dei round e controllo invariato.
Folback automatico LL-HLS.

Prodotto

I limiti/gioco responsabile vengono applicati in tempo reale.
Suggerimenti nativi al momento della puntata.
Dashboard SLO + alert 24/7.

API integrazione dei giochi di live è un legamento di striam a basso raggio, pneumatico di evento e portafoglio idropotente con requisiti rigidi per l'ordine dei messaggi, timing e sicurezza. L'implementazione di successo si basa su: ciclo di vita rigoroso di scommesse e round, consistenza collaudata, protezione dei dati e limiti del gioco responsabile e trasforma la «bella trasmissione» in un prodotto finanziario affidabile e certificato.