GambleHubインテグレーションガイド

1）概要と相互作用モデル

• APIプロバイダー：GambleHub API（ウォレット、ボーナス、レポート）を呼び出します。
• 外部プロバイダ：webhooks/endpoints（残高、トランザクション、KYC）を呼び出します。

1.Edge/API （REST/gRPC、 Webhooks）

2.イベント（イベントバス：ベット/ペイアウト/ウォレット/ICC）

3.レポート（API+S3/SFTPエクスポート）

4.オペレーション（インシデント、SLO、 SLAクレジット）

2）環境、ドメイン、IP

契約SLAは契約で固定されています。IPアップデートは事前に公開されています。Allow Allowlist。

3）認証と認証

私たちは3つのメカニズムをサポートしています（契約の下で必要なものを選択してください）

OAuth2 Client Credentials： server-to-server （'scope'： 'wallet： read'、 'wallet： write'、 'bet： write'、 'report： read'）。
JWT （issuer=GambleHub）： RS256署名、JWKSエンドポイント内のキー。
mTLS：入力レベルでの相互TLS認証（コンプライアンス要求時）。

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日。
Webhookは「X-GH-Event-Version： 1」というタイトルでバージョン管理されています。

5）制限、クォータ、idempotency

• 'X-RateLimit-Limit'、 'X-RateLimit-Remaining'、 'X-RateLimit-Reset'。
• 429は'Retry-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"}]
}

Retriable： 5xx/ 503/504/429 （'Retry-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） Webhooks（パートナーへのGambleHub）

• 'X-GH-Event'：'プレイヤー。'session'を作成しました。ベットを始めた。'betを配置しました。落ち着いたウォレット。'kycを変更しました。'rgを更新しました。フラグ付き"
• '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だけです。さもなければ-retrai：指数関数的なバックオフ（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.デポジット（PSP→ウォレット。クレジット）

2.ベット（hold/authorizeの直接デビット）

3.決済（リリースホールド；'win'/'lose'/'void'）

4.出金（ウォレット。デビット→PSP）

ホールドバランスとマルチウォレット（リアル/ボーナス）がサポートされています。

11）サンドボックスとテストシナリオ

テストプレーヤー：'p_sbx _'、通貨'EUR 'USD' CAD'。
ゲームプロバイダがエミュレート：勝利/失う/無効、割引、遅延。
KYCサンドボックス：パスポートテンプレートの'検証'失敗'レビュー'応答。
PSPサンドボックス：'authorized' captured 'declined' reversed'。

• バランスシートStavka→vyplata→sverka
• プルバック/ボイドラウンド
• 再入札時のIdempotency
• リトレイとその後の重複除外によるWebhookの障害
• 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、プロバイダ、地理/通貨の内訳。
エクスポート：署名付きマニフェストとファイルハッシュ（SHA256）でS3/SFTPします。
レポートのタイムゾーン：UTC（契約で特に指定されていない限り）。

13）観察可能性およびSLO

SLI： API ≥ 99の成功。95％ （28d）、重要な方法のp95レイテンシ、webhook配信の成功。
誤った予算でのバーンアラート（高速/遅い）。
トレース相関：レスポンス/ログの'trace_id'、トレースへのドリルダウン。
ステータスページ：エッジ、ウォレット、ベット、Webhooks、 PSP、 KYCコンポーネント。

14）安全性とコンプライアンス

PIIの最小化；PAN/secretsはログ/webhookで禁止されています。
秘密管理およびキーの回転。
RG（責任あるギャンブル）：自己排除/制限フラグはベット/支払いを自動的に拒否する必要があります。
AML/KYC： 'kyc'イベント。'、'amlを更新しました。alert'はサブスクリプションで利用できます。あなたのシステムまたは私達のモジュールを通して決定をして下さい。
GDPR/DSAR：法的要求のためにプレイヤーの個人データをアップロード/削除するためのエンドポイント。
mTLSとHSTSは、デフォルトで本番環境で有効になっています。

15）性能およびクォータ

• RPS： 50（バースト100）
• 同時Webhook： 10
• ボディサイズ：≤ 256 KB（ゲームイベント）、≤ 64 KB（ウォレット）

RPS予測/ボリュームを指定して、アカウントマネージャを通じてプランのアップグレードを要求します。

16）変更およびリリース管理

変更ウィンドウ：スケジュールされた作業-スケジュール、通知≥ 5営業日。
バージョンの移行：移行期間中にデュアルライト/デュアルリード。
CI契約テスト：JSONスキーマ、必須フィールド、安定した'error_code'。
カナリア：新機能のトラフィックを徐々に含める。

17）統合認証（チェックリスト）

• 入札/支払登録/無効
• すべての書き込みエンドポイントに対するIdempotency
• 正しい429/5xx+バックオフ処理
• Webhook署名検証、X-GH-Event-Id重複除外
• 一連のイベント後のバランス調整（勝敗）
• 和解レポートはあなたのデータに同意します

• Webhookのリトリートが実装されている
• クライアントのタイムアウト≤ 10c、合計試行≤ 30c
• 依存関係の回路遮断器

• シークレットマネージャーに秘密を保存する
• ログのPIIエディション
• RG/AMLフラグはリアルタイムで考慮されます

18）頻繁に使用されるシナリオ

18.1 idempotencyによるレート登録

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失敗したWebhookに続いて成功

1.あなたのサーバーは利用できません→5xx→バックオフレトロ。
2.リカバリ後-同じ'X-GH-Event-Id'→を取ると重複を無視する義務があります。

18.3プロバイダの部分的な劣化

私達は503を払い戻します；バックオフで繰り返す。
長い劣化で-プロバイダのマーキングを停止し、税込。スマートルーティング（契約の場合）。

19） DevExおよびサポート

ポータル：キー、使用法、webhook、配達記録、SLOのダッシュボード、輸出レポート。
Webhooksリプレイ：日付範囲/IDによる再納品。
インシデント：チケットの自動作成、戦争部屋、死後≤ SEV-1 48時間。
コミュニケーション：#partners-status channel/mail on-call 24 × 7 （Enterprise）。

20）搭乗プラン（2〜4週間）

1.週1：キー発行、サンドボックス接続、ベースシナリオ（ベット/ペイ/財布）。
2.Week 2： Webhooks and Reconcilations、 RG/KYC Flags、 Load Tests、 429/5xx Behavior。
3.第3週：報告（和解、アップロード）、セキュリティ（署名、秘密）、契約テスト。
4.第4週：販売、モニタリング、コンタクトマトリックスにおける認証、カナリア含有。

21） ミニFAQ

gRPCは使えますか？
はい、要求あり次第；HTTPエラーコードマッピングは仕様書に記載されています。

レトロデータを取得する方法？
「和解」レポート（日付から/日付まで）またはS3/SFTPをアップロードします。

制限を解除するにはどうすればよいですか？
予測RPS/競争力を示すポータル/アカウントマネージャーを通じて。

平衡の真理の源と考えられるものは何ですか？
GambleHubウォレットトランザクションログ+毎日の和解。

合計

GambleHubとの統合は、安定したAPIとスキーム、署名されたwebhook、 idempotencyとretray、透明な制限とレポート、セキュリティとコンプライアンスの要件など、明確な契約に基づいて構築されています。このガイドと認証チェックリストに従うことで、あなたはすぐに市場に到達し、信頼性の高いキャッシュフローと矛盾なく一貫したレポートを提供します。