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，等效性和转发，透明的限制和报告以及安全和合规性要求。按照本指南和认证单，您将通过提供可靠的现金流量和一致的报表而迅速进入计划。