玩家

啟動遊戲、登出、查詢與更新玩家。玩家第一次 launch（或第一次轉入）時自動建立，不需要另外註冊。

相關指南：閱讀這部分的串接指南

TIP

範例使用〈認證與簽章〉的範例金鑰與時間戳計算簽章，可直接用〈簽章除錯器〉驗算。

啟動遊戲

POST /api/tenant/v1/player/launch

取得玩家進入遊戲的一次性網址（60 秒內有效、只能開啟一次）。玩家不存在時自動建立。

單一登入：呼叫 launch 時，這位玩家已開啟的 session 立即失效並被踢出（原因 SESSION_REPLACED）；玩家開啟網址時會再做一次。所以同時發出多個網址時，以最後開啟的那一個為準，先開啟的 session 會被踢出。
取得網址後，把玩家的瀏覽器導向（或以 iframe 開啟）這個網址；過期或已使用的網址會顯示「連結已失效」（HTTP 410）。
nickname、currency 只在建立玩家時使用；之後要改暱稱請用 POST /player/update，幣別建立後不能變更。
currency 要是租戶在 Console「限紅方案 → 幣別」開啟的幣別（不帶＝主要幣別），否則回 CURRENCY_NOT_ENABLED。
limitProfileId 會儲存為這位玩家的限紅方案（與 POST /player/update 相同），之後的 launch 不帶就沿用。
被鎖定（locked）的玩家回 PLAYER_LOCKED；no_bet 的玩家可以進入但不能下注。

請求本文（application/json）

欄位	型別	必填	說明
`username`	string	是	玩家帳號，1–32 個字元（英數字與 `_ . @ -`）；不分大小寫（`Alice` 與 `alice` 是同一位玩家）。格式：`^[A-Za-z0-9_.@-]{1,32}$`
`nickname`	string	否	暱稱（選填）。只在建立玩家時使用。
`currency`	string	否	幣別（選填），只在建立玩家時使用；預設為你的租戶幣別。格式：`^[A-Za-z]{3,5}$`
`lang`	string	否	遊戲語系（選填）；預設為你在 Console 設定的第一個語系，未設定時為 `CHT`。可能的值：`CHT`、`CHS`、`ENG`、`JPN`、`KOR`、`THAI`、`VIET`、`HIND`、`PHP`
`device`	string	否	`mobile` 開啟手機版，其他值一律為桌機版 `pc`。可能的值：`pc`、`mobile` 預設：`pc`
`table`	string	否	直接進入這張桌（選填）；不帶時進入大廳。桌必須是你已啟用的桌。長度：1–…
`variant`	string	否	偏好的百家樂玩法（選填，`classic`／`nocomm`）。目前版本只保存，玩家仍在桌內自行選擇。
`lobbyUrl`	string (uri)	否	你的網站網址（選填，http 或 https）。目前版本的「回到網站」按鈕使用 Console「品牌與登入 → 返回大廳網址」的設定；這個參數會保存，供之後的版本逐次覆寫。格式：`^https?://`
`limitProfileId`	integer \| null	否	限紅方案 ID：你在 Console「限紅方案」建立的方案，或平台範本；幣別必須與玩家相同，否則回 `INVALID_PARAMETER`。`null` 改回預設。限紅方案依遊戲區分，只套用在同一種遊戲的桌，其他遊戲的桌使用預設方案。範圍：1–…

請求範例

http

POST /api/tenant/v1/player/launch HTTP/1.1
Host: elite.ewin888.com
X-Api-Key: ek_s_1a_XXXXXXXXXXXXXXXX
X-Timestamp: 1790218800
X-Nonce: ex2a3b659ce54a7c197e7bd7
X-Signature: 984cf8a6c0afeb4b7baf4bb7c800ced833ef6265d8c8e8234d89375c4377e4bf
Content-Type: application/json

{"username":"alice","lang":"ENG","device":"mobile","table":"S01"}

回應的 data

欄位	型別	說明
`url`	string (uri)	一次性遊戲網址（`https://<主機>/Launch?t=…`），60 秒內有效、只能開啟一次。
`expiresIn`	integer	網址有效秒數。固定為：`60`

回應範例

json

{
  "ok": true,
  "data": {
    "url": "https://elite.ewin888.com/Launch?t=k1.eyJ0aWQiOjQ2fQ.3xAmPlE-TiCkEt",
    "expiresIn": 60
  }
}

錯誤碼

錯誤碼	HTTP	意義
`INVALID_PARAMETER`	400	缺少必要欄位，或欄位格式、值不正確；`message` 會指出是哪個欄位。
`INVALID_USERNAME`	400	玩家帳號不符合規則（1–32 個字元，英數字與 `_ . @ -`），或查詢時沒有帶 `username`。
`INVALID_CURRENCY`	400	建立新玩家時指定的幣別代碼不合法（需要 3–5 個英文字母）。
`CURRENCY_NOT_ENABLED`	400	建立新玩家時指定的幣別，租戶還沒開啟（多幣別：Console「限紅方案 → 幣別」）。已存在的玩家不受影響。
`PLAYER_LOCKED`	403	玩家已被鎖定，不能啟動遊戲。
`PLAYER_LIMIT`	403	玩家帳號數已達方案上限（免費展示方案預設 50、沙箱 500）。

所有端點另外都可能回傳共通錯誤（UNAUTHORIZED、IP_NOT_ALLOWED、TENANT_SUSPENDED、RATE_LIMITED、INTERNAL_ERROR…）。

登出玩家

POST /api/tenant/v1/player/logout

讓玩家所有 session 立即失效並踢出遊戲（原因 LOGGED_OUT），並送出 Webhook player.kicked（reason 為 logged_out）。玩家之後要再進入，需要重新 launch。

請求本文（application/json）

欄位	型別	必填	說明
`username`	string	是	玩家帳號，1–32 個字元（英數字與 `_ . @ -`）；不分大小寫（`Alice` 與 `alice` 是同一位玩家）。格式：`^[A-Za-z0-9_.@-]{1,32}$`

請求範例

http

POST /api/tenant/v1/player/logout HTTP/1.1
Host: elite.ewin888.com
X-Api-Key: ek_s_1a_XXXXXXXXXXXXXXXX
X-Timestamp: 1790218800
X-Nonce: ex30c4dc0d6184b121569ed8
X-Signature: 03d4b8a3fae4c5d4198c434b0a7d00651ae514c76c3c92697fabf327265a2313
Content-Type: application/json

{"username":"alice"}

回應的 data

欄位	型別	說明
`kicked`	boolean	一律為 `true`。

回應範例

json

{
  "ok": true,
  "data": {
    "kicked": true
  }
}

錯誤碼

錯誤碼	HTTP	意義
`INVALID_PARAMETER`	400	缺少必要欄位，或欄位格式、值不正確；`message` 會指出是哪個欄位。
`INVALID_USERNAME`	400	玩家帳號不符合規則（1–32 個字元，英數字與 `_ . @ -`），或查詢時沒有帶 `username`。
`PLAYER_NOT_FOUND`	404	這個帳號的玩家不存在。

所有端點另外都可能回傳共通錯誤（UNAUTHORIZED、IP_NOT_ALLOWED、TENANT_SUSPENDED、RATE_LIMITED、INTERNAL_ERROR…）。

查詢玩家

GET /api/tenant/v1/player

玩家資料、狀態、目前餘額與是否在線。

參數

參數	位置	型別	必填	說明
`username`	query	string	是	玩家帳號。格式：`^[A-Za-z0-9_.@-]{1,32}$`

請求範例

http

GET /api/tenant/v1/player?username=alice HTTP/1.1
Host: elite.ewin888.com
X-Api-Key: ek_s_1a_XXXXXXXXXXXXXXXX
X-Timestamp: 1790218800
X-Nonce: ex0f4c27405f79ad431f805c
X-Signature: 01202dea8bd6b3ee60804a309c91cd4a71a2a7089243887bdccb9d43b13896e5

回應的 data

欄位	型別	說明
`username`	string	玩家帳號（保留第一次建立時的大小寫）。
`nickname`	string \| null	暱稱。
`status`	string	`active` 正常；`locked` 鎖定（不能進入遊戲）；`no_bet` 禁止下注（可進入觀看）。可能的值：`active`、`locked`、`no_bet`
`currency`	string	幣別。
`balance`	string	目前可用餘額。格式：`^-?\d{1,15}(\.\d{1,4})?$`
`online`	boolean	目前是否在遊戲中（大廳或桌內）。
`createdAt`	string (date-time)	UTC 時間，ISO-8601 含毫秒。
`lastLoginAt`	string (date-time) \| null	最近一次進入遊戲的時間。

回應範例

json

{
  "ok": true,
  "data": {
    "username": "alice",
    "nickname": "Alice",
    "status": "active",
    "currency": "TWD",
    "balance": "1500.5",
    "online": true,
    "createdAt": "2026-09-20T08:15:30.120Z",
    "lastLoginAt": "2026-09-24T02:59:40.004Z"
  }
}

錯誤碼

錯誤碼	HTTP	意義
`INVALID_USERNAME`	400	玩家帳號不符合規則（1–32 個字元，英數字與 `_ . @ -`），或查詢時沒有帶 `username`。
`PLAYER_NOT_FOUND`	404	這個帳號的玩家不存在。

所有端點另外都可能回傳共通錯誤（UNAUTHORIZED、IP_NOT_ALLOWED、TENANT_SUSPENDED、RATE_LIMITED、INTERNAL_ERROR…）。

更新玩家

POST /api/tenant/v1/player/update

只更新有帶的欄位，回傳更新後的玩家資料（格式同 GET /player）。

status: locked：鎖定並立即踢出遊戲（原因 LOCKED），並送出 Webhook player.kicked（reason 為 locked）；之後 launch 會回 PLAYER_LOCKED。
status: no_bet：可以進入、觀看，但不能下注。active 恢復正常。
limitProfileId：必須是你自己的限紅方案或平台範本，且幣別與玩家相同，否則回 INVALID_PARAMETER；null 改回預設。
password：只有使用平台「公用登入」（/Login）的租戶需要；以 launch 串接的租戶不需要設定玩家密碼。

請求本文（application/json）

欄位	型別	必填	說明
`username`	string	是	玩家帳號，1–32 個字元（英數字與 `_ . @ -`）；不分大小寫（`Alice` 與 `alice` 是同一位玩家）。格式：`^[A-Za-z0-9_.@-]{1,32}$`
`status`	string	否	`active` 正常；`locked` 鎖定（不能進入遊戲）；`no_bet` 禁止下注（可進入觀看）。可能的值：`active`、`locked`、`no_bet`
`nickname`	string \| null	否	新暱稱；`null` 或空字串清除。
`limitProfileId`	integer \| null	否	限紅方案 ID：你在 Console「限紅方案」建立的方案，或平台範本；幣別必須與玩家相同，否則回 `INVALID_PARAMETER`。`null` 改回預設。限紅方案依遊戲區分，只套用在同一種遊戲的桌，其他遊戲的桌使用預設方案。範圍：1–…
`password`	string	否	公用登入（`/Login`）用的密碼，6–64 個字元。長度：6–64

請求範例

http

POST /api/tenant/v1/player/update HTTP/1.1
Host: elite.ewin888.com
X-Api-Key: ek_s_1a_XXXXXXXXXXXXXXXX
X-Timestamp: 1790218800
X-Nonce: ex31022a88145bbea84a3c01
X-Signature: fec8572e397e037df9aa8d207d142f38296d10890f96528a68cb66cd6778accc
Content-Type: application/json

{"username":"alice","status":"locked"}

回應的 data

欄位	型別	說明
`username`	string	玩家帳號（保留第一次建立時的大小寫）。
`nickname`	string \| null	暱稱。
`status`	string	`active` 正常；`locked` 鎖定（不能進入遊戲）；`no_bet` 禁止下注（可進入觀看）。可能的值：`active`、`locked`、`no_bet`
`currency`	string	幣別。
`balance`	string	目前可用餘額。格式：`^-?\d{1,15}(\.\d{1,4})?$`
`online`	boolean	目前是否在遊戲中（大廳或桌內）。
`createdAt`	string (date-time)	UTC 時間，ISO-8601 含毫秒。
`lastLoginAt`	string (date-time) \| null	最近一次進入遊戲的時間。

回應範例

json

{
  "ok": true,
  "data": {
    "username": "alice",
    "nickname": "Alice",
    "status": "locked",
    "currency": "TWD",
    "balance": "1500.5",
    "online": false,
    "createdAt": "2026-09-20T08:15:30.120Z",
    "lastLoginAt": "2026-09-24T02:59:40.004Z"
  }
}

錯誤碼

錯誤碼	HTTP	意義
`INVALID_PARAMETER`	400	缺少必要欄位，或欄位格式、值不正確；`message` 會指出是哪個欄位。
`INVALID_USERNAME`	400	玩家帳號不符合規則（1–32 個字元，英數字與 `_ . @ -`），或查詢時沒有帶 `username`。
`PLAYER_NOT_FOUND`	404	這個帳號的玩家不存在。

所有端點另外都可能回傳共通錯誤（UNAUTHORIZED、IP_NOT_ALLOWED、TENANT_SUSPENDED、RATE_LIMITED、INTERNAL_ERROR…）。

玩家 ​

啟動遊戲 ​

登出玩家 ​

查詢玩家 ​

更新玩家 ​

玩家

啟動遊戲

登出玩家

查詢玩家

更新玩家