GambleHub 통합 가이드

1) 개요 및 상호 작용 모델

GambleHub는 iGaming 서비스 (게임 제공 업체, 결제 게이트웨이, KYC/AML, 보너스 엔진, 보고서) 를위한 집계 플랫폼입니다. 파트너 통합은 두 가지 모드로 가능합니다

API 제공 업체: GambleHub API (지갑, 보너스, 보고서) 라고합니다.
외부 제공 업체: 웹 후크/엔드 포인트 (잔액, 거래, KYC) 라고합니다.

1. 가장자리/API (REST/gRPC, 웹 후크)

2. 이벤트 (이벤트 버스: 베팅/지불/지갑/ICC)

3. 보고 (API + S3/STP 내보내기)

4. 운영 (사고, SLO, SLA 크레딧)

2) 환경, 도메인 및 IP

계약 SLA는 계약에서 수정됩니다. IP 업데이트는 사전에 게시됩니다. 할당량 목록을 허용하십시오

3) 인증 및 인증

우리는 세 가지 메커니즘을 지원합니다 (계약에 필요한 메커니즘을 선택)

OAuth2 클라이언트 자격 증명: 서버 간 서버 ('범위': '지갑: 읽기', '지갑: 쓰기', '내기: 쓰기', '보고서: 읽기').
JWT (issuer = GambleHub): RS256 서명, JWKS 엔드 포인트의 키.
mSL: 입력 레벨에서의 상호 SL 인증 (규정 준수 요청).

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

스코프는 각 통화에서 확인됩니다. 고위험 운영 (지불) 의 경우 별도의 범위와 선택적으로 IP/ASN에 구속력있는 스텝 업이 사용됩니다.

4) 수정 및 호환성

경로: '/v1/... ', '/v2/...' (주요 버전은 호환되지 않습니다).
체계의 확장 (새로운 옵션 필드) 을 통해 약간의 변경 및 확장.
감소-통지 90 일.
웹 후크에는 제목 'X-GH-Event-Version: 1' 이 있습니다.

5) 한계, 할당량 및 demmpotency

속도 제한은 헤더에 의해 제공됩니다

'X-RateLimit-Limit', 'X-RateLimit-Remaining', 'X-RateLimit-Reatting'.
429는 'Redue-After' (초) 로 반환됩니다.
모든 안전하지 않은 방법에는 'Idempotency-Key' (TTL 24-72 h) 가 필요합니다. 동일한 쿼리를 반복하면 원래 결과 (충돌시 '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"}]
}

검색 가능: 5xx/503/504/429 ('Redch-After'). 검색 불가: 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 to Partner)

이벤트는 '컨텐츠 유형: 응용 프로그램/json', 헤더 순서대로 발송됩니다

'X-GH 이벤트': '플레이어. 세션을 만들었습니다. 내기를 시작했습니다. 배치. 정착 된 지갑. 'kyc. 업데이트 된 'rg. 깃발 '

'X-GH-Event-ID': 고유 한 UUI

'X-GH-Signature': 'sha256 = '

'X-GH 재시도': 시도 없음

'X-GH 이벤트 버전': '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 만 성공한 것으로 간주됩니다. 그렇지 않으면-retrai: 지수 백오프 (1, 3, 10, 30, 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. 예금 (PSP → 지갑. 신용)

2. 내기 (и독점 자동 이체 보유/승인)

3. 결제 (릴리스 보류; '승리 '/' 잃어버린 '/' 공허')

4. 철수 (지갑. 직불 → PSP)

홀드 밸런스와 멀티 월렛 (실제/보너스) 이 지원됩니다.

11) 샌드 박스 및 테스트 시나리오

테스트 플레이어: 'p _ sbx _', 통화 'EUR' USD 'CAD'.
게임 제공 업체는 승리/손실/무효, 할인, 지연을 모방합니다.
KYC 샌드 박스: 여권 템플릿에서 '확인 된' 실패 '검토' 응답.
PSP 샌드 박스: стат계정 '승인 된' 캡처 된 '반전'.

• 밸런스 시트 Stavka → vyplata → sverka
• 풀백/보이드 라운드
• 재 입찰시 이념성
• 배설물 및 후속 중복 제거로 웹 후크 실패
• 429 및 정확한 '재생 후'
• 클라이언트 측 지수 백오프가있는 5xx

12) 조정 및보고

조정 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 (SH256).
보고 시간대: UTC (계약서에 달리 명시되지 않는 한).

13) 관찰 및 SLO

SLI: API의 성공 95% (28d), 중요한 방법에 대한 p95 대기 시간, 웹 후크 전달 성공.
잘못된 예산으로 번 알림 (빠른/느린).
추적 상관 관계: 응답/로그에서 'trace _ id', 추적으로 드릴 다운.
상태 페이지: Edge, Wallet, Bets, Webhooks, PSP, KYC 구성 요소.

14) 안전 및 준수

PII 최소화; 로그/웹 후크에서는 PAN/비밀이 금지됩니다.
비밀 관리 및 키 교체.
RG (Responsible Gambling): 자체 제외/제한 플래그는 베팅/지불을 자동으로 거부해야합니다.
AML/KYC: 'kyc' 이벤트. ',' aml 업데이트되었습니다. 경고 '는 구독으로 제공됩니다. 시스템이나 모듈을 통해 결정을 내립니다.
GDPR/DSAR: 법적 요청을 위해 플레이어의 개인 데이터를 업로드/삭제하기위한 종점입니다.
mTLS 및 HSTS는 기본적으로 생산 환경에서 활성화됩니다.

15) 성능 및 할당량

• RPS: 50 (버스트 100)
• 동시 웹 후크: 10

• RPS 예측/볼륨을 지정하여 계정 관리자를 통해 계획 업그레이드를 요청하십시오.

16) 변경 및 릴리스 관리

창 변경: 예약 된 작업-일정에 따라 알림 5 일 이상 영업일.
버전 마이그레이션: 전환 기간 동안 이중 쓰기/이중 읽기.
CI 계약 테스트: JSON 스키마, 필요한 필드, 안정적인 '오류 _ 코드'.
카나리아: 새로운 기능에 대한 트래픽의 점진적인 포함.

17) 통합 인증 (체크리스트)

• 입찰/지불 등록/무효
• 모든 쓰기 끝점에 대한 이념성
• 수정 429/5xx + 백오프 처리
• 웹후크 시그니처 검증, X-GH-Event-ID 중복 제거
• 일련의 이벤트 후 균형 조정 (승리/손실)
• 조정 보고서는 귀하의 데이터에 동의합니다

• 웹훅 퇴각이 구현됩니다
• 클라이언트 타임 아웃
• 종속성에 대한 회로 차단기

• 비밀 관리자에 비밀 보관
• 통나무의 PII 판
• RG/AML 플래그는 실시간으로 고려됩니다

18) 자주 사용되는 시나리오

18. dempotency를 사용한 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 → 백오프 복고풍.
2. 복구 후-동일한 'X-GH-Event-ID' → 복제본을 무시해야합니다.

18. 3 공급자의 부분 저하

503을 환불합니다. 백오프로 반복하십시오.
성능 저하가 길면 공급자의 표시를 중지하고 경사합니다. 스마트 라우팅 (계약에있는 경우).

19) DevEx 및 지원

포털: 키, 사용량, 웹 후크, 배송 로그, SLO 대시 보드, 수출 보고서.
웹 후크 재생: 날짜 범위/ID 별 재배송.
사건: SEV-1에서 티켓의 자동 생성, 전쟁 실, 사후에 48 시간.
통신: # 파트너 상태 채널/메일 온 콜 24 × 7 (엔터프라이즈).

20) 온 보딩 계획 (2-4 주)

1. 1 주차: 주요 발행, 샌드 박스 연결, 기본 시나리오 (베팅/지불/지갑).
2. 2 주차: 웹 후크 및 화해, RG/KYC 플래그, 로드 테스트, 429/5xx 동작.
3. 3 주차: 보고 (조정, 업로드), 보안 (서명, 비밀), 계약 테스트.
4. 4 주차: 인증, 판매, 모니터링, 접촉 매트릭스에 카나리아 포함.

21) 미니 -FAQ

gRPC를 가질 수 있습니까?
예, 요청시; HTP 오류 코드 매핑은 사양에 제공됩니다.

복고풍 데이터를 얻는 방법?
'조정' 보고서 (날짜/날짜) 를 통해 S3/SFTP를 업로드하십시오.

한계를 어떻게 해제합니까?
예측 RPS/경쟁력을 나타내는 포털/계정 관리자를 통해.

균형의 진실의 근원으로 간주되는 것은 무엇입니까?
GambleHub 지갑 거래 로그 + 일일 조정.

합계

GambleHub와의 통합은 안정적인 API 및 체계, 서명 된 웹 후크, demempotency 및 배상, 투명한 한계 및보고, 보안 및 규정 준수 요구 사항과 같은 명확한 계약을 기반으로합니다. 이 안내서 및 인증 체크리스트를 따르면 신속하게 시장에 출시되어 안정적인 현금 흐름과 불일치없이 일관된 보고서를 제공합니다.