AG 代理會員 API v1

此 API 提供代理系統建立會員帳號。v1 固定使用 hash 欄位簽章，不接受 chkstr。

簽章公式：hash = md5(method + ag_no + player_id + utime + common_ag.key)。MD5 請使用小寫 hex。common_ag.key 是代理自己的密鑰，不可傳到前端玩家端。

1. 新增會員

POST /api/ag/v1/users

Request body（JSON）

欄位	型別	說明
`ag_no`	string	代理編號。須存在於 `common_ag`，且 `is_enabled = 1`，並已設定 `key`。
`player_id`	string	代理端玩家編號，只允許英數與底線。不可自行加代理前綴，例如傳 `dsz001`，不要傳 `dssz_dsz001`。
`utime`	integer	呼叫方 Unix time 秒數。與伺服器時間誤差須 ≤ 15 秒。
`hash`	string	`md5('create_player' + ag_no + player_id + utime + common_ag.key)`。

PHP 範例

$ag_no = 'dssz';
$player_id = 'dsz001';
$utime = time();
$ag_key = 'AG_KEY_FROM_COMMON_AG';
$method = 'create_player';
$hash = md5($method . $ag_no . $player_id . $utime . $ag_key);

$data = array(
  'ag_no' => $ag_no,
  'player_id' => $player_id,
  'utime' => $utime,
  'hash' => $hash
);

curl 範例

curl -X POST https://mj.168a.com.tw/api/ag/v1/users \
  -H "Content-Type: application/json" \
  -d '{"ag_no":"dssz","player_id":"dsz001","utime":1700000000,"hash":"yyyyyyy"}'

Response（成功 200）

{
  "ok": true,
  "version": "v1",
  "ag_no": "dssz",
  "player_id": "dsz001",
  "user_id": "dssz_dsz001"
}

2. 查詢餘額

POST /api/ag/v1/balance

代理端用同一套 v1 簽章規則查詢自己名下會員目前點數。

Request body（JSON）

欄位	型別	說明
`ag_no`	string	代理編號。
`player_id`	string	代理端玩家編號，例如 `dsz001`。server 會查 `dssz_dsz001`。
`utime`	integer	呼叫方 Unix time 秒數。與伺服器時間誤差須 ≤ 15 秒。
`hash`	string	`md5('balance' + ag_no + player_id + utime + common_ag.key)`。

Response（成功 200）

{
  "ok": true,
  "version": "v1",
  "ag_no": "dssz",
  "player_id": "dsz001",
  "user_id": "dssz_dsz001",
  "npoint": "1000.00"
}

3. 上點

POST /api/ag/v1/deposit

Request body（JSON）

欄位	型別	說明
`ag_no`	string	代理編號。
`player_id`	string	代理端玩家編號，例如 `dsz001`。server 會更新 `dssz_dsz001`。
`amount`	number	上點金額，必須大於 0。v1 直接增加 `common_user.npoint`。
`utime`	integer	呼叫方 Unix time 秒數。與伺服器時間誤差須 ≤ 15 秒。
`hash`	string	`md5('deposit' + ag_no + player_id + utime + common_ag.key)`。注意：v1 的 `amount` 不列入 hash。

PHP 範例

$ag_no = 'dssz';
$player_id = 'dsz001';
$amount = 123.00;
$utime = time();
$ag_key = 'AG_KEY_FROM_COMMON_AG';
$method = 'deposit';
$hash = md5($method . $ag_no . $player_id . $utime . $ag_key);

$data = array(
  'ag_no' => $ag_no,
  'player_id' => $player_id,
  'amount' => $amount,
  'utime' => $utime,
  'hash' => $hash
);

Response（成功 200）

{
  "ok": true,
  "version": "v1",
  "ag_no": "dssz",
  "player_id": "dsz001",
  "user_id": "dssz_dsz001",
  "npoint": "1123.00"
}

4. 下點

POST /api/ag/v1/withdraw

Request body（JSON）

欄位	型別	說明
`ag_no`	string	代理編號。
`player_id`	string	代理端玩家編號，例如 `dsz001`。server 會更新 `dssz_dsz001`。
`amount`	number	下點金額，必須大於 0。若會員點數不足，不會扣點並回錯誤。
`utime`	integer	呼叫方 Unix time 秒數。與伺服器時間誤差須 ≤ 15 秒。
`hash`	string	`md5('withdraw' + ag_no + player_id + utime + common_ag.key)`。注意：v1 的 `amount` 不列入 hash。

PHP 範例

$ag_no = 'dssz';
$player_id = 'dsz001';
$amount = 12.00;
$utime = time();
$ag_key = 'AG_KEY_FROM_COMMON_AG';
$method = 'withdraw';
$hash = md5($method . $ag_no . $player_id . $utime . $ag_key);

$data = array(
  'ag_no' => $ag_no,
  'player_id' => $player_id,
  'amount' => $amount,
  'utime' => $utime,
  'hash' => $hash
);

Response（成功 200）

{
  "ok": true,
  "version": "v1",
  "ag_no": "dssz",
  "player_id": "dsz001",
  "user_id": "dssz_dsz001",
  "npoint": "1111.00"
}

Response（點數不足 409）

{
  "ok": false,
  "error": "point_not_enough",
  "ag_no": "dssz",
  "player_id": "dsz001",
  "user_id": "dssz_dsz001",
  "npoint": "5.00"
}

5. 遊戲列表

POST /api/ag/v1/gamelist

Request body（JSON）

欄位	型別	說明
`ag_no`	string	代理編號。
`utime`	integer	呼叫方 Unix time 秒數。與伺服器時間誤差須 ≤ 15 秒。
`hash`	string	`md5('gamelist' + ag_no + utime + common_ag.key)`。此 API 沒有 `player_id`。

PHP 範例

$ag_no = 'dssz';
$utime = time();
$ag_key = 'AG_KEY_FROM_COMMON_AG';
$method = 'gamelist';
$hash = md5($method . $ag_no . $utime . $ag_key);

$data = array(
  'ag_no' => $ag_no,
  'utime' => $utime,
  'hash' => $hash
);

Response（成功 200）

{
  "ok": true,
  "version": "v1",
  "ag_no": "dssz",
  "games": [
    {
      "id": 1,
      "game_id": "0001",
      "game_type": "東東局 50底/20台",
      "base": 50,
      "tai": 20
    }
  ]
}

Server 會讀取 common_ag.game_list，再關聯 lob_room，回傳符合的 lob_room 全部欄位。game_list 可使用 JSON 陣列或逗號分隔，例如 ["0001","0002"] 或 0001,0002。

6. 開啟遊戲

POST /api/ag/v1/launch

Request body（JSON）

欄位	型別	說明
`ag_no`	string	代理編號。
`player_id`	string	代理端玩家編號，例如 `dsz001`。server 會使用 `dssz_dsz001`。
`game_id`	string	遊戲編號，例如 `0004`。必須在 `common_ag.game_list` 內。
`utime`	integer	呼叫方 Unix time 秒數。與伺服器時間誤差須 ≤ 15 秒。
`hash`	string	`md5('launch' + ag_no + player_id + game_id + utime + common_ag.key)`。

PHP 範例

$ag_no = 'dssz';
$player_id = 'dsz001';
$game_id = '0004';
$utime = time();
$ag_key = 'AG_KEY_FROM_COMMON_AG';
$method = 'launch';
$hash = md5($method . $ag_no . $player_id . $game_id . $utime . $ag_key);

$data = array(
  'ag_no' => $ag_no,
  'player_id' => $player_id,
  'game_id' => $game_id,
  'utime' => $utime,
  'hash' => $hash
);

Response（成功 200）

{
  "ok": true,
  "version": "v1",
  "ag_no": "dssz",
  "player_id": "dsz001",
  "user_id": "dssz_dsz001",
  "game_id": "0004",
  "npoint": 5000,
  "miniPoint": 1000,
  "token": "xxxxxxxx",
  "url": "https://mj.168a.com.tw?token=xxxxxxxx&user_id=yyyyyyyy&t=1700000000000",
  "game": {
    "game_id": "0004",
    "game_type": "金幣區"
  }
}

開啟遊戲前會檢查會員目前點數必須大於等於 lob_room.mini_point。不足時不簽發 token，也不回傳遊戲 URL。

Response（最低進場金額不足 403）

{
  "ok": false,
  "error": "min_point_not_enough",
  "message": "最低進場金額不足",
  "ag_no": "dssz",
  "player_id": "dsz001",
  "user_id": "dssz_dsz001",
  "game_id": "0004",
  "npoint": 300,
  "miniPoint": 1000
}

7. 建立規則

common_user 欄位	寫入值
`ag_no`	請求的 `ag_no`
`user_id`	`ag_no + '_' + player_id`
`pass`	`md5(server_now_unix_time)`
`is_enabled`	`1`
`is_ai`	`0`
`user_nick`	從 `common_user_nick` 抽未使用暱稱，transaction + `FOR UPDATE`
`npoint/gold`	API 不指定，走 DB 預設值

8. 錯誤碼

HTTP	error	原因
400	`amount_required`	上點時未傳 `amount`。
400	`hash_required`	未傳 `hash`。v1 不接受 `chkstr` 代替。
400	`invalid_ag_no`	`ag_no` 含非法字元。
400	`invalid_amount`	`amount` 非數字或小於等於 0。
400	`invalid_game_id`	`game_id` 含非法字元。
400	`invalid_player_id`	`player_id` 含非法字元，或已自行帶代理前綴。
401	`time_drift`	`utime` 與 server Unix time 誤差超過 15 秒。
401	`agency_not_found`	代理不存在、停用，或未設定 key。
401	`bad_signature`	`hash` 驗證不符。
404	`account_not_found`	查詢餘額時，代理名下找不到該會員。
403	`game_not_allowed`	開啟遊戲時，該 `game_id` 不在代理的 `game_list`。
403	`min_point_not_enough`	開啟遊戲時，會員點數低於 `lob_room.mini_point`。
404	`game_not_found`	開啟遊戲時，該遊戲不存在或未啟用。
409	`point_not_enough`	下點時會員點數不足，不會扣點。
409	`account_exists`	`ag_no_player_id` 已存在。
500	`nick_unavailable`	暱稱池沒有可用資料，會員不會建立。
500	`create_user_failed`	DB 寫入失敗，transaction 會 rollback。
500	`deposit_failed`	上點更新失敗，transaction 會 rollback。
500	`withdraw_failed`	下點更新失敗，transaction 會 rollback。
500	`gamelist_failed`	遊戲列表查詢失敗。
500	`launch_failed`	開啟遊戲 URL 建立失敗。

9. 線上測試

本機計算 hash 並呼叫 AG API

貼上代理密鑰後，本頁只在瀏覽器內計算 hash；method 是各 API 固定簽章字串，不需要送到 server。