dafuweng-saiadmin6.x/API对接文档.md

大富翁-摇色子 对接文档

本文覆盖平台侧对接接口（/api/v1/*，使用 auth-token 鉴权）以及（可选）玩家侧接口（/api/*，使用 token 鉴权）。

---

1. 基本约定

1.1 服务地址（Base URL）

由部署方提供：

• 测试环境：https://dice-api.h55555game.top

下文所有路径均为相对路径，如：/api/v1/getGameUrl。

1.2 请求方式与编码

• 请求方法：项目路由多数使用 Route::any，对接建议统一使用 POST（便于 body 传参）；个别接口文档中标注了 GET 参数。
• 编码：UTF-8
• Content-Type：建议 application/x-www-form-urlencoded 或 application/json（以平台实际实现为准）
• 必带凭证：所有 /api/v1/* 接口均需带 api-key（与服务端 .env 中 API_KEY 一致）；除 /api/v1/authToken 外另需 auth-token。详见 §2.2。

1.3 统一返回结构

所有接口统一返回 JSON：

{
  "code": 200,
  "message": "success",
  "data": {}
}

• code：业务状态码（见“返回 code 对照表”）
• message：提示信息（可根据请求头 lang 返回中英文）
• data：成功时返回数据；失败时通常不返回该字段

1.4 多语言（lang）

服务端会根据请求头 lang 翻译 message（以及部分接口字段）：

• lang: zh（默认）
• lang: en

注意：平台 v1 接口的 getGameUrl 还支持 body 参数 lang（zh/en），用于拼接游戏地址语言参数。

---

2. 鉴权与对接流程（平台侧 /api/v1）

平台侧接口需统一携带请求头 api-key（与服务端 .env 中 API_KEY 一致），业务接口另需 auth-token。

1. 获取 auth-token（同时携带 api-key）
2. 携带 api-key + auth-token 调用 /api/v1/* 业务接口

2.1 获取 auth-token

• 路径：/api/v1/authToken
• 方法：GET / POST 均可（建议 GET，参数放 query）
• 说明：用于平台调用 v1 业务接口的授权 token（JWT）

请求参数（query/body）

参数名	必填	类型	说明
agent_id	是	string	平台/代理标识（后台查看对应管理员agent_id）
secret	是	string	双方约定的密钥（服务端配置 xF75oK91TQj13s0UmNIr1NBWMWGfflNO）
time	是	int/string	Unix 时间戳（秒），服务端会做时间容忍校验
signature	是	string	签名：md5(agent_id + secret + time)

• agent_id：通过后台获取系统管理-用户管理-代理ID
• secret：xF75oK91TQj13s0UmNIr1NBWMWGfflNO（服务器配置）
• 后台地址：https://dice.h55555game.top 账号: zhuguan 密码：123456

签名规则

• 签名字符串：直接拼接 agent_id.secret.time（无分隔符）
• 算法：MD5（32 位小写/大写均可，按实现一致即可）

示例（伪代码）：

signature = md5(agent_id + secret + time)

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "authtoken": "xxxx.yyyy.zzzz"
  }
}

失败场景

• 缺少参数：code=400
• 密钥错误/签名错误/时间戳无效：code=403
• 服务端未配置密钥或生成失败：code=500

2.2 平台 api-key（所有 /api/v1/* 必填）

• 取值：与服务端环境变量 API_KEY 完全一致（部署在 server/.env）
• 适用范围：所有 /api/v1/* 接口（含 /api/v1/authToken 与业务接口）
• 携带方式（任选其一，按优先级读取，先命中即采用）：
  1. 请求头 api-key: <API_KEY>（推荐）
  2. URL 查询参数 api_key=<API_KEY>（或 api-key=<API_KEY>）
  3. body 表单/JSON 字段 api_key（或 api-key）
• 未携带或错误：401 / 403

2.3 调用 v1 业务接口（携带 auth-token）

除 /api/v1/authToken 外，其余 /api/v1/* 接口需要携带：

• api-key: <与 API_KEY 一致>（请求头 / query / body 任选其一，参见 2.2）
• auth-token: <authtoken>（仅支持请求头）

当 auth-token 过期或失效，返回 code=402，需要重新调用 /api/v1/authToken 获取新 token。

---

3. 平台 v1 业务接口清单（/api/v1）

3.1 获取游戏地址

• 路径：/api/v1/getGameUrl
• 方法：POST
• 请求头：api-key、auth-token
• 说明：根据平台用户名创建/登录玩家并生成登录 JWT，返回可直接打开的游戏地址。

请求参数（body）

参数名	必填	类型	说明
username	是	string	玩家唯一账号（平台侧用户名）
time	否	int/string	默认当前时间戳
lang	否	string	zh / en，默认 zh

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "url": "https://dice-game.h55555game.top/?token=...&lang=zh"
  }
}

3.2 获取用户信息

• 路径：/api/v1/getPlayerInfo
• 方法：POST
• 请求头：api-key、auth-token

请求参数

参数名	必填	类型	说明
username	是	string	玩家账号

响应说明

返回玩家基础信息（已隐藏敏感字段，如 password 等）。

3.3 获取游戏记录

• 路径：/api/v1/getPlayerGameRecord
• 方法：POST
• 请求头：api-key、auth-token

请求参数

参数名	必填	类型	说明
username	否	string	不传则不按用户筛选；数据仅来自「最近 7 天」时间窗（见下）
start_create_time	否	string	开始时间；与 end_create_time 均不传时，服务端默认最近 7 天
end_create_time	否	string	结束时间
limit	否	int	返回条数上限，默认 20；小于 1 或大于 2000 时按 20 处理

时间规则：仅允许查询「当前服务器时间起向前 7 天」内的 create_time；start_create_time 与 end_create_time 的跨度不得超过 7 天；end_create_time 晚于当前时间时按当前时间截断。非法区间返回参数错误。

响应说明

返回游玩记录列表（按 id 倒序，最多 limit 条），并附带 dice_player（包含 id/username/phone）。

3.4 获取钱包流水

• 路径：/api/v1/getPlayerWalletRecord
• 方法：POST
• 请求头：api-key、auth-token

参数与时间规则同 3.3（无 page，仅 limit 限制条数），返回钱包流水列表（附带 dice_player）。

3.5 获取中奖券获取记录

• 路径：/api/v1/getPlayerTicketRecord
• 方法：POST
• 请求头：api-key、auth-token

参数与时间规则同 3.3，返回中奖券记录列表（附带 dice_player）。

3.6 平台钱包转入/转出

• 路径：/api/v1/setPlayerWallet
• 方法：POST
• 请求头：api-key、auth-token
• 说明：平台为玩家加币/扣币，生成钱包流水。

请求参数

参数名	必填	类型	说明
username	是	string	玩家账号
coin	是	number	转入：>0；转出：<0；不允许为 0

业务规则

• 当 coin < 0 且余额不足时：code=422，message=余额不足，无法转出

---

4. 玩家侧接口（可选 /api）

若甲方平台需要在服务端直接调用“购买抽奖券/开局”等接口，可按本节对接（此类接口需要 token，与 auth-token 不同）。

4.1 获取 token（玩家登录）

• 路径：/api/user/Login
• 方法：POST
• 说明：创建/登录玩家并返回登录 token 以及游戏地址。

请求参数：username、password（必填），lang/coin/time（可选）。

响应 data.token 可用于后续 /api/* 请求头 token 或 Authorization: Bearer <token>。

4.2 需要 token 的接口

请求头携带（任选一种）：

• token: <token>
• Authorization: Bearer <token>

接口列表：

• /api/user/logout
• /api/user/info
• /api/user/balance
• /api/user/walletRecord
• /api/user/playGameRecord
• /api/game/config
• /api/game/buyLotteryTickets
• /api/game/lotteryPool
• /api/game/playStart

---

5. 返回 code 对照表

项目定义的统一状态码如下（与 HTTP 语义对齐）：

code	含义	常见场景
200	成功	请求成功
400	请求参数错误	缺参、参数格式不合法、范围错误
401	未授权	未携带 api-key、auth-token 或 token
402	token 无效或已过期	auth-token/token 过期、签名错误、被挤下线等
403	鉴权失败	api-key 无效、secret 错误、签名验证失败、时间戳无效等
404	资源不存在	用户不存在等
422	业务逻辑错误	余额不足、业务校验失败等
500	服务器内部错误	服务端异常或配置缺失

---

6. 联调建议

• 时间戳校验：/api/v1/authToken 会校验 time 与服务器时间差（默认容忍 300 秒），请确保平台服务器时间同步。
• token 失效处理：当 code=402 时，按业务类型重新获取 auth-token 或重新登录获取 token。
• 语言：如需英文提示，请在请求头带 lang: en。