GambleHub integratsiya qoʻllanmasi

1) O’zaro hamkorlik sharhi va modeli

• API provayderi: Siz GambleHub (hamyon, bonuslar, hisobotlar) APIlarini chaqirasiz.
• Tashqi etkazib beruvchi: Biz sizning vebxuklaringizni/endpointlaringizni (balans, tranzaksiyalar, KYC) chaqiramiz.

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

2. Hodisalar (event bus: stavkalar/to’lovlar/hamyon/QQS)

3. Hisobot (API + eksport S3/SFTP)

4. Operatsiyalar (noxush hodisalar, SLO, SLA-kreditlar)

2) Muhit, domen va IP

Kontrakt SLA shartnomada qayd etiladi. IP yangilanishlari oldindan eʼlon qilinadi. Allowlist’ga ruxsat bering.

3) Autentifikatsiya va avtorizatsiya

• OAuth2 Client Credentials: server-server (’scope’lari:’wallet: read’,’wallet: write’,’bet: write’,’report: read’).
• JWT (issuer = GambleHub): RS256 imzosi, JWKS endpointidagi kalitlar.
• mTLS: ingress darajasida o’zaro TLS autentifikatsiyasi (komplayens so’rovi bo’yicha).

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

Scopes har bir chaqiruvda tekshiriladi. Yuqori tavakkalchilik operatsiyalari (to’lovlari) uchun step-up: alohida scope va ixtiyoriy ravishda IP/ASN ga bog’lash qo’llaniladi.

4) Versiyalash va muvofiqlik

Yoʻl: ’/v1/...’, ’/v2/...’(major versiyasi orqaga mos kelmaydi).
Kichik va kengaytiruvchi o’zgarishlar - sxemani kengaytirish orqali (yangi opsion maydonlari).
Depreksiya - bildirishnoma bilan 90 kun oldin.
Vebxuklar’X-GH-Event-Version: 1’sarlavhasi bilan versiya qilinadi.

5) Limitlar, kvotalar va idempotentlik

• `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
• 429’Retry-After’dan qaytadi (soniya).
• Barcha xavfli usullar «Idempotency-Key» (TTL 24-72 soat) talab qiladi. Bir xil soʻrovni takrorlash boshlangʻich natijani qaytaradi (’409 IDEMP_REPLAY' mojaroda).

6) Xato standartlari

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) Ma’lumotlar sxemalari (yadro)

7. 1 oʻyinchi

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 Hamyon/tranzaksiyalar

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 Stavka/to’lov

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 parchalari)

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

• `X-GH-Event`: `player. created|session. started|bet. placed|bet. settled|wallet. changed|kyc. updated|rg. flagged`
• ’X-GH-Event-Id’: noyob UUID
• `X-GH-Signature`: `sha256=`
• ’X-GH-Retry’: urinish №
• `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"
}
}

Qabul qiluvchi tomonning javobi - faqat 2xx muvaffaqiyatli hisoblanadi. Aks holda - retrai: eksponensial backoff (1s, 3s, 10s, 30s, 2m, 10m, 30m; ko’pi bilan 24 soat). Deduplikatsiya uchun’X-GH-Event-Id’dan foydalaning.

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

10) Pul oqimi tartibi (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-balanslar va ko’p hamyonlar (real/bonus) qo’llab-quvvatlanadi.

11) Qum qutisi va test stsenariylari

Test o’yinchilari:’p _ sbx _’, valyutalar’EUR’USD’CAD’.
O’yin provayderlari: win/lose/void, diskonnektlar, kechikishlar.
KYC sandbox: javoblar’verified’failed’review’pasport namunalari boʻyicha.
PSP sandbox: статусы `authorized|captured|declined|reversed`.

• Stavka → to’lov → balansni solishtirish
• Qaytish/void raund
• Takroriy stavkada idempotency
• Vebxukni retralar va keyinchalik duplikatsiya bilan o’tkazish
• 429 va to’g "ri’Retry-After ’
• 5xx mijoz tomonida eksponensial backoff

12) Solishtirishlar va hisobotlar

Reconciliation API

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

Kundalik ma’lumotlar: oborotlar, GGR/NGP, provayderlar, geo/valyutalar bo’yicha kesim.
Eksport: imzolangan manifestlar va fayl xeshlari (SHA256) bilan S3/SFTP.
Hisobotlar taymzoni: UTC (agar kontraktda boshqacha tartib belgilanmagan bo’lsa).

13) Kuzatuv va SLO

SLI: API muvaffaqiyati ≥ 99. 95% (28d), tanqidiy usullar uchun p95 latency, vebxuklarni yetkazib berish muvaffaqiyati.
Burn-alerts (fast/slow) noto’g "ri budjet bo’yicha.
Trace-korrelyatsiya:’trace _ id’javoblarda, drilldown trassalarga.
Maqom sahifasi: Edge, Wallet, Bets, Webhooks, PSP, KYC komponentlari.

14) Xavfsizlik va komplayens

PII - minimallashtirish; log/vebxuklarda PAN/sirlar taqiqlangan.
Secret-management va kalitlarni almashtirish.
RG (Responsible Gambling): o’z-o’zini istisno qilish/limitlar bayroqlari stavkalar/to’lovlarni avtomatik ravishda rad etishga olib kelishi kerak.
AML/KYC: hodisalar’kyc. updated`, `aml. alert’obuna bo’yicha mavjud; o’z tizimingizda yoki bizning modulimiz orqali qarorlar qabul qilasiz.
GDPR/DSAR: yuridik so’rovlar bo’yicha o’yinchining shaxsiy ma’lumotlarini yuklash/o’chirish uchun endpointlar.
mTLS va HSTS namunaviy muhitda andoza tarzda yoqilgan.

15) Unumdorlik va kvotalar

• RPS: 50 (burst 100)
• Concurrent webhooks: 10
• Tana o’lchami: ≤ 256 KB (o’yin tadbirlari), ≤ 64 KB (hamyon)

RPS/hajmlar prognozini koʻrsatish orqali hisobni yangilashni soʻrang.

16) O’zgartirishlar va relizlarni boshqarish

Change windows: rejali ishlar - jadval boʻyicha, xabarnoma ≥ 5 ish kuni.
O’tish davrida versiya migratsiyasi: dual-write/dual-o’qish.
Contract testlari: JSON sxemasi, majburiy maydonlar, barqaror’error _ code’.
Canary: yangi sahifa uchun trafikni bosqichma-bosqich yoqish.

17) Integratsiyani sertifikatlash (Check-list)

• Stavkani/to’lovlarni/void ro’yxatdan o’tkazish
• Barcha write-endpointlarda idempotentlik
• 429/5xx + backoff
• Vebxuk imzosini verifikatsiya qilish,’X-GH-Event-Id ’
• Bir qator voqealardan keyin balansni solishtirish (win/lose)
• Reconciliation hisobotlari sizning

• Vebxuk retraylari amalga oshirildi
• Mijozlarning taymautlari ≤ 10s, umumiy urinish ≤ 30s
• Circuit-breaker qaramlikda

• Maxfiy menejerda sirlarni saqlash
• PII-tahriri
• RG/AML bayroqlari real vaqtda hisobga olinadi

18) Ko’p ishlatiladigan stsenariylar

18. 1 Idempotentlik stavkasini ro’yxatdan o’tkazish

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 Fayl vebxuka va keyingi muvaffaqiyat

1. Serveringiz mavjud emas → 5xx → backoff.
2. Tiklangandan so’ng, xuddi shu’X-GH-Event-Id’→ ni qabul qilasiz.

18. 3 Provayderning qisman degradatsiyasi

Biz 503 ni qaytaramiz; backoff bilan takrorlang.
Uzoq tanazzulga uchraganda - provayderning stop-markirovkasi va shu jumladan smart-routing (agar kontraktda bo’lsa).

19) DevEx va qo’llab-quvvatlash

Portal: kalitlar, usage, vebxuklar, yetkazib berish daftarlari, SLO dashbordlari, hisobotlarni eksport qilish.
Webhooks replay: sana/ID diapazoni boʻyicha qayta yetkazib berish.
Hodisalar: auto-tiket yaratish, war-room, postmortem ≤ SEV-1 bo’yicha 48 soat.
Kommunikatsiyalar: #partners -status kanal/pochta on-call 24 × 7 (Enterprise).

20) Onbording rejasi (2-4 hafta)

1. 1-hafta: kalitlarni berish, sandbox ulanish, bazaviy stsenariylar (stavka/to’lov/hamyon).
2. Hafta 2: vebxuklar va taqqoslashlar, RG/KYC bayroqlari, yuklash testlari, 429/5xx xatti-harakatlar.
3. 3-hafta: hisobot (reconciliation, tushirish), xavfsizlik (imzolar, sirlar), kontrakt-testlar.
4. 4-hafta: sertifikatlash, canary-prodga kiritish, monitoring, kontakt matritsasi.

21) Mini-FAQ

gRPC boʻlishi mumkinmi?
Ha, so’rov bo’yicha; xato kodlarining HTTP mapping spetsifikatsiyasida taqdim etiladi.

Retro ma’lumotlarni qanday olish mumkin?
Hisobotlar orqali’reconciliation’(sanalar’from/to’) yoki S3/SFTP tushirish.

Limitlarni qanday oshirish mumkin?
Prognoz RPS/raqobatbardoshlik ko’rsatilgan portal/akkaunt menejeri orqali.

Muvozanatning manbai nimada?
GambleHub hamyonining tranzaksion jurnali + kundalik solishtirish (reconciliation).

Jami

GambleHub bilan integratsiya aniq shartnomaga asoslanadi: barqaror API va sxemalar, imzolangan vebxuklar, idempotentlik va retrajlar, shaffof limitlar va hisobotlar, shuningdek xavfsizlik va komplayens talablari. Ushbu yoʻl-yoʻriq va sertifikatlashtirish chek-varaqlariga amal qilib, siz ishonchli pul oqimlari va kelishilgan hisobotlarni hech qanday tafovutsiz taʼminlab, tez orada ishlab chiqarishga kirishasiz.