Guida all'integrazione dei sistemi

1) Panoramica e modello di interazione

• Provider API: si chiama API GambleHub (portafoglio, bonus, rapporti).
• Fornitore esterno: chiamiamo i vostri siti Web/endpoint (saldo, transazioni, KYC).

1. Edge/API (REST/gRPC, Webhooks)

2. Eventi (event bus: scommesse/pagamenti/portafoglio/CUS)

3. Report (API + esportazione S3/SFTP)

4. Operazioni (incidenti, SLO, SLA-prestiti)

2) Ambienti, domini e IP

La SLA contrattuale è fissata nel contratto. Gli aggiornamenti IP vengono pubblicati in anticipo. Autorizzare Allowlist.

3) Autenticazione e autorizzazione

• OAUTh2 Client Credentials: server-a-server («scope»: «wallet: read», «wallet: write», «bet: write», «report: read»).
• JWT (issuer = GambleHub) - Firma RS256, chiavi in endpoint JWKS.
• mTLS: autenticazione TLS reciproca a livello ingress (su richiesta della compilazione).

POST /oauth2/token grant_type=client_credentials&scope=wallet:write bet:write
→ { "access_token": "...", "token_type": "Bearer", "expires_in": 3600 }

I Scopes vengono controllati in ogni chiamata. Per le operazioni ad alto rischio (pagamenti) si utilizza uno step-up: scope separato e, opzionalmente, un collegamento IP/ASN.

4) Versioning e compatibilità

Percorso: '/v1/... ', '/v2/...' (la versione maggiore non è compatibile indietro).
Modifiche minori ed estensive tramite l'estensione dello schema (nuovi campi opzionali).
Deprecazioni in 90 giorni con notifica.
I webhook sono versionati dal titolo «X-GH-Event-Variante: 1».

5) Limiti, quote e idepotenza

• `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
• 429 ritorna con'Retry-After '(secondi).
• Tutti i metodi non sicuri richiedono «Idempotency-Key» (TTL 24-72 ore). Ripetere una query identica restituisce il risultato originale ('409 IDAMP _ REPLAY'in caso di conflitto).

6) Standard di errore

json
{
"type": "https://docs. gamblehub. io/errors/validation_failed",
"title": "Validation failed",
"status": 422,
"error_code": "VAL_001",
"trace_id": "a1b2c3...",
"retriable": false,
"errors": [{"field":"amount","code":"min","message":"Must be >= 1"}]
}

Retriable: 5xx/503/504/429 (с `Retry-After`). Non-retriable: 400/401/403/404/409/422/410/415/412.

7) Schemi dati (kernel)

7. 1 Giocatore

json
{
"player_id": "p_123",
"country": "CA",
"currency": "CAD",
"rg_flags": {"self_excluded": false, "limits": {"daily_loss": 100}},
"kyc_status": "verified    pending    failed"
}

7. 2 Sessione

json
{
"session_id": "s_789",
"player_id": "p_123",
"started_at": "2025-11-03T17:55:00Z",
"ip": "203. 0. 113. 5",
"device": {"ua":"...", "os":"Android", "model":"..."}
}

7. 3 Portafoglio/transazioni

json
{
"txn_id": "t_001",
"player_id": "p_123",
"type": "deposit    withdrawal    bet    win    bonus    adjustment",
"amount": "12. 34",
"currency": "EUR",
"balance_after": "123. 45",
"metadata": {"provider":"psp_x","request_id":"r_456"}
}

7. 4 Tasso/pagamento

json
{
"bet_id": "b_456",
"player_id": "p_123",
"game_id": "g_777",
"stake": "1. 50",
"currency": "EUR",
"placed_at": "2025-11-03T17:58:10Z",
"round_id": "rnd_aa1",
"provider": "StudioX"
}

json
{
"settlement_id": "st_456",
"bet_id": "b_456",
"win_amount": "3. 75",
"settled_at": "2025-11-03T17:59:02Z",
"outcome": "win    lose    void"
}

7. 5 Bonus

json
{
"bonus_id": "bo_900",
"player_id": "p_123",
"type": "freespin    cash    wagered",
"state": "issued    active    expired    consumed",
"wagering": {"target": "100. 00","progress":"45. 20","currency":"EUR"}
}

8) REST API (frammenti di OpenAPI)

yaml paths:
/v1/wallet/balance/{player_id}:
get:
summary: Get wallet balance security: [{ oauth2: [wallet:read] }]
responses:
'200': { description: OK }
'401': { $ref: '#/components/responses/Problem' }
'404': { $ref: '#/components/responses/Problem' }

/v1/wallet/transactions:
post:
summary: Create wallet transaction security: [{ oauth2: [wallet:write] }]
parameters:
- name: Idempotency-Key in: header required: true schema: { type: string }
responses:
'201': { description: Created }
'409': { $ref: '#/components/responses/Problem' }
'422': { $ref: '#/components/responses/Problem' }

/v1/bets:
post:
summary: Register bet security: [{ oauth2: [bet:write] }]
responses:
'201': { description: Created }
'422': { $ref: '#/components/responses/Problem' }

9) Webhook (da GambleHub a partner)

• `X-GH-Event`: `player. created|session. started|bet. placed|bet. settled|wallet. changed|kyc. updated|rg. flagged`
• «X-GH-Event-ID» - UUID univoco
• `X-GH-Signature`: `sha256=`
• «X-GH-Retry» - Tentativo numero
• `X-GH-Event-Version`: `1`

json
{
"event": "bet. settled",
"occurred_at": "2025-11-03T18:00:12Z",
"data": {
"settlement_id": "st_456",
"bet_id": "b_456",
"player_id": "p_123",
"win_amount": "3. 75",
"currency": "EUR",
"outcome": "win"
}
}

Risposta dell'ospite: solo 2xx è considerato un successo. Altrimenti - retrai: backoff esponenziale (1s, 3s, 10s, 30s, 2m, 10m, 30m; massimo 24 ore). Utilizzare X-GH-Event-ID per deduplicare.

text expected = base64(hmac_sha256(request_body, SHARED_SECRET))
header  = split(X-GH-Signature, '=')[1]
assert header == expected

10) Ordine flusso di cassa (Wallet flow)

1. deposit (PSP → wallet. credit)

2. bet (hold/authorize или direct debit)

3. settlement (release hold; `win`/`lose`/`void`)

4. withdrawal (wallet. debit → PSP)

Sono supportati bilanci hold e multi-portafogli (reali/bonus).

11) Scudi di sabbia e test

Giocatori di prova: «p _ sbx _», valuta «EUR» USD «CAD».
I provider di giochi emulano: win/lose/void, disconnessi, ritardi.
KYC sandbox: risposte «verified» failed «review» sui modelli di passaporto.
PSP sandbox: статусы `authorized|captured|declined|reversed`.

Reimpostazione/void del round

Idempotency a tasso ripetuto

Errore del webhook con i retrai e la deduplicazione successiva

429 e corretto'Retry-After '

5xx con backoff esponenziale sul lato client

12) Accoppiamento e reporting

Reconciliation API

yaml
GET /v1/reports/reconciliation? from=...&to=...&scope=wallet    bets
→ CSV/JSON: { player_id, bet_id, stake, win, currency, balance_delta, provider }

Riepilogo giornaliero: giri, GGR/NGP, provider, taglio geo/valuta.
Esporta: S3/SFTP con manifesti firmati e hash di file (SHA256).
Timeson report: UTC (a meno che non sia specificato diversamente nel contratto).

13) Osservabilità e SLO

L'API ha successo 99. 95% (28d), p95 latency per metodi critici, successo nella consegna di webhoop.
Burn-alerts (fast/slow) per bilancio errato.
Correlazione trace: «trace _ id» nelle risposte/login, drilldown alle piste.
I componenti Edge, Wallet, Bets, Webhooks, PSP, KYC.

14) Sicurezza e compliance

Minimizzazione PII; Non sono consentiti PAN/segreti in login/webhop.
Secret management e rotazione delle chiavi.
RG - Le bandiere di auto-esclusione/limitazione devono causare l'annullamento automatico delle rate/pagamenti.
AML/KYC: eventi "kyc. updated`, `aml. alert "disponibili per iscrizione; prendete decisioni nel vostro sistema o tramite il nostro modulo.
GDPR/DSAR: endpoint per scaricare/rimuovere i dati personali del giocatore in base a richieste legali.
mTLS e HSTS sono attivati per impostazione predefinita in un ambiente protetto.

15) Prestazioni e quote

• RPS: 50 (burst 100)
• Concurrent webhooks: 10
• Dimensioni del corpo: 256 KB (eventi di gioco), 64 KB (portafoglio)

Richiedi l'upgrade del piano tramite l'account manager specificando le previsioni RPS/volumi.

16) Gestione delle modifiche e dei comunicati

Cambio windows: pianificazione programmata, notifica 5 giorni lavorativi.
Migrazioni in versione dual-write/dual-read durante il periodo di transizione.
Test contract in CI: schema JSON, campi obbligatori, stabili'error _ code '.
Canary: attivazione graduale del traffico per i nuovi fiocchi.

17) Certificazione integrazione (Check-list)

• Registrazione scommesse/pagamenti/void
• Idempotenza su tutti gli endpoint write
• Corretta gestione 429/5xx + backoff
• Verifica della firma Web, deduplicazione dì X-GH-Event-Id "
• Bilanciamento dopo una serie di eventi (win/lose)
• I report di riparazione convergono con i dati

• I retrai dei webhook sono stati implementati
• Timeout clienti 10s, tentativo totale 30 s
• Circuito-breaker per dipendenza

• Mantenere segreti nel gestore dei segreti
• Revisione PII nei loghi
• I flag RG/AML vengono conteggiati in tempo reale

18) Script utilizzati frequentemente

18. 1 Registrazione delle scommesse con idipotenza

POST /v1/bets
Idempotency-Key: bet-p_123-rnd_aa1-1

{ "player_id":"p_123","game_id":"g_777","stake":"1. 50","currency":"EUR","round_id":"rnd_aa1" }
→ 201 Created { "bet_id":"b_456" }

18. 2 Fail webhook seguito da successo

1. Il server 5xx non è disponibile per backoff.
2. Dopo il ripristino - accetti lo stesso «X-GH-Event-ID» per ignorare i duplicati.

18. 3 Degrado parziale del provider

Restituiremo 503; Ripetere con backoff.
In caso di degrado prolungato, l'etichettatura del provider e lo smart-routing (se nel contratto).

19) DevEx e supporto

Portale: chiavi, usage, webhook, loghi di consegna, dashboard SLO, esportazione di report.
Webhooks replay: ricarica per intervalli di date/ID.
Incidenti: Creazione auto di un ticket, war-room, postmortem di 48 ore su SEC-1.
Comunicazioni: # partners-status canale/posta on-call 24 x 7 (Enterprise).

20) Piano di onboarding (2-4 settimane)

1. Settimana 1: consegna delle chiavi, connessione sandbox, script base (puntata/pagamento/portafoglio).
2. Settimana 2: webhoop e compressioni, flag RG/KYC, test di carico, comportamento 429/5xx.
3. Settimana 3: rendicontazione (recepcibili, scarichi), sicurezza (firme, segreti), test di contratto.
4. Settimana 4: certificazione, inclusione canary in vendita, monitoraggio, matrice di contatto.

21) Mini FAQ

Possiamo gRPC?
Sì, su richiesta; Il mapping dei codici di errore HTTP è disponibile nella specifica.

Come ottenere i dati retro?
Tramite report di scaricamento S3/SFTP.

Come aumentare i limiti?
Tramite portale/account manager con RPS/concorrenza predittiva.

Qual è la fonte della verità del bilanciamento?
Registro del portafoglio transazionale GambleHub + Incrociatura giornaliera.

Totale

L'integrazione con l' GambleHub è basata su un contratto chiaro: API e schemi stabili, webhoop firmati, idompotenza e retrai, limiti e rapporti trasparenti e requisiti di sicurezza e compliance. In base a questo manuale e agli assegni di certificazione, si entrerà rapidamente in gioco, garantendo flussi di cassa affidabili e rapporti coerenti senza discrepanze.