GambleHub интеграциялык колдонмо

1) карап чыгуу жана өз ара аракеттенүү модели

• API-провайдер: Сиз GambleHub API чакырасыз (капчык, бонустар, отчеттор).
• Тышкы жөнөтүүчү: Биз сиздин WebHook/EndPoint (баланс, бүтүмдөр, KYC) чакырат.

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

2. Events (event bus: коюмдар/төлөмдөр/капчык/CUS)

3. Отчеттуулук (API + экспорт S3/SFTP)

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

2) чөйрөлөр, домендер жана IP

Келишимдик SLA келишимде белгиленет. IP жаңыртуулар алдын ала жарыяланат. Allowlist уруксат.

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

• OAuth2 Client Credentials: server-to-server ('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/...' (негизги версия артка туура келбейт).
Майда жана кеңейтүүчү өзгөрүүлөр - схеманы кеңейтүү аркылуу (жаңы кошумча талаалар).
Депрекация - билдирме менен 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) Webhook (өнөктөш үчүн 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 гана ийгилик болуп эсептелет. Болбосо - retrains: экспоненциалдык 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) Акча агымынын тартиби (Кошелек агымы)

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) Sandbox жана сыноо жагдайлар

Тесттик оюнчулар: '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 критикалык ыкмалар үчүн, Webhook жеткирүү ийгилиги.
Burn-alerts (fast/slow) туура эмес бюджет боюнча.
Trace-корреляция: жооптордо/логдордо 'trace _ id', жолдорго drilldown.
Статус-бет: Edge компоненттери, Wallet, Bets, Webhooks, PSP, KYC.

14) Коопсуздук жана комплаенс

PII-минималдаштыруу; тыюу салынган PAN/блог сырлары/vebhuk.
Secret-башкаруу жана ачкычтарды айлантуу.
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) өзгөртүүлөрдү жана толуктоолорду башкаруу

Өзгөртүү Windows: пландаштырылган иш - расписание, эскертүү ≥ 5 жумушчу күн.
Version көчүрүү: өткөөл мезгил ичинде dual-write/dual-окуу.
CI Contract тесттер: JSON схемасы, милдеттүү талаалар, туруктуу 'error _ code'.
Canary: жаңы fich үчүн бара-бара жол киргизүү.

17) Интеграция күбөлүк (Check-list)

• чендерди каттоо/төлөмдөр/void
• Бардык write-endpoints боюнча Идемпотенттүүлүк
• Туура иштетүү 429/5xx + backoff
• Webhook колтамгасын текшерүү, 'X-GH-Event-Id'
• Бир катар окуялардан кийин балансты салыштыруу (win/lose)
• reconciliation отчеттор сиздин маалыматтар менен дал келет

• Webhook Retray ишке ашырылган
• 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 Fail Webhook кийинки ийгилик менен

1. Сиздин сервер жеткиликтүү эмес → 5xx → backoff боюнча retrains.
2. калыбына кийин - ошол эле кабыл алуу 'X-GH-Event-Id' → дубликат четке кагууга милдеттүү.

18. 3 Провайдердин жарым-жартылай деградациясы

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

19) DevEx жана колдоо

Portal: ачкычтар, usage, Webhook, жеткирүү Логи, dashboard SLO, экспорт отчеттор.
Webhooks replay: Date/ID диапазону боюнча кайра жеткирүү.
Окуялар: auto-түзүү тикет, war-room, postmortem ≤ 48 саат SEV-1.
Байланыш: #partners -status канал/почта on-call 24 × 7 (Enterprise).

20) Онбординг планы (2-4 жума)

1. Апта 1: ачкычтарды берүү, sandbox туташуу, базалык сценарийлер (коюм/төлөм/капчык).
2. Жума 2: Webhook жана текшерүү, RG/KYC желектери, жүктөө тесттер, 429/5xx жүрүм-туруму.
3. Жума 3: отчеттуулук (reconciliation, жүктөө), коопсуздук (кол тамгалар, сырлар), келишим-тесттер.
4. Апта 4: тастыктоо, canary-киргизүү, мониторинг, байланыш матрица.

21) Mini-FAQ

gRPC болушу мүмкүнбү?
Ооба, суроо-талап боюнча; HTTP боюнча mapping ката коддору спецификациясында берилген.

Ретро маалыматтарды кантип алууга болот?
отчеттор аркылуу 'reconciliation' (даталар 'from/to') же S3/SFTP чыгаруу.

Кантип лимиттерди көбөйтүү керек?
Болжолдуу RPS/атаандаштыкты көрсөтүү менен портал/аккаунт-менеджер аркылуу.

Баланстын чындыгынын булагы деп эмне айтууга болот?
GambleHub капчык бүтүм журналы + күнүмдүк текшерүү (reconciliation).

Жыйынтык

GambleHub менен интеграция так келишимге негизделген: туруктуу API жана схемалар, кол коюлган вебхактар, демпотенттүүлүк жана ретрациялар, ачык-айкын лимиттер жана отчеттуулук, ошондой эле коопсуздук жана комплаенс талаптары. Бул колдонмону жана чек-сертификация баракчаларын сактоо менен сиз тез арада ишенимдүү акча агымдарын жана келишпестиктер жок макулдашылган отчетторду камсыз кылуу менен өндүрүшкө чыгасыз.