游戏启动

获取游戏启动链接，玩家通过该链接进入真钱游戏。

环境地址

环境	Base URL
生产环境	`https://hub-panel-api.v7stech.com`
测试环境	`https://hub-panel-api-dev.v7stech.com`

接口信息

属性	值
路径	`POST /papi/v1/game/launch`
认证	Agent Token (Bearer)
Content-Type	`application/x-www-form-urlencoded`

请求参数

参数	类型	必填	说明
`member_id`	string	是	玩家唯一标识（代理侧 ID）。只允许英文字母和数字；传入大写字母时 Hub 会自动转换为小写。空格、下划线、连字符及其他符号会被拒绝。
`game_id`	string	是	游戏 ID（来自游戏列表接口）
`currency`	string	是	货币代码（如 `MYR`、`USD`）。自动转为大写
`platform`	string	否	平台类型：`WEB` / `MOBILE` / `DESKTOP`，默认 `WEB`。自动转为大写
`language`	string	否	语言代码，默认 `en-US`
`return_url`	string	否	退出游戏后跳转的 URL

自动注册机制

玩家首次启动游戏时：

系统会自动在游戏商注册玩家账号（无需单独调用）
系统会自动为该币种创建 balance=0 的钱包（如尚不存在）

同币种切换游戏

如果玩家已经在同一币种的其他游戏中，再次启动游戏不会被拦截。Hub 会先汇总该玩家该币种在所有 Provider 的钱包余额（包括迟到派彩），清空这些钱包并发起一次 switch_game Offline callback；包网 callback 成功或失败都不阻止新游戏启动。Hub 随后尽力关闭旧 session，并返回新游戏 URL 和新的 session_id；包网收到新启动响应后，后续余额增量同步必须使用新的 session_id。

请求示例

bash

curl -X POST https://api.example.com/papi/v1/game/launch \
  -H "Authorization: Bearer {agent_token}" \
  -d "member_id=player001&game_id=xxxx-guid&currency=MYR&platform=WEB&language=en-US"

响应字段

字段	类型	说明
`game_url`	string	游戏启动链接（将玩家跳转至此 URL 即可进入游戏）
`session_id`	string	VCT 为本次游戏启动生成的唯一会话 ID；后续 reclaim 时建议原样传回

响应示例

json

{
  "status": true,
  "code": 0,
  "data": {
    "game_url": "https://game.provider.com/play?token=xxx&lang=en-US",
    "session_id": "vct-session-uuid-001"
  },
  "msg": "success"
}

错误码

错误码	Message	说明
1001	`err.param.invalid`	必填参数缺失（`member_id`、`game_id`、`currency`）
1002	`err.signature.invalid`	Agent Token 验证失败
2006	`err.player.member_id_invalid`	`member_id` 格式错误：只能包含英文字母和数字，不能包含空格或符号
2001	`err.player.not_found`	玩家不存在（需先注册）
4001	`err.game.not_found`	游戏不存在或已下线
4005	`err.game.launch_failed`	游戏启动失败（游戏商注册或内部错误）
4006	`err.game.access_denied`	游戏启动访问校验失败。请根据 `msg` 判断具体原因：游戏不支持币种、Agent 币种未授权、Brand 不支持币种、未配置佣金费率或游戏未授权。详见错误码。
5002	`err.provider.call_failed`	游戏商接口调用失败

币种启动前提

currency 必须是游戏列表响应中该游戏实际返回的币种。对于上游标记为 ALL 的游戏，Hub 已在列表阶段替换为最终可启动的币种集合；不能传 ALL 启动。

实际启动还会校验该币种同时满足：全局 Currency Management 已启用、游戏与 Brand 支持、Agent 币种权限允许，以及存在适用的佣金费率。任一条件不满足均返回 4006，应按 msg 修正配置，不要重试。

启动失败与余额补偿

游戏启动成功的判断条件是 VCT 返回 code=0、非空 game_url，并且已经确认本次 session_id。仅收到包网 /balance 回调不代表游戏启动成功。

如果 /balance 已成功但游戏商启动失败，VCT 会通过 /api/v1/callback/offline 发送 action: "launch_failed"，并携带本次原始 session_id 与 reclaimed_amount。包网应按启动失败补偿处理，只释放临时会话和锁，不得当作普通 offline 平账或重复加款。

AI 开发提示词（可直接复制）

text

请在当前包网项目中实现 VCT 正式游戏启动流程。

接口：POST {VCT_BASE_URL}/papi/v1/game/launch
Content-Type：application/x-www-form-urlencoded
Authorization：Bearer {agent_token}，Token 必须在后端生成。
参数：member_id、game_id、currency 必填；platform、language、return_url 可选。

实现要求：
1. member_id 只允许英文字母和数字；currency、platform 转大写。game_id 必须来自 VCT 游戏列表返回的 id。
2. 为同一 Agent、玩家和币种增加并发启动保护，避免双击创建两次启动流程。
3. 只有 HTTP 成功、code=0、data.game_url 非空且 data.session_id 非空，才标记启动成功。
4. 原样保存 VCT session_id，并关联玩家、币种、game_id 和本次启动请求；后续 reclaim、bet-push、offline 都使用同一 ID。
5. /balance 回调成功只代表启动准备成功，不能提前记录 enter_game；浏览器跳转前仍需满足第 3 条。
6. 若后续收到 action=launch_failed 的 offline，只释放该 session 的临时记录和锁，不得按正常退出重复加款。
7. code=4006 时把 msg 原样提供给运营排查币种、Brand、佣金或游戏授权；不要自动重试配置错误。
8. 网络超时和 5xx 做有限重试，但不得在结果不确定时并发重复启动；记录 request ID，避免重复提交。
9. 不向前端或日志暴露 Agent API Key、Secret、完整 Token 或游戏 URL 中的敏感 token。
10. 增加测试：参数校验、成功条件、缺少 game_url、缺少 session_id、并发启动、4006、网络超时及 launch_failed 补偿。

请先复用项目现有认证、HTTP Client、玩家会话和锁机制，再完成 Service、Controller、前端跳转与测试。

游戏启动 ​

环境地址 ​

接口信息 ​

请求参数 ​

同币种切换游戏 ​

请求示例 ​

响应字段 ​

响应示例 ​

错误码 ​

币种启动前提 ​

启动失败与余额补偿 ​

AI 开发提示词（可直接复制） ​