GambleHub интеграциялық нұсқаулығы

1) Шолу және өзара іс-қимыл моделі

• API провайдері: сіз GambleHub (әмиян, бонустар, есептер) API шақырады.
• Экстернал жеткізуші: біз сіздің вебхоктеріңізді/эндпоинттеріңізді (баланс, транзакциялар, KYC) шақырамыз.

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

2. Оқиғалар (event bus: ставкалар/төлемдер/әмиян/АКҚ)

3. Есептілік (API + S3/SFTP экспорты)

4. Операциялар (инциденттер, SLO, SLA-кредиттер)

2) Орталар, домендер және IP

Келісімшарттық SLA шартта тіркеледі. IP жаңартулары алдын ала жарияланады. Allowlist қызметіне рұқсат етіңіз.

3) Аутентификация және авторизация

• OAuth2 Client Credentials: сервер-серверге ('scope' lary: 'wallet: read', 'wallet: write', 'bet: write', 'report: read').
• JWT (issuer = GambleHub): RS256 қолы, JWKS-эндпоинттегі кілттер.
• mTLS: ingress деңгейінде өзара TLS-аутентификация (комплаенс сұрауы бойынша).

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

Scopes әрбір шақыруда тексеріледі. Жоғары тәуекелді операциялар (төлемдер) үшін step-up пайдаланылады: жеке scope және, қосымша, IP/ASN байланыстыру.

4) Нұсқалау және үйлесімділік

Жол: '/v1/... ', '/v2/...' (major-нұсқасы артқа сыйыспайды).
Шағын және кеңейтілетін өзгерістер - схеманы кеңейту арқылы (жаңа опциондық өрістер).
Депрекация - хабарламамен 90 күн бұрын.
Вебхактар 'X-GH-Event-Version: 1' тақырыбымен нұсқаланады.

5) Лимиттер, квоталар және теңсіздік

• `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
• 429 'Retry-After' (секунд) арқылы қайтады.
• Барлық қауіпсіз емес әдістер 'Idempotency-Key' (TTL 24-72 сағ) талап етеді. Ұқсас сұрауды қайталау бастапқы нәтижені қайтарады (қайшылықта '409 IDEMP_REPLAY').

6) Қателер стандарттары

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) Деректер схемалары (ядро)

7. 1 Ойыншы

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 Сессия

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 Әмиян/транзакциялар

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 Ставка/төлем

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 Бонус

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 фрагменттері)

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) Вебхактар (GambleHub-дан серіктеске)

• `X-GH-Event`: `player. created|session. started|bet. placed|bet. settled|wallet. changed|kyc. updated|rg. flagged`
• 'X-GH-Event-Id': бірегей UUID
• `X-GH-Signature`: `sha256=`
• 'X-GH-Retry': № әрекеті
• `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"
}
}

Қабылдаушы тараптың жауабы - тек 2xx қана табысты болып саналады. Басқаша - ретра: экспоненциалды backoff (1s, 3s, 10s, 30s, 2m, 10m, 30m; ең көп дегенде 24 сағат). Дедупликация үшін 'X-GH-Event-Id' дегенді пайдаланыңыз.

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

10) Ақша ағынының тәртібі (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-баланстар мен мульти-әмияндар (нақты/бонустық) қолданылады.

11) Құмсалғыш және тестілік сценарийлер

Тест ойыншылары: 'p _ sbx _', валюталар 'EUR' USD 'CAD'.
Ойын провайдерлері эмуляциялайды: win/lose/void, дисконнектілер, кідірістер.
KYC sandbox: 'verified' failed 'review' деген жауаптар паспорт үлгілері бойынша.
PSP sandbox: статусы `authorized|captured|declined|reversed`.

• Ставка → төлем → балансты салыстыру
• Айналым/void
• Қайталанған мөлшерлеме кезіндегі idempotency
• Ретрациямен және кейіннен дедупликациямен вебхукке қол жеткізу
• 429 және түзету 'Retry-After'
• 5xx клиент жағында экспоненциалды backoff

12) Салыстырып тексеру және есептілік

Reconciliation API

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

Күнделікті мәліметтер: айналымдар, GGR/NGP, провайдерлер, гео/валюталар бойынша разрез.
Экспорт: Қол қойылған файл манифесттері мен хэштері бар S3/SFTP (SHA256).
Есептер таймзоны: UTC (егер келісімшартта өзгеше айтылмаса).

13) Бақылау және SLO

SLI: API табыстылығы ≥ 99. 95% (28d), сыни әдістер үшін p95 latency, вебхуктерді жеткізудің табысты болуы.
Қате бюджет бойынша Burn-alerts (fast/slow).
Trace-корреляция: 'trace _ id' жауаптарда/логтарда, drilldown трассаларға.
Мәртебе-бет: Edge, Wallet, Bets, Webhooks, PSP, KYC компоненттері.

14) Қауіпсіздік және комплаенс

PII-азайту; PAN/құпиялар логтарда/веб-хуктерде тыйым салынған.
Secret-management және кілттерді ротациялау.
RG (Responsible Gambling): өздігінен алып тастау/лимиттердің жалаулары мөлшерлемелерде/төлемдерде автоматты түрде бас тартуға әкелуі тиіс.
AML/KYC: 'kyc оқиғалары. updated`, `aml. alert 'жазылым бойынша қол жетімді; өз жүйеңізде немесе біздің модуль арқылы шешім қабылдайсыз.
GDPR/DSAR: заңды сұрау бойынша ойыншының дербес деректерін түсіруге/жоюға арналған эндпоинттер.
mTLS және HSTS әдепкі өнертабыс ортасында қосылған.

15) Өнімділік және квоталар

• RPS: 50 (burst 100)
• Concurrent webhooks: 10
• Дене өлшемі: ≤ 256 KB (ойын оқиғалары), ≤ 64 KB (әмиян)

RPS/көлем болжамын көрсету арқылы аккаунт менеджері арқылы жоспарды жаңартуды сұраңыз.

16) Өзгерістер мен релиздерді басқару

Change windows: жоспарлы жұмыстар - кесте бойынша, хабарландыру ≥ 5 жұмыс күні.
Нұсқалық көші-қон: өтпелі кезеңде dual-write/dual-read.
CI Contract тестілері: JSON схемасы, міндетті өрістер, тұрақты 'error _ code'.
Canary: жаңа сандар үшін трафикті біртіндеп қосу.

17) Интеграцияны сертификаттау (Check-list)

• Ставканы тіркеу/төлемдер/void
• Барлық write-эндпоинттердегі теңсіздік
• 429/5xx + backoff дұрыс өңдеу
• Вебхуктардың қолтаңбаларын верификациялау, 'X-GH-Event-Id' бойынша дедупликациялау
• Оқиғалар сериясынан кейін балансты салыстыру (win/lose)
• reconciliation есептері сіздің деректеріңізбен үйлеседі

• Вебхуктардың ретрайлері іске асырылды
• Клиенттердің уақыты ≤ 10с, жалпы әрекет ≤ 30с
• Circuit-breaker тәуелділікте

• Құпия менеджерде құпияларды сақтау
• Логтардағы PII-редакция
• RG/AML жалаулары нақты уақытта есепке алынады

18) Жиі қолданылатын сценарийлер

18. 1 Сәйкестігі бар ставканы тіркеу

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 Кейіннен табысты вебхука фейл

1. Серверіңіз қол жетімді емес → 5xx → ретраи backoff.
2. Қалпына келтірілгеннен кейін сол 'X-GH-Event-Id' → дубликаттарын елемеу керек.

18. 3 Провайдердің ішінара құлдырауы

Біз 503 қайтарамыз; backoff бағдарламасымен қайталаңыз.
Ұзақ деградация кезінде - провайдердің тоқтату-таңбалануы және smart-routing (егер келісімшартта болса).

19) DevEx және қолдау

Portal: кілттер, usage, веб-хактар, жеткізу журналдары, SLO дашбордтары, есептер экспорты.
Webhooks replay: күн/ID диапазоны бойынша қайта жеткізу.
Инциденттер: auto-құру тикет, war-room, постмортем ≤ SEV-1 бойынша 48 сағат.
Коммуникациялар: #partners -status арна/почта on-call 24 × 7 (Enterprise).

20) Онбординг жоспары (2-4 апта)

1. 1-апта: кілттерді беру, sandbox қосу, базалық сценарийлер (мөлшерлеме/төлем/әмиян).
2. Апта 2: Вебхактар мен салыстыру, RG/KYC жалаулары, жүктеме тесттері, 429/5xx мінез-құлық.
3. 3-апта: есептілік (reconciliation, түсіру), қауіпсіздік (қолдар, құпиялар), келісімшарт-тестілер.
4. 4-апта: сертификаттау, canary-өнімге қосу, мониторинг, байланыс матрицасы.

21) Шағын FAQ

gRPC болуы мүмкін бе?
Иә, сұрау салу бойынша; HTTP қате кодтарының маппингі спецификацияда ұсынылады.

Ретро деректерді қалай алуға болады?
'reconciliation' ('from/to' күндері) немесе түсіру S3/SFTP есептері арқылы.

Лимиттерді қалай ұлғайтуға болады?
Болжамды RPS/бәсекелестікті көрсете отырып, портал/аккаунт-менеджер арқылы.

Тепе-теңдік ақиқатының қайнар көзі деп не ойлайсыз?
GambleHub әмиян транзакциялық журналы + күнделікті салыстыру (reconciliation).

Жиынтығы

GambleHub-пен интеграция нақты келісімшартқа негізделген: тұрақты API және схемалар, қол қойылған вебхактар, демпотенттілік және ретрайлер, мөлдір лимиттер мен есептілік, сондай-ақ қауіпсіздік пен комплаенс талаптары. Осы нұсқаулық пен сертификаттаудың чек-парақтарына сүйене отырып, сіз алшақтықсыз сенімді ақша ағындарын және келісілген есептерді қамтамасыз ете отырып, өнімге жылдам шығасыз.