GambleHub İnteqrasiya Təlimatı

1) Baxış və qarşılıqlı model

• API provayderi: Siz GambleHub API-ni çağırırsınız (cüzdan, bonuslar, hesabatlar).
• Xarici təchizatçı: biz sizin vebhuk/end point (balans, əməliyyatlar, KYC) çağırır.

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

2. Hadisələr (event bus: dərəcələr/ödənişlər/cüzdan/cüzdan)

3. Hesabat (API + ixrac S3/SFTP)

4. Əməliyyatlar (hadisələr, SLO, SLA kreditləri)

2) Mühit, domen və IP

Müqavilə SLA müqavilədə qeyd olunur. IP yeniləmələri əvvəlcədən dərc olunur. Allowlist icazə.

3) Autentifikasiya və avtorizasiya

• OAuth2 Client Credentials: server-server ('scope' s: 'wallet: read', 'wallet: write', 'bet: write', 'report: read').
• JWT (issuer = GambleHub): RS256 imzası, JWKS end-point açarları.
• mTLS: ingress səviyyəsində qarşılıqlı TLS autentifikasiyası (komplayens tələbi üzrə).

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

Scopes hər çağırışda yoxlanılır. Yüksək riskli əməliyyatlar (ödənişlər) üçün step-up istifadə olunur: ayrıca scope və əlavə olaraq IP/ASN-ə bağlama.

4) Version və uyğunluq

Yol: '/v1/... ', '/v2/...' (major versiyası geri uyğun gəlmir).
Kiçik və genişləndirici dəyişikliklər - sxemin genişləndirilməsi vasitəsilə (yeni opsion sahələri).
Deprekasiya - bildirişlə 90 gün əvvəl.
Vebhukları 'X-GH-Event-Version: 1' başlığı ilə versiya olunur.

5) Limitlər, kvotalar və idempotentlik

• `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
• 429 'Retry-After' (saniyə) ilə qayıdır.
• Bütün təhlükəli üsullar «Idempotency-Key» (TTL 24-72 saat) tələb edir. Eyni sorğunun təkrarı ilkin nəticəni qaytarır ('409 IDEMP_REPLAY' münaqişə zamanı).

6) Səhv standartları

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) Məlumat sxemləri (nüvə)

7. 1 oyunçu

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 Sessiya

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 Cüzdan/əməliyyatlar

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 Mərc/Ödəniş

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 (OpenAPI fraqmentləri)

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 (GambleHub-dan partnyora)

• `X-GH-Event`: `player. created|session. started|bet. placed|bet. settled|wallet. changed|kyc. updated|rg. flagged`
• 'X-GH-Event-Id': unikal UUID
• `X-GH-Signature`: `sha256=`
• 'X-GH-Retry': Cəhd No
• `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"
}
}

Ev sahibinin cavabı - yalnız 2xx uğur hesab olunur. Əks - retras: eksponensial backoff (1s, 3s, 10s, 30s, 2m, 10m, 30m; maksimum 24 saat). Deduplikasiya üçün 'X-GH-Event-Id' istifadə edin.

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

10) Pul axını qaydası (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)

Hold-balans və multi-cüzdan (real/bonus) dəstəklənir.

11) Qum qutusu və test ssenariləri

Test oyunçuları: 'p _ sbx _', valyutalar 'EUR' USD 'CAD'.
Oyun provayderləri emulyasiya edir: win/lose/void, endirimlər, gecikmələr.
KYC sandbox: cavablar 'verified' failed 'review' pasport şablonları üzrə.
PSP sandbox: статусы `authorized|captured|declined|reversed`.

• Mərc → ödəniş → balans müqayisə
• Dönüş/void
• Idempotency
• Retralar və sonrakı duplikasiya ilə vebhuku yığın
• 429 və düzgün 'Retry-After'
• 5xx müştəri tərəfində eksponensial backoff ilə

12) Yoxlama və hesabat

Reconciliation API

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

Gündəlik hesabatlar: dövriyyələr, GGR/NGP, provayderlər, geo/valyuta kəsilməsi.
İxrac: imzalanmış fayl manifestləri və heşləri ilə S3/SFTP (SHA256).
Hesabatların Taymzonu: UTC (müqavilədə başqa bir şey deyilsə).

13) Müşahidə və SLO

SLI: API müvəffəqiyyəti ≥ 99. 95% (28d), kritik üsullar üçün p95 latency, webhook çatdırılması müvəffəqiyyəti.
Burn-alerts (fast/slow) səhv büdcə ilə.
Trace-korrelyasiya: cavablarda/loqlarda 'trace _ id', yollara drilldown.
Status-səhifə: Edge, Wallet, Bets, Webhooks, PSP, KYC komponentləri.

14) Təhlükəsizlik və uyğunluq

PII-minimallaşdırma; log/vebhuk PAN/sirləri qadağan.
Secret-management və açar rotasiyası.
RG (Responsible Gambling): Öz-özünə istisna/limit bayraqları avtomatik olaraq dərəcələrin/ödənişlərin rədd edilməsinə səbəb olmalıdır.
AML/KYC: hadisələr 'kyc. updated`, `aml. alert 'abunə ilə mövcuddur; öz sisteminizdə və ya modulumuz vasitəsilə qərarlar qəbul edin.
GDPR/DSAR: Qanuni tələblər üzrə oyunçunun şəxsi məlumatlarının yüklənməsi/silinməsi üçün son nöqtələr.
mTLS və HSTS prod mühitində default olaraq daxil edilmişdir.

15) Performans və kvotalar

• RPS: 50 (burst 100)
• Concurrent webhooks: 10
• Bədən ölçüsü: ≤ 256 KB (oyun hadisələri), ≤ 64 KB (cüzdan)

RPS/həcm proqnozunu göstərərək hesab meneceri vasitəsilə plan yeniləməsini tələb edin.

16) Dəyişikliklər və buraxılışların idarə edilməsi

Change windows: planlı iş - cədvəl, bildiriş ≥ 5 iş günü.
Version miqrasiyası: keçid dövründə dual-write/dual-read.
CI Contract testləri: JSON sxemi, məcburi sahələr, sabit 'error _ code'.
Canary: Yeni xüsusiyyətlər üçün trafikin tədricən daxil edilməsi.

17) İnteqrasiya Sertifikatlaşdırma (Check-list)

• Dərəcələrin/ödənişlərin/void qeydiyyatı
• Bütün write nöqtələrində idempotentlik
• Düzgün emal 429/5xx + backoff
• Vebhuk imzasının təsdiqlənməsi, 'X-GH-Event-Id' deduplikasiyası
• Bir sıra hadisələrdən sonra balans müqayisə (win/lose)
• Reconciliation hesabatları məlumatlarınızla uyğundur

• Webhook Retrains həyata keçirilmişdir
• Müştəri vaxtları ≤ 10s, ümumi cəhd ≤ 30s
• Asılılıqda Circuit-breaker

• Sirr menecerində sirlərin saxlanması
• Log-da PII redaktəsi
• RG/AML bayraqları real vaxt nəzərə alınır

18) Tez-tez istifadə olunan ssenarilər

18. 1 İdempotentlik dərəcəsi qeydiyyatı

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 sonrakı müvəffəqiyyətlə

1. Server mövcud deyil → 5xx → backoff tərəfindən retrai.
2. Bərpa edildikdən sonra - eyni 'X-GH-Event-Id' → qəbul edin.

18. 3 Provayderin qismən deqradasiyası

503 qaytaracağıq; backoff ilə təkrarlayın.
Uzun deqradasiyada - provayderin stop-markalanması və smart-routing daxildir (əgər müqavilədə varsa).

19) DevEx və dəstək

Portal: açarlar, usage, vebhuk, çatdırılma qeydləri, SLO dashboard, ixrac hesabatları.
Webhooks replay: tarix/ID diapazonu üzrə təkrar çatdırılma.
Hadisələr: auto-yaradılması bileti, war-room, postmortem ≤ 48 saat SEV-1.
Rabitə: #partners -status kanal/poçt on-call 24 × 7 (Enterprise).

20) Onbordinq planı (2-4 həftə)

1. Həftə 1: açarların verilməsi, sandbox bağlantısı, əsas ssenarilər (bahis/ödəniş/cüzdan).
2. Həftə 2: vebhuks və yoxlama, RG/KYC bayraqlar, yük testləri, 429/5xx davranış.
3. Həftə 3: hesabat (reconciliation, boşaltma), təhlükəsizlik (imzalar, sirlər), müqavilə testləri.
4. Həftə 4: sertifikatlaşdırma, canary-prod daxil, monitorinq, əlaqə matrisi.

21) Mini-FAQ

gRPC mümkündür?
Bəli, tələb; HTTP mapping səhv kodları spesifikasiyada verilir.

Retro məlumatları necə əldə etmək olar?
Hesabatlar vasitəsilə 'reconciliation' (tarixlər 'from/to') və ya boşaltma S3/SFTP.

Limitləri necə artırmaq olar?
Portal/hesab meneceri vasitəsilə proqnozlaşdırılan RPS/rəqabət qabiliyyətini göstərir.

Balans həqiqətinin mənbəyi nədir?
GambleHub cüzdan əməliyyat jurnalı + gündəlik yoxlama (reconciliation).

Yekun

GambleHub ilə inteqrasiya aydın müqaviləyə əsaslanır: sabit API və sxemlər, imzalanmış vebhuklar, idempotentlik və retrajlar, şəffaf limitlər və hesabatlar, təhlükəsizlik və uyğunluq tələbləri. Bu təlimata və sertifikatlaşdırma yoxlama vərəqələrinə əməl edərək, etibarlı pul axınlarını və uyğunlaşdırılmış hesabatları uyğunsuzluqlar olmadan təmin edərək, tez bir zamanda məhsula çıxacaqsınız.