營運商 API 實作說明
單一錢包模式下,營運商需要實作統一的 API 供遊戲商呼叫,以實現餘額查詢、下注結算和交易處理。
架構概述
在單一錢包模式中,會員的餘額由營運商端管理,遊戲商作為遊戲服務提供者,需要向營運商查詢餘額和處理交易。
API 實作說明
營運商需要在自己的伺服器上提供一組 callBack URL，營運商需根據請求中的 action 參數來決定執行的操作：
| Action | 說明 | 優先級 |
|---|---|---|
| balance | 即時查詢會員可用餘額 | 必須 |
| betNSettle | 處理遊戲下注和結算 | 必須 |
| rollback | 回滾異常交易 | 必須 |
| retryBet | 下注重試機制 | 必須 |
統一端點
營運商只需提供一組 callBack URL，例如：
POST https://operator.example.com/api/wallet
遊戲商會在請求的解密後參數中帶上 action 欄位來區分不同操作
實作要求
1. 安全性要求
- ✅ 加密傳輸: 所有請求內容使用 AES-256-GCM 加密，響應使用明文 JSON 格式
- ✅ HTTPS: 生產環境必須使用 HTTPS
加密說明
算法: AES-256-GCM
- 密鑰長度：256 位（32 字節）
- IV 長度：96 位（12 字節）
- 認證標籤長度：128 位（16 字節）
cipherText 格式:
ivBase64(16字元) + authTagBase64(24字元) + encryptedDataBase64
2. 響應格式要求
響應格式說明
所有營運商 API 的響應格式統一為明文 JSON，固定格式如下：
{
status: '0000',
errText: '',
balance: 12345.67,
responseTime: '2024-12-11T01:23:38.271Z'
}
| 欄位 | 類型 | 說明 |
|---|---|---|
| status | string | 狀態碼，詳見各 API 說明 |
| errText | string | 錯誤訊息，成功時為空字串 |
| balance | number | 操作後的會員餘額 |
| responseTime | string | 回應時間 |
3. 效能要求
- ⚡ 回應時間: 平均回應時間應 < 3000ms，超過則是為超時
常見問題
Q1: 如何區分不同的操作?
A: 遊戲商會在請求的解密後參數中帶上 action 欄位 (balance、betNSettle、rollback、retryBet)，營運商根據此欄位路由到對應的處理邏輯。
Q2: Token 有效期應該設定多久?
A: 建議 24 小時。會員關閉遊戲或登出後,應該使 Token 失效。
Q3: 餘額精度應該設定多少位小數?
A: 支援到小數後 4 位 (0.0001)，至少要支援到小數後 2 位 (0.01)。
Q4: 交易多久後會是為超時?
A: 3 秒
Q5: 那些交易會進入下注重試流程?
A: 道具與平台卡之交易不會觸發取消下注，會透過「下注重試」API 持續重試
Q6: callBack Url 可以調整嗎?
A: 可以，交易回傳的 calBack Url 我方並未指定任何格式，具體可透過後台設定與驗證
技術支援
如在實作過程中遇到問題,請聯繫 TG 技術支援團隊