Come funziona l'integrazione API tra studi e piattaforme

L'integrazione dello studio (provider di giochi) con la piattaforma/aggregatore è una catena di chiamate sincroni e asincroni intorno alla sessione, al portafoglio, al risultato della schiena e alla telemetria di eventi. Di seguito è una mappa breve, ma pratica, come tutto si unisce senza dolore per gli sviluppatori e la compilazione.

1) Architettura sul palmo

Attori:

Studio RGS (Remote Game Server) è la logica del gioco, RNG, bonus, jackpot.
Piattaforma/Aggregatore - routing, billing, promo, compilation.
Operatore portafoglio giocatore, KYC/RG, vetrina.
Il client è il contenitore web/mobile del gioco (iframe/webview/native).

Pneumatici principali:

API Sync: sessioni, portafogli, outcome.
Async/Event Bus: eventi spin, bonus, jackpot, RG, errori tecnici.
Metadati/directory: giochi, market builds, profili RTP, locali.

2) Protocolli e soluzioni di base

Trasporti: HTTPS/JSON (a volte gRPC per Event Bus/portafoglio).

Versioning: 'Accept: application/vnd. rgs. v1 + json'o '/v1/... '; degrado della compatibilità solo attraverso le nuove versioni.

Identificazione: 'game _ id', 'build _ hash', 'operator _ id', 'sessions _ id', 'round _ id', 'spin _ id'.

Tempo: rigorosamente UTC, ISO-8601 con millisecondi.

Valute: ISO-4217 + precisione (minor units). FX è dalla parte dell'operatore/aggregatore.

3) Autenticazione e autorizzazione

Server-to-server: OAuth2 Client Credentials или HMAC-подпись (`X-Signature: HMAC_SHA256(payload, shared_key)`).

Sessione del giocatore: short-lived JWT (firma piattaforma) c «sub», «geo», «rg _ flags», «exp», «aud = studio».

Elenchi di accesso: IP allowlist + mTLS per i tracciati prod.

4) Modelli portafoglio: debit/credit vs transfer

A) Debit/Credit (on-the-fly):

1. La piattaforma chiama RGS: 'SpinRequest (stake)' → RGS calcola l'esito del → restituisce «win».

2. Parallelamente, la piattaforma fa «debit (stake)» e «credit (win)» presso il proprio operatore.

I vantaggi sono una semplice contabilità. Meno: più chiamate di rete, requisiti di idampotenza severi.

B) Transfer (session balance):

1. All'inizio della sessione, la piattaforma fa «transferIn (amount)» su RGS.

2. Durante gli spin, RGS effettua il bilanciamento della sessione; al termine, 'transferOut (remaining)'.

Meno chat del portafoglio. Contro: conteggio dei soldi RGS, dei rischi aggiuntivi e delle riscossioni.

Raccomandazioni:

Per i slot, è più comune utilizzare debit/credit con chiavi idompotenti.

Per free spins e tornei è conveniente avere singoli tipi di punte'spin _ type = free	promo`.

5) Idampotenza e coerenza

Ogni passaggio di denaro deve avere un unico «idempotency _ key» (ad esempio, «round _ id» o «spin _ id»).

Le ripetizioni ('HTTP 409/425') restituiscono lo stesso risultato, anziché «errore già completato».

Exactly-once è difficile da ottenere, quindi costruiamo at-least-once + idampotenza.

L'idampotenza viene estesa a: «debit», «credit», «jackpot _ content», «bonus _ award».

6) Schemi di query chiave (abbreviati)

6. 1. Avvio sessione

json
POST /rgs/v1/sessions
{
"session_id": "s-…",  "operator_id": "op-…",  "player_id": "p-…",  "game_id": "g-BookOf…",  "build_hash": "sha256:…",  "jwt": "eyJhbGci…",  "geo": "DE",  "currency": "EUR",  "rg_flags": {"self_excluded": false, "time_limit_min": 60}
}

6. 2. Spin (debit/credit)

json
POST /rgs/v1/spins
{
"spin_id": "spin-…",  "round_id": "rnd-…",  "session_id": "s-…",  "stake": {"amount": 1. 00, "currency": "EUR"},  "spin_type": "cash",  "idempotency_key": "spin-…"
}

Risposta:

json
{
"spin_id": "spin-…",  "outcome": {
"win": {"amount": 3. 40, "currency": "EUR"},   "features": [{"type":"bonus_trigger","name":"FreeSpins","count":10}],   "symbols": "opaque-or-omitted"
},  "rgs_txns": [
{"type":"jackpot_contribution","amount":0. 01}
],  "telemetry_ref": "evt-…"
}

6. 3. Loga evento (Event Bus, formato batch)

json
POST /rgs/v1/events/batch
{
"events":[
{
"type":"spin_finished",    "ts":"2025-10-20T11:22:33. 123Z",    "spin_id":"spin-…",    "round_id":"rnd-…",    "stake":1. 00,"win":3. 40,"currency":"EUR",    "game_id":"g-…","build_hash":"sha256:…",    "player_id":"p-…","operator_id":"op-…",    "spin_type":"cash"
}
]
}

7) Versioning dei bilanci e market builds

«build _ hash» (SHA-256) è obbligatorio per ogni evento.

Global vs Market build: lingua, avvertenze, vincoli di puntata, profilo RTP.

La piattaforma dice: «Se il bilico corrisponde al certificato del paese».

Matrice: 'game _ id x country x rtp _ profile x build _ hash'.

8) RNG, matematica e repliche

RNG vive su RGS; la logica aziendale non cambia le possibilità di volare.

Per forensica: «seed/nonce» per round/spin + versione meccanica.

Replica: 'spin _ id '/' seed'RGS riproduce l'esito e dà la traccia di verifica.

9) Respontible Gaming (RG) e gancio di compilazione

Ganci di tempo/limite: 'sessions _ time _ ms', 'promemoria', 'timeouts;' rg _ event'in Event Bus.

Auto-esclusione/blocco: con il flag, immediata è «403 RG _ BLOCKED».

Invarianti UI: la piattaforma controlla che il client mostri avvisi/etichette di età dal market build.

10) Errori, retrai e SLA

Codici: '400' (convalida), '401/403' (autenticazione/RG), '409' (conflitto di idempotenza), '422' (errore di business), '429' (rate limit), '5xx' (temporaneo).

La politica dei retrai è esponenziale, con chiave idompotente e deduplicazione sul ricevitore.

La disponibilità dell'API è ≥99. 9%, p95 latency per «spin» -300 mc (regionale), Event Bus - near-real-time <60 s

11) Osservazione e verifica

Fogli: fogli server non tagliati con corellazione trace _ id.

Metriche: p95/p99 latency, error rate per metodi, deviazioni RTP/frequenze bonus, quota «elegibile spins».

Secondo la SLA, per anomalie matematiche, per aumento dei mancamenti di portafoglio.

Controllo: storage WORM per gli eventi scommesse/risultati; esportazione su richiesta.

12) Sicurezza

mTLS + TLS 1. 2 +, HSTS, CORS rigorosi sul loader client.

Rotazione K, token TTL brevi, controlli JTI/nonce.

Anti-tamper il client: firma degli assetti, verifica dell'integrità, protezione contro i debagger.

I segreti sono solo il segreto manager; Niente «chiave nella configurazione del gioco».

13) Ambienti di prova e certificazione

Sandbox: portafogli fittizi, RNG determinati (fixed seed), il fallimento automatico degli script RG.

Staging - una copia di prod-infra senza soldi reali.

Pacchetto per laboratori: GDD/matematica, file RNG, schemi di logi, repeatable build e hash.

14) Promo e jackpot in API

Free Spins: «grant _ free _ spins (count, bet _ size, rtp _ profile?)»; gli eventi vengono sprecati in RGS e logificati.

Tornei: attributo'spin _ type = tourement' + aggregazioni separate in Event Bus.

Jackpot: 'jackpot _ contribution'e'jackpot _ win'come singole transazioni; consistenza attraverso idempotenza ed eventi «firmati».

15) Rendicontazione e billing

Блоки выгрузок: `spins_total`, `eligible_spins`, `turnover`, `ggr`, `netwin`, `jackpot_contrib`, `bonus_cost`, `royalty_due`.

Per-spin/turnover-fee: conto a «eligibile _ spins» o « stake x rate».

Da «NetWin» dopo la «cascata» delle trattenute; true-up trimestrale per FX/eccezioni.

16) Sequenze tipiche (grafici verbali)

Spin (debit/credit):

Client → Platform: StartRound → Platform → RGS: Spin → RGS → Platform: Outcome → Platform → Wallet: Debit → Platform → Wallet: Credit → Platform → Client: Result → Platform → EventBus: spin_finished.

Free Spins:

Platform → RGS: GrantFreeSpins → Client: Start → RGS: Consume/Log each → EventBus: spin_finished (spin_type=free).

17) Change-management e compatibilità

Contratto-prima (contract-first): OpenAPI/Protobuf è un'unica fonte di schemi.

SemVer - Aggiungi solo i campi; rimozione/modifica - in/v2.

Feature flags - Abilita opzioni (Bonus Buy/Ante) - Solo attraverso profili certificati.

Deprecation: announce n'grace period si spegne nelle regioni inattive.

18) Assegno fogli

Studio → Piattaforma

OpenAPI/gRPC spack e payload approssimativi.
Idempotensione'spin/debit/credit/jackpot '.
'build _ hash', e il registro market builds.
repliche RNG e controllo-loga.
Guasti RG e errori dì 403 RG _ BLOCKED '.
Sandbox con fix-seed, portafoglio di prova e autoveicoli.

Piattaforma → Studio

Firma JWT con TTL corto, allowlist IP, mTLS.
Valida market builds e certificati.
Event Bus e dashboard (latency/error/RTP draft).
Quote e rate-limits con feedback onesto «429-Retry-After».
SLA/incidenti/canali di comunicazione 24 x 7.

19) Piano di avvio

0-30 giorni

Concordare appalti API e schemi di eventi, scegliere un modello di portafoglio.

Sollevare sandbox: fissed-seed RNG, portafogli di prova, idampotenza automatica.

Registro «build _ hash» e matrice primaria market builds.

31-60 giorni

Integrazione tra portafoglio e spin; includere Event Bus e dashboard.

Test di carico (p95/p99), retrai/idampotenza, scenari di rete di caos.

Compilation: RG-hook, locali, age-labels; Un sacchetto per il laboratorio.

61-90 giorni

Pilota da 1-2 operatori, A/B per promo (free spins/tornei).

Immettere true-up/report, alert alla deriva RTP/bonus-freq.

Preparazione di v2 miglioramenti: eventi batch, gRPC per il portafoglio, geo-routing.

20) FAQ breve

Dove viene verificata la versione RTP? Nel platino «build _ hash», il certificato viene da un paese.

È possibile modificare la RTP in modo dinamico? No, no. Solo profili pre-certificati e solo market build.

Come si decide il doppio debit? Chiave Idempotent + Conservazione dello stato transazione ripetizione - restituisce l'esito.

C'è bisogno di un gRPC? Utile per portafogli/iventi ad alti volumi; Restando restando per i metadati/adminati.

L'integrazione stabile è contratto + idepotenza + osservabilità. Gli schemi di eventi trasparenti, il controllo dei bilanci/mercati, gli hook RG e la disciplina delle versioni eliminano il 90% dei rischi in partenza. In seguito, l'automazione di promozioni e rendicontazione, la rigida SLA e l'evoluzione attenta dell'API senza cambiamenti «distruttivi».