Ghid de integrare GambleHub

1) Prezentare generală și modelul de interacțiune

• Furnizor API: apelați API-ul GambleHub (portofel, bonusuri, rapoarte).
• Furnizor extern: apelăm broșurile web/punctele finale (soldul, tranzacțiile, KYC).

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

2. Evenimente (event bus: pariuri/plăți/portofel/ICC)

3. Raportare (API + export S3/SFTP)

4. Operațiuni (incidente, SLO, credite SLA)

2) Medii, domenii și IP

SLA contractual este stabilit în contract. Actualizările IP sunt publicate în prealabil. Permiteți Allowlist.

3) Autentificare și autorizare

• OAuth2 Client Acreditări: server-to-server ('scope' s: 'wallet: read', 'wallet: write', 'bet: write', 'report: read').
• JWT (emitent = GambleHub): semnătură RS256, taste în punctul final JWKS.
• mTLS: autentificare TLS reciprocă la nivel de intrare (la cererea de conformitate).

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

Scopes sunt verificate pe fiecare apel. Pentru operațiunile (plățile) cu risc ridicat, se utilizează o intensificare: un domeniu de aplicare separat și, opțional, obligatoriu pentru IP/ASN.

4) Versioning și compatibilitate

Cale: '/v1/... ", "/v2/"... (versiunea majoră este incompatibilă înapoi).
Modificări minore și în extindere - prin extinderea schemei (noi câmpuri opționale).
Decretări - 90 de zile cu preaviz.
Cărțile web sunt versionate cu titlul „X-GH-Event-Version: 1”.

5) Limite, cote și idempotență

• „X-RateLimit-Limit”, „X-RateLimit-Reset”, „X-RateLimit-Reset”.
• 429 revine cu 'Retry-After' (secunde).
• Toate metodele nesigure necesită 'Idempotency-Key' (TTL 24-72 h). Repetarea unei interogări identice returnează rezultatul inițial ('409 IDEMP_REPLAY' privind conflictul).

6) Standarde de eroare

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”). Nerecuperabil: 400/401/403/404/409/ 422/410/415/412.

7) Scheme de date (de bază)

7. 1 Jucător

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 Sesiune

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 Portofel/Tranzacții

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 Rată/plată

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 (fragmente 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) Webhooks (GambleHub la partener)

• "X-GH-Event": "jucător. created 'session. started 'bet. plasat 'bet. settled 'wallet. schimbat 'kyc. actualizat "rg. flagged '
• "X-GH-Event-Id': UUID unic
• 'X-GH-Signature': 'sha256 = '
• „X-GH-Retry”: Încercare Nu
• „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"
}
}

Răspunsul gazdei - numai 2xx este considerat un succes. În caz contrar - retrai: backoff exponențial (1s, 3s, 10s, 30s, 2m, 10m, 30m; maximum 24 de ore). Utilizați "X-GH-Event-Id' pentru eliminarea duplicatelor.

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

10) Ordine de flux de numerar (Flux de portofel)

1. depozit (PSP → portofel. credit)

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

3. decontare (deţinere eliberare; „câştig ”/„ pierdere ”/„ gol”)

4. retragere (portofel. debit → PSP)

Soldurile hold și multi-portofele (real/bonus) sunt acceptate.

11) Sandbox și scenarii de testare

Testați jucătorii: 'p _ sbx _', valute' EUR 'USD' CAD'.
Furnizorii de jocuri emulează: câștig/pierdere/gol, reduceri, întârzieri.
KYC sandbox: „verificat” nu a reușit „revizuire” răspunsurile pe șabloane de pașaport.
Sandbox PSP: статусы "autorizat" capturat "decolorat" invers ".

• Bilanțul contabil Stavka→vyplata→sverka
• Runda pullback/gol
• Idempotența la re-ofertă
• Eșec al cârligului web cu retraverse și eliminare ulterioară a duplicatelor
• 429 și corectă „Încercați din nou”
• 5xx cu backoff exponențial pe partea clientului

12) Reconcilieri și raportare

API de reconciliere

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

Rezumate zilnice: cifre de afaceri, GGR/NGP, furnizori, defalcare geo/valută.
Export: S3/SFTP cu manifeste semnate și hash-uri de fișiere (SHA256).
Fusul orar de raportare: UTC (cu excepția cazului în care se specifică altfel în contract).

13) Observabilitate și SLO

SLI: succesul API ≥ 99. 95% (28d), latență p95 pentru metode critice, succes de livrare a cârligelor web.
Alerte de ardere (rapid/lent) pe un buget eronat.
Trace corelation: 'trace _ id' în răspunsuri/jurnale, trilldown la urme.
Status page: Edge, Wallet, Bets, Webhook-uri, componente PSP, KYC.

14) Siguranță și conformitate

Minimizarea PII; PAN/secretele sunt interzise in busteni/carti web.
Managementul secret şi rotaţia cheilor.
RG (Joc Responsabil): steagurile de auto-excludere/limită ar trebui să aibă ca rezultat negarea automată a pariurilor/plăților.
AML/KYC: "kyc' evenimente. actualizat „,” aml. alertă "sunt disponibile prin abonament; ia decizii în sistemul dvs. sau prin modulul nostru.
GDPR/DSAR: puncte finale pentru încărcarea/ștergerea datelor personale ale jucătorului pentru solicitări legale.
mTLS și HSTS sunt activate în mod implicit în mediul de producție.

15) Performanță și cote

• SPR: 50 (explozie 100)
• Cârlige web concurente: 10
• Dimensiunea caroseriei: ≤ 256 KB (evenimente de joc), ≤ 64 KB (portofel)

Solicitați o actualizare a planului prin intermediul managerului de cont, specificând prognoza/volumele SPR.

16) Schimbare și Release Management

Schimbarea ferestrelor: lucrari programate - in grafic, notificare ≥ 5 zile lucratoare.
Migrarea versiunilor: dual-write/dual-read în timpul perioadei de tranziție.
Teste contract CI: schema JSON, câmpuri obligatorii, stabil 'error _ code'.
Canare: includerea treptată a traficului pentru noi caracteristici.

17) Certificarea integrării (Check-list)

• Oferta/Plata Înregistrare/nul
• Idempotența tuturor punctelor finale de scriere
• Procesare corectă 429/5xx + backoff
• Verificarea semnăturii prin broșură web, Deduplicarea X-GH-Event-Id
• Echilibrarea reconcilierii după serii de evenimente (câștig/pierdere)
• Rapoartele de reconciliere sunt de acord cu datele dvs

• Retragerile prin webhook sunt implementate
• Timeout client ≤ 10c, încercare totală ≤ 30c
• Întrerupător de circuit pe dependențe

• Stocarea secretelor în managerul secret
• PII Edition în jurnale
• Steagurile RG/AML sunt luate în considerare în timp real

18) Scenarii utilizate frecvent

18. 1 Înregistrarea ratei cu idempotență

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 urmat de succes

1. Serverul dvs. nu este disponibil → retro 5xx → backoff.
2. După recuperare - ia același "X-GH-Event-ID' → sunt obligați să ignore duplicate.

18. 3 Degradarea parțială a furnizorului

Vom rambursa 503; repeta cu backoff.
Cu degradare îndelungată - opriți marcarea furnizorului și incluzând rutarea inteligentă (dacă se află în contract).

19) DevEx și suport

Portal: chei, utilizare, cârlige web, jurnale de livrare, tablouri de bord SLO, rapoarte de export.
Webhooks reluare: redelivery după intervalul de date/ID.
Incidente: auto-crearea unui bilet, cameră de război, post-mortem ≤ 48 de ore pe SEV-1.
Comunicații: # partners-status channel/mail on-call 24 × 7 (Enterprise).

20) Planul de îmbarcare (2-4 săptămâni)

1. Săptămâna 1: emisiune cheie, conexiune sandbox, scenarii de bază (pariu/plată/poșetă).
2. Săptămâna 2: Cârlige web și reconcilieri, steaguri RG/KYC, teste de încărcare, comportament 429/5xx.
3. Săptămâna 3: raportare (reconciliere, încărcare), securitate (semnături, secrete), teste contractuale.
4. Săptămâna 4: certificare, includere canară în vânzări, monitorizare, matrice de contact.

21) Mini-Întrebări frecvente

Pot avea gRPC?
Da, la cerere; Cartografierea codului de eroare HTTP este furnizată în caietul de sarcini.

Cum să obțineți date retro?
Prin rapoarte de „reconciliere” (de la/la date) sau încărcați S3/SFTP.

Cum îmi ridic limitele?
Prin portal/account manager indicând SPR/competitivitate prognozată.

Care este considerată sursa adevărului echilibrului?
Jurnalul tranzacției portofelului GambleHub + reconcilierea zilnică.

Total

Integrarea cu GambleHub se bazează pe un contract clar: API-uri și scheme stabile, cărți web semnate, idempotență și retrăiri, limite transparente și raportare, precum și cerințe de securitate și conformitate. Urmând acest ghid și listele de verificare de certificare, veți ajunge rapid pe piață, oferind fluxuri de numerar fiabile și rapoarte consecvente fără discrepanțe.