玩家

启动游戏、登出、查询与更新玩家。玩家第一次 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…）。

玩家 ​

启动游戏 ​

登出玩家 ​

查询玩家 ​

更新玩家 ​

玩家

启动游戏

登出玩家

查询玩家

更新玩家