GambleHub集成指南

1）瀏覽和交互模型

• API提供商：您調用GambleHub API（錢包、獎金、報告）。
• 外部供應商：我們調用您的webhook/enpoints（資產負債表、交易、KYC）。

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

2.事件（活動巴士：費率/付款/錢包/CUS）

3.報告（API+導出S3/SFTP）

4.運營（事件，SLO，SLA貸款）

2）環境、域和IP

合同SLA記錄在合同中。IP更新會提前發布。允許Allowlist。

3）認證和授權

• OAuth2 Client Credentials：服務器對服務器（'scope'--"wallet： read", 'wallet： write", 'bet： write", 'report： read"）。
• JWT（issuer=GambleHub）：標題，j RS256 WKS端點中的密鑰。
• mTLS：相互的TLS身份驗證,在無損級別上（應合規要求）。

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

每次呼叫都會檢查Scopes。對於高風險操作（付款），使用步進式：單獨的scope，以及可選的IP/ASN綁定。

4）轉化與兼容性

路徑：'/v1/……'，'/v2/……'（主要版本向後不兼容）。
次要和擴展更改-通過電路擴展（新的可選字段）。
撤銷-在90天內通知。
Webhooks的標題是「X-GH-Ivent-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）Webhooks（從GambleHub到合作夥伴）

• `X-GH-Event`: `player.created|session.started|bet.placed|bet.settled|wallet.changed|kyc.updated|rg.flagged`
• 「X-GH-Ivent-Id」：獨特的UUID
• `X-GH-Signature`: `sha256=`
• 「X-GH-Retry」：嘗試No
• `X-GH-Event-Version`: `1`

示例'bet。settled`:

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 s，3 s，10 s，30 s，2 m，10 m，30 m；最多24小時）。要重復數據消除,請使用「X-GH-Invent-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)

支持固定資產負債表和多錢包（真實/獎金）。

11）沙盒和測試場景

測試玩家：「p_sbx_」，貨幣為「EUR」 USD 「CAD」。
遊戲提供商模擬：win/lose/void,折扣,延遲。
KYC sandbox：對護照模板的「驗證」失敗的「評論」的回應。

PSP sandbox: статусы `authorized|captured|declined|reversed`.

• Stavka→vyplata→sverka資產負債表
• 回滾/void回合
• 重復投註時的Idempotency
• 通過轉發和隨後的重復數據消除來運行webhook
• 429和正確的「Retry-After」
• 5xx在客戶端具有指數後端

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 （SHA 256）。
報告時間：UTC（除非合同另有規定）。

13）可觀察性和SLO

SLI： API ≥ 99的成功。95% （28d）, p95 latency用於關鍵技術,成功交付webhook。
Burn-alerts（快速/慢）,預算錯誤。
跟蹤相關性：答案/邏輯中的「trace_id」，drilldown到軌道。
狀態頁面：Edge、Wallet、Bets、Webhooks、PSP、KYC組件。

14）安全和合規性

PII最小化；禁用PAN/博客/網絡中的秘密。
秘密管理和密鑰輪換。
RG （Responsible Gambling）：自我排序/限制標誌應導致自動拒絕利率/付款。
AML/KYC：kyc事件。updated`, `aml.警告"可通過訂閱獲得；在您的系統中或通過我們的模塊做出決定。
GDPR/DSAR：根據法律要求卸載/刪除玩家個人數據的終端。
mTLS和HSTS默認包含在prod環境中。

15）生產力和配額

• RPS: 50 (burst 100)
• Concurrent webhooks: 10
• 體型：≤ 256 KB（遊戲賽事）,≤ 64 KB（錢包）

通過帳戶經理請求計劃升級,指定RPS/卷預測。

16）變更和發行管理

Change windows：計劃工作-按計劃,通知≥ 5個工作日。
Version migration：過渡時期的雙寫作/雙讀。
CI中的合同測試：JSON電路，強制字段，穩定的「error_code」。
金絲雀：逐步納入流量以適應新的景象。

17）集成認證（檢查列表）

• 註冊費率/付款/void
• 所有write-enpoint的冪等
• 正確處理429/5xx+backoff
• Webhook簽名驗證、「X-GH-Invent-Id」重復數據消除'
• 在一系列事件之後核對資產負債表（win/lose）
• reconciliation報告與您的數據趨同

• webhook retrai實現
• 客戶Taymauts ≤ 10 c，一般嘗試≤ 30 c
• 成癮巡回賽決勝局

• 秘密管理器中的秘密
• Logs中的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.5 xx →後端→服務器不可用。
2.恢復後-接受相同的「X-GH-Ivent-Id」 →必須忽略重復。

18.3部分供應商降解

我們將返回503；與backoff重復。
長期降解-提供商的停止標記和智能路由插件（如果合同中有）。

19） DevEx和支持

門戶：keys, usage, webhooks,交付日誌,SLO dashboards,導出報告。
Webhooks replay： 按日期/ID範圍重新交付。
事件：自動創建tiket，戰爭室，驗屍室≤ SEV-1 48小時。
通訊：#partners-status頻道/呼叫郵件24 × 7（企業）。

20）劃船計劃（2-4周）

1.第1周：發行鑰匙，sandbox連接，基本方案（投註/付款/錢包）。
2.第二周：webhooks和對賬，RG/KYC標誌，負載測試，429/5xx行為。
3.第3周：報告（重組，卸載），安全（簽名，保密），合同測試。
4.第4周：認證，金絲雀包括在銷售中，監視，接觸矩陣。

21） Mini-FAQ

gRPC可以嗎？
是的，應要求；規格中提供了對HTTP錯誤代碼的映射。

如何獲取復古數據?

通過「reconciliation」報告（「from/to」日期）或卸載S3/SFTP。

如何提高限制？
通過門戶/帳戶管理器指示預測的RPS/競爭力。

什麼是平衡真理的來源？
交易錢包雜誌GambleHub+每日對賬（reconciliation）。

底線

與GambleHub的集成建立在一個明確的合同基礎上：穩定的API和電路，簽名的webhooks，等效性和轉發，透明的限制和報告以及安全和合規性要求。按照本指南和認證單，您將通過提供可靠的現金流量和一致的報表而迅速進入計劃。