GambleHub integrasiýa gollanmasy

1) Özara gatnaşyklara syn we model

• API-üpjün ediji: Siz GambleHub API (gapjyk, bonuslar, hasabatlar) çagyrýarsyňyz.
• Daşarky üpjün ediji: webhuk/endpointleriňizi (balans, amallar, KYC) çagyrýarys.

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

2. Wakalar (waka bus: nyrhlar/tölegler/gapjyk/KUS)

3. Hasabat (API + eksport S3/SFTP)

4. Amallar (hadysalar, SLO, SLA-karzlar)

2) Gurşaw, domenler we IP

Şertnama SLA şertnamada bellenilýär. IP täzelenmeleri öňünden çap edilýär. Allowlist-a rugsat beriň.

3) Tassyklamak we ygtyýarlandyrmak

• OAuth2 Client Credentials: serwer-a ('scope' s: 'wallet: read', 'wallet: write', 'bet: write', 'report: read').
• JWT (issuer = GambleHub): RS256 goly, JWKS-endpointdäki açarlar.
• mTLS: ingress derejesinde özara TLS-autentifikasiýasy (komplayensiň haýyşy boýunça).

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

Her çagyryşda skoplar barlanýar. Töwekgelçilikli amallar (tölegler) üçin step-up ulanylýar: aýratyn skope we goşmaça IP/ASN baglanyşygy.

4) Wersiýalaşdyrmak we gabat gelmek

Ýol: '/v1/... ', '/v2/...' (major-wersiýasy yza gabat gelmeýär).
Kiçi we giňeldiji üýtgeşmeler - shemany giňeltmek arkaly (täze opsiýa meýdançalary).
Deprekasiýa - habar bilen 90 günüň içinde.
Webhuklar 'X-GH-Event-Version: 1' sözbaşy bilen wersiýa edilýär.

5) Çäkler, kwotalar we dempotentlik

• `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
• 429 "Retry-After" (sekunt) bilen gaýdyp gelýär.
• Ähli howply usullar "Idempotency-Key" (TTL 24-72 sagat) talap edýär. Şol bir haýyşyň gaýtalanmagy başlangyç netijäni berýär ('409 IDEMP_REPLAY' gapma-garşylykda).

6) Ýalňyşlyklaryň standartlary

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) Maglumatlaryň shemalary (özeni)

7. 1 Oýunçy

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 Sessiýa

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 Gapjyk/amallar

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 Stawka/töleg

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 bölekleri)

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) Webhuklar (GambleHub-dan hyzmatdaşa)

• `X-GH-Event`: `player. created|session. started|bet. placed|bet. settled|wallet. changed|kyc. updated|rg. flagged`
• 'X-GH-Event-Id': özboluşly UUID
• `X-GH-Signature`: `sha256=`
• 'X-GH-Retry': synanyşyk №
• `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"
}
}

Kabul ediji tarapyň jogaby - diňe 2xx üstünlikli hasaplanýar. Otherwiseogsam - retrailer: eksponensial backoff (1s, 3s, 10s, 30s, 2m, 10m, 30m; iň köp 24 sagat). Göçürmek üçin 'X-GH-Event-Id' ulanyň.

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

10) Pul akymynyň tertibi (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 we köp gapjyklar (hakyky/bonus) goldanylýar.

11) Sandyk gutusy we synag ssenarileri

Synag oýunçylary: 'p _ sbx _', walýuta 'EUR' USD 'CAD'.
Oýun üpjün edijileri emulýasiýa edýärler: win/lose/void, arzanladyşlar, gijikdirmeler.
KYC sandbox: jogaplar 'verified' failed 'review' pasport şablonlary boýunça.
PSP sandbox: статусы `authorized|captured|declined|reversed`.

• Nyrh → töleg → balans barlagy
• Aýlawdan/void
• Gaýtalanýan nyrhda idempotency
• Webhuky retralar we soňraky duplikasiýa bilen sboy
• 429 we dogry 'Retry-After'
• 5xx müşderi tarapynda eksponensial backoff

12) Deňeşdirmeler we hasabatlylyk

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ündelik habarlar: dolanyşyklar, GGR/NGP, üpjün edijiler, geo/walýuta boýunça kesme.
Eksport: Gol çekilen manifestler we faýl heşleri bilen S3/SFTP (SHA256).
Hasabatlaryň wagt zolagy: UTC (eger şertnamada başgaça göz öňünde tutulmadyk bolsa).

13) Synlamak we SLO

SLI: API-iň üstünligi ≥ 99. 95% (28d), p95 latency kritiki usullar üçin, webhuklary gowşurmagyň üstünligi.
Burn-alerts (fast/slow) nädogry býudjet boýunça.
Trace-korrelasiýa: 'trace _ id' jogaplarda/bloglarda, drilldown-dan ýollara.
Status-sahypa: Edge, Wallet, Bets, Webhooks, PSP, KYC komponentleri.

14) Howpsuzlyk we gabat gelmek

PII-minimallaşdyrmak; bloglarda/webhuklarda PAN/syrlar gadagan.
Secret-management we açarlaryň aýlanmagy.
RG (Responsible Gambling): Öz-özüni aýyrmak/çäklendirmek baýdaklary nyrhlaryň/tölegleriň awtomatiki ret edilmegine getirmelidir.
AML/KYC: wakalar 'kyc. updated`, `aml. alert 'abuna ýazylmak arkaly elýeterlidir; öz ulgamyňyzda ýa-da modulymyz arkaly karar berýärsiňiz.
GDPR/DSAR: kanuny haýyşlar boýunça oýunçynyň şahsy maglumatlaryny düşürmek/aýyrmak üçin endpointler.
mTLS we HSTS prob-gurşawda adaty ýagdaýda açylýar.

15) Öndürijilik we kwotalar

• RPS: 50 (burst 100)
• Concurrent webhooks: 10
• Beden ululygy: ≤ 256 KB (oýun wakalary), ≤ 64 KB (gapjyk)

RPS/göwrümi çaklamasyny görkezip, hasap dolandyryjysy arkaly meýilnamany täzeläň.

16) Üýtgetmeleri we goýberişleri dolandyrmak

Change windows: meýilleşdirilen işler - meýilnama boýunça, habar ≥ 5 iş güni.
Wersiýa göçmeleri: geçiş döwründe dual-write/dual-read.
CI-de contract-testler: JSON shemasy, hökmany meýdanlar, durnukly 'error _ code'.
Canary: Täze ugurlar üçin traffigiň kem-kemden açylmagy.

17) Integrasiýa şahadatnamasy (Check-list)

• Stawkany hasaba almak/tölegler/void
• Ähli write-endpointlerde idempotentlik
• Dogry 429/5xx + backoff
• Webhuklaryň goluny tassyklamak, 'X-GH-Event-Id' -den göçürmek
• Birnäçe wakadan soň deňagramlylygy deňeşdirmek (win/lose)
• Reconciliation hasabatlary siziň maglumatlaryňyza laýyk gelýär

• Webhook retraýlary amala aşyryldy
• Müşderileriň wagtlary ≤ 10s, umumy synanyşyk ≤ 30s
• Circuit-breaker garaşly

• Gizlin dolandyryjyda gizlin saklamak
• Bloglarda PII redaksiýasy
• RG/AML baýdaklary hakyky wagtda hasaba alynýar

18) Köplenç ulanylýan ssenariýalar

18. 1 Jedelli stawkany bellige almak

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 webhuk

1. Serveriňiz elýeterli däl → 5xx → backoff retrailer.
2. Dikeldilenden soň, şol bir 'X-GH-Event-Id' → kabul edýärsiňiz.

18. 3 Üpjün edijiniň bölekleýin pese gaçmagy

Biz yzyna gaýtaryp bereris 503; backoff bilen gaýtalaň.
Uzak wagtlap pese gaçanda - üpjün edijiniň duralgasy we smart-routing (eger şertnamada bar bolsa).

19) DevEx we goldaw

Portal: açarlar, usage, webhuklar, eltiş ýazgylary, SLO dashbordlary, hasabatlaryň eksporty.
Webhooks replay: seneler/ID diapazony boýunça gaýtadan eltip bermek.
Wakalar: awto-döretmek bileti, war-room, postmortem ≤ 48 sagat SEV-1.
Aragatnaşyk: #partners -status kanaly/poçta on-call 24 × 7 (Enterprise).

20) Onbording meýilnamasy (2-4 hepde)

1. 1-nji hepde: açarlary bermek, sandbox birikdirmek, esasy ssenariýalar (stawka/töleg/gapjyk).
2. 2-nji hepde: webhuklar we barlyşyklar, RG/KYC baýdaklary, ýük synaglary, 429/5xx özüni alyp barşy.
3. 3-nji hepde: hasabat (reconciliation, düşürmek), howpsuzlyk (gollar, syrlar), şertnama-synaglar.
4. 4-nji hepde: sertifikat, önüme canary-goşulma, gözegçilik, aragatnaşyk matrisi.

21) Mini-FAQ

gRPC mümkinmi?
Hawa, haýyş boýunça; HTTP-daky ýalňyşlyk kodlarynyň mappingi aýratynlykda berilýär.

Retro maglumatlary nädip almaly?
Hasabatlar arkaly 'reconciliation' (seneler 'from/to') ýa-da düşürmek S3/SFTP.

Çäkleri nädip ýokarlandyrmaly?
Çak edilýän RPS/bäsdeşlik ukybyny görkezýän portal/hasap dolandyryjysy arkaly.

Deňagramlylygyň hakykatynyň çeşmesi näme?
GambleHub gapjygynyň geleşik magazineurnaly + gündelik deňeşdirme (reconciliation).

Jemi

GambleHub bilen integrasiýa anyk şertnama esaslanýar: durnukly API we shemalar, gol çekilen webhuklar, idempotentlik we retralar, aç-açan çäkler we hasabat, şeýle hem howpsuzlyk we laýyklyk talaplary. Bu gollanmany we sertifikatlaşdyryş çek-sanawlaryny ýerine ýetirmek bilen, Siz tapawutsyz ygtybarly pul akymlaryny we ylalaşylan hasabatlary üpjün edip, çalt önümçilige çykarsyňyz.