ThreeKingChess 商戶串接 API (1.0.0)

1. 建立玩家：首次以 POST /v1/player/login 帶入商戶端玩家 ID（player_id），平台即建立該玩家與錢包。
2. 入金：POST /v1/wallet/deposit 將額度搬進玩家錢包（每筆給唯一 transaction_id）。
3. 開遊戲：POST /v1/game/launch-url 取得帶 JWT 的 launch_url，以 iframe 嵌入或整頁導向讓玩家進場。
4. 查詢：GET /v1/player/balance 查餘額、POST /v1/game/bet-records 拉注單。
5. 出金 / 踢出：POST /v1/wallet/withdraw 出金、POST /v1/player/kick 踢出在線玩家。

每個請求皆須帶三個標頭：

• 簽章字串 = 原始 request body 字串 直接接上 timestamp 字串（GET 無 body 時 body 為空字串）。
• api_secret 只存在商戶後端，絕不可進前端、瀏覽器或 URL。
• IP 白名單：商戶可設定允許呼叫的來源 IP；未列入者一律 403。
• 重放防護：同一個 X-Signature 在 600 秒內只能用一次。金流端點（deposit/withdraw） 以 transaction_id 自身做冪等，合法重送同簽章不會被誤擋。

⚠️ 最常見的簽章錯誤：簽章用的 body 必須與實際送出的 HTTP body 位元組完全一致。 請先把 body 序列化成字串，同一份字串既拿去簽章也拿去送（切勿序列化兩次，兩次結果可能不同）。

🔧 線上簽章驗證工具：signature-tool.html —— 貼上 secret / body / timestamp， 在瀏覽器本機算出 X-Signature 並與你後端產出的比對，快速定位不符問題（secret 不會送出）。

簽章範例

Node.js

import crypto from 'node:crypto';
const sign = (body, ts, secret) =>
  crypto.createHmac('sha256', secret).update(body + ts).digest('hex');

const body = JSON.stringify({ player_id: 'p001', amount: 10000, transaction_id: 'dep_1' });
const ts = Math.floor(Date.now() / 1000).toString();
const headers = {
  'X-API-Key': API_KEY,
  'X-Timestamp': ts,
  'X-Signature': sign(body, ts, API_SECRET),
  'Content-Type': 'application/json',
};
// 送出時用同一個 body 變數：fetch(url, { method: 'POST', headers, body })

PHP

<?php
function sign(string $body, string $ts, string $secret): string {
    return hash_hmac('sha256', $body . $ts, $secret);
}
$body = json_encode(['player_id' => 'p001', 'amount' => 10000, 'transaction_id' => 'dep_1']);
$ts   = (string) time();
$sig  = sign($body, $ts, $apiSecret);

$ch = curl_init("$base/v1/wallet/deposit");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "X-API-Key: $apiKey",
        "X-Timestamp: $ts",
        "X-Signature: $sig",
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => $body,   // 與簽章同一份字串
    CURLOPT_RETURNTRANSFER => true,
]);
$resp = curl_exec($ch);

Golang

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "time"
)

func sign(body, ts, secret string) string {
    m := hmac.New(sha256.New, []byte(secret))
    m.Write([]byte(body + ts))
    return hex.EncodeToString(m.Sum(nil))
}

body := `{"player_id":"p001","amount":10000,"transaction_id":"dep_1"}`
ts := fmt.Sprintf("%d", time.Now().Unix())
sig := sign(body, ts, apiSecret)
// 設 header：X-API-Key / X-Timestamp=ts / X-Signature=sig；送出時用同一份 body 位元組

bash + openssl

sign() { printf '%s%s' "$1" "$2" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //'; }
ts=$(date +%s); sig=$(sign "$BODY" "$ts")
curl -X POST "$BASE/v1/wallet/deposit" \
  -H "X-API-Key: $KEY" -H "X-Timestamp: $ts" -H "X-Signature: $sig" \
  -H "Content-Type: application/json" -d "$BODY"

錯誤回應格式：{ "success": false, "code": <http_status>, "message": "<說明>" }

玩家建立與餘額查詢。

入金 / 出金（轉帳錢包）。

開遊戲、拉注單。

統計報表（日 / 週 / 月 / 即時）。

健康檢查。