Come connettere i provider tramite API: handshake, certificazione, sandbox

Testo completo dell'articolo

💡 18+. Il materiale è ingegneristico, non un appello al gioco. Per «provider» si intende RGS/studio live/jackpot/servizio; sotto «piattaforma» - PAM/portafoglio/cassa/bonus/RG.

1) Scheda di integrazione dalla richiesta alla produzione

Fasi:

1. Presale e Due Diligence: giuristi, geo/licenze, compatibilità di contenuti e regole RG.

2. Handshake e sicurezza: accesso sandbox, scambio di chiavi (mTLS/HMAC), registrazione alla Schema Registry.

3. Tecnizine: confermiamo il modello di dominio (sessions/bets/settlements/events), l'idempotenza, i codici di errore.

4. Integrazione Sandbox: emulatori portafogli/PSP/RG, giocatori di prova, scenari di pioggia e riprese.

5. Certificazione: test obbligatori, firma di protocolli, carichi di lavoro e valigette in disordine.

6. Staging/UAT - conferme di combattimento senza soldi reali, traffico di canarie.

7. Go-Live: compagnia di chiavi, accensione flag, monitoraggio SLO, post-incidente.

2) Handshake: autenticazione, autorizzazione, traccia

2. 1 Scambio di segreti e scopi

mTLS (certificati per brand/region) e/o OAuth2 Client Credentials.

Firma il corpo della query di HMAC/EdDSA (aggiunge non-replica).

Скоупы: `sessions:write`, `bets:write`, `settlements:write`, `events:publish`.

2. 2 Intestazioni obbligatorie

X-Trace-Id - Traccia completa.

`X-Brand-Id`, `X-Region`, `X-Provider-Id`.

X-Idempotency-Key - per tutte le operazioni write.

2. 3 Health Check (prima del codice)


GET /health
→ 200 {"status":"ok","version":"1. 7. 2","time":"2025-10-23T10:00:00Z"}

3) Sandbox: cosa c'è e come usarlo

Composizione ambiente:

Emulatore portafoglio ('/wallet/debit	credit	rollback ') con idropotenza e ritardi.
Gancio RG ('/rg/check ',' rg. limit. hit ') e profili di prova (auto-esclusione/limiti).
Aggregatore/jackpot per contributi/trigger.
Risposte FAKE KYC/AML (allow/deny/pending).
Pneumatico di eventi (Kafka/Pulsar) con top test e Schema Registry.

Armonia con la realtà:

Versioni simili di diagrammi e rate limits che sono in vendita.
Timeout, doppie di consegna, out-of-order - incorporato da pulsanti di emulazione.

Set di giocatori/valute di prova:


p_demo_1 (EUR), p_demo_2 (USD), p_blocked_rg (denied), p_low_balance

4) Modello di risorse e contratto minimo

4. 1 Creazione sessione


POST /v1/sessions
{
"player_id":"p_demo_1",  "game_id":"studio:slot_forge_02",  "currency":"EUR",  "locale":"de-DE"
}
→ 201 {"session_id":"s_456","expires_at":"2025-10-23T19:10:00Z"}

4. 2 Autorizzazione puntata (hold)


POST /v1/bets/authorize
Headers: X-Idempotency-Key: bet_r_8c12_1
{
"session_id":"s_456",  "bet_id":"b_001",  "round_id":"r_8c12",  "amount":{"amount":2. 00,"currency":"EUR"}
}
→ 200 {"status":"authorized","hold_id":"h_zz1"}

4. 3 Settlent (esito del round)


POST /v1/bets/settle
Headers: X-Idempotency-Key: settle_r_8c12_1
{
"bet_id":"b_001",  "round_id":"r_8c12",  "win":{"amount":14. 60,"currency":"EUR"},  "bonus_state":{"in_bonus":true,"freespins_left":7}
}
→ 200 {"status":"credited","settlement_id":"st_77"}

4. 4 Errori (diagramma unico)


409
{"code":"DUPLICATE","message":"Bet already authorized","retryable":false,"trace_id":"tr_a1b2"}

5) Eventi e schemi: senza questo non ottieni la certificazione

Topic base:

`session. started	ended`, `bet. authorized	settled	rolled_back`, `bonus. issued	consumed`, `wager. progress. updated`, `wallet. debit.`, `wallet. credit.`, `rg. limit. hit`, `rg. reality_check`.

Esempio di Avro/JSON Schema (frammento "bet. settled`):

json
{
"event_type":"bet. settled",  "schema_version":"1. 2. 0",  "event_id":"uuid",  "occurred_at":"2025-10-23T16:21:05Z",  "tenant_id":"brand-7",  "region":"EU",  "player_id":"p_demo_1",  "trace_id":"tr_a1b2",  "payload":{
"round_id":"r_8c12",   "bet":{"amount":1. 00,"currency":"EUR"},   "win":{"amount":14. 60,"currency":"EUR"},   "in_bonus":true
},  "idempotency_key":"bet_r_8c12_1"
}

Regole: evoluzione backward-compatibile, test per «duplicati ed eventi tardivi», partizionamento per «tenant _ id/player _ id».

6) Certificazione integrazione: esattamente cosa viene verificato

6. 1 Script funzionali (minimo)

Ripetere la query «authorize/settle» con la stessa «X-Idempotency-Key» è la stessa risposta.

Out-of-order: «settle» è arrivato senza «authorize».

Catene Rollback in caso di caduta del portafoglio/rete.

Piedi RG - L'autolesionismo/il limite di perdita/tempo impedisce la puntata.

Bonus/wager - contributo per tipo di gioco, max bet, deadline.

6. 2 Carico di lavoro

p95 «bet/settle» nei bilanci (ad esempio «<200-300 ms»), nessuna tempesta «retrae».

I flussi di eventi arrivano a BI da 5 minuti.

6. 3 valigette di caos

Doppie delle consegne, ritardi outbox/CDC, distacco della regione, settlement parziale.

6. 4 Documenti di risultato

Protocollo dei test con timecode/trace-id.

Rapporto SLO.

Riepilogo di sicurezza (chiavi, rotazioni, disponibilità, Vault/HSM).

7) Versione e migrazioni

HTTP: '/v1/... 'nel percorso, eventi:' schema _ version'nel corpo.

SemVer: minor - Aggiungere campi opzionali maggiore - solo attraverso il nuovo prefisso '/v2/'.

Deprecation headers: «Deprecation», «Sunset», specchio di utilizzo nel dashbord.

Flag Fiech: «doppia lettera» di eventi («v1» e «v2») durante il periodo di transizione.

8) Sicurezza e conformità

mTLS + firma S2S, token a breve vita, scorciatoie limitate.

Zero-trust: regole di rete, chiavi per-brand/region.

Data residency & PII Storage e loghi nella regione; RLS/occultamento.

Controllo WORM - Modifiche ai limiti, ai profili RTP, alle configurazioni jackpot.

RG/AML: segnali di stop sincronizzati su tasso/pagamento; Rapporto SAR/TR.

9) Esci in provetta: elenco di controllo di avvio

Prima di attivare il traffico

Rotazione dei segreti sandbox delle chiavi prod.

Inclusi i dashboard p95/p99, error-rate, queue-lag, settle-lag.

Alert SLO: breach latency/error/lag, sfoggiò DUPLICATA/IDEMPOTENCY _ MISMATCH '.

Piano DR: RPO 5 min, RTO 30 min; «pulsante rosso» - stop nuove sessioni.

Canarino

1-5% di pubblico/gioco/geo; rollback automatico in caso di violazione dello SLO.

Monitoraggio post-post 24-72 ore, controllo dei risultati/rapporti.

10) Anti-pattern (bandiere rosse)

Pubblicare eventi oltre outbox/CDC.

Nessun «X-Idempotency-Key» nelle operazioni write.

Modifica manuale dei bilanci/settlement nel database.

Una sola chiave per più marchi/regioni.

BI e i rapporti regolatori sopra il database di combattimento OLTP.

Zero degrado, la caduta del provider distrugge il portafoglio/piattaforma.

11) Assegno fogli

Per il provider

Invio «X-Trace-Id» e «X-Idempotency-Key» sempre.
Supporto la ripetizione con la stessa chiave senza effetti collaterali.
Pubblico eventi per schemi da Registry; memorizzò schema _ variante ".
Implementazione di retrai con backoff e deduplicazione.
I piedi RG e i vincoli di bonus vengono rispettati nel real-time.
Accessibili e segreti - per brand/region, rotazione configurata.

Per la piattaforma

Outbox/CDC su tutti i percorsi di cassa; traccia end-to-end.
SLO-dashboard: p95/99, error-rate, queue-lag, settle-lag.
Deprecation/Sunset-workflow, doppia lettera di eventi sulle migrazioni.
DR./xaoc-esercitazioni, gestione degli incidenti e post-mortem.
Modalità di degrado: «no new sessions», disattivazione promo/jackpot.

12) Esempio di playbook di integrazione «minimo» (TL; DR)

1. Firmare NDA/contratto per rilasciare sandbox e schemi.

2. Scambiare certificati di mTLS/HMAC; attivare «provider _ id».

3. Allineare gli endpoint minimi a «sessions», «bets/authorize», «bets/settle», «rollback».

4. Connettersi a Sandbox Bus e Registry; Controllare le valigette funzionali/caotiche.

5. Inoltrare il protocollo di certificazione: logi, trace-id, rapporto SLO.

6. Sposta le chiavi a una prua, accende il canarino, osserva la SLO.

7. Fissa le metriche post-release e le «lezioni» in changelog.

La connessione di successo del provider non è solo un'API, ma un processo gestito: handshake sicuro, sandbox realistico, certificazione rigorosa, osservabilità e regole di compatibilità ben definite. Seguendo le invarianti descritte (Idempotence, Outbox/CDC, RG/AML-piedi, SLO e DR), si accelera l'integrazione, si evitano incidenti monetari e si ottengono rilasci prevedibili - senza sorprese per attori, regolatori e imprese.