游戏接口

本文描述公开 HTTP 接口。除健康检查外均使用 POST，携带 Content-Type: application/json 和 token: YOUR_TOKEN；接口地址使用当前应用审核后提供的基础地址。认证、错误与重试规则见签名认证。下列编号、地址、玩家与金额均为示例。

游戏目录

POST /api/v1/gamelist

取得游戏目录。无参数，发送空对象。响应 message 是 JSON 字符串，需要再解析一次；字段表描述解码后的对象。

{}

{
  "success": true,
  "message": "{\"list\":[{\"game_code\":\"baccarat\",\"name\":\"百家乐\",\"game_type\":\"table\",\"thumb_url\":\"https://games.example.invalid/thumb/baccarat.png\",\"priority\":1,\"status\":1,\"version\":\"1\"}],\"timestamp\":1792000000}"
}

message 解码后的业务对象（用于阅读，不是另一次 HTTP 响应）：

{
  "list": [
    {
      "game_code": "baccarat",
      "name": "百家乐",
      "game_type": "table",
      "thumb_url": "https://games.example.invalid/thumb/baccarat.png",
      "priority": 1,
      "status": 1,
      "version": "1"
    }
  ],
  "timestamp": 1792000000
}

服务端不承诺数组已按推荐值排序。目录不返回 game_id、room_mode、hot_priority。默认场次由服务端处理，不要根据目录名重建游戏 URL。

启动游戏

POST /api/v1/user/launch_url

为已在第三方站点登录的玩家获取游戏入口。调用必须来自第三方服务端，不能允许浏览器指定任意其他玩家身份。

{
  "user": "test-player-001",
  "name": "测试玩家",
  "avatar": "default",
  "country_code": "CN",
  "game": "baccarat",
  "theme": "0"
}

{
  "success": true,
  "user_key": "WALLET_SESSION_KEY",
  "game": "baccarat",
  "launch_url": "https://games.example.invalid/?session=OPAQUE_SESSION&game=baccarat&theme=0&serverUrl=wss%3A%2F%2Fgames.example.invalid%2Fws"
}

不同合作方下相同 user 独立。获取链接不代表已登录游戏或钱包已开启。重复调用可能重新签发入口；已在线时可能恢复当前游戏，必须读取响应 game。不能自行拼接、长期缓存或公开 launch_url。lobby_url 当前不改变返回行为；iframe 返回使用浏览器交互。

业务失败常见 message：invalid user code（玩家编码不合规）、invalid country_code、invalid user_code（创建玩家失败，也可能是请求游戏无效）、invalid game_code、machine unavailable（目录位置失效）、default room unavailable、profile update failed。这些错误可能以 HTTP 200、success=false 返回，不应自动无限重试。

玩家状态

POST /api/v1/user/status

查询当前合作方下玩家的运行状态。user 为必填字符串，与启动时完全一致。

{
  "user": "test-player-001"
}

{
  "success": true,
  "status": "offline"
}

{
  "success": true,
  "game_code": "baccarat",
  "status": "online",
  "session": "OPAQUE_SESSION",
  "session_timestamp": 1792000000,
  "session_time": 60,
  "login_timestamp": 1792000010,
  "login_time": 50,
  "balance": 10000000,
  "open_status": 2
}

缺少 user 返回 success=false、message="user code empty"。没有运行记录时只返回 success/status；不要假定所有可选字段存在。

请求退出

POST /api/v1/user/kick

user 为必填字符串。通知当前玩家退出，不是同步结算接口。

{
  "user": "test-player-001"
}

{
  "success": true,
  "status": "pending"
}

响应 status 为 pending 表示退出通知已下发，offline 表示当前不在线。缺少 user 返回 user code empty。两种成功状态都不代表 close 回调完成；提现、调账须依据第三方已核对的钱包状态。超时先查询状态，不要把 HTTP 超时视为退出未执行。

头像目录

POST /api/v1/avatars

无参数，发送空对象。此接口直接返回顶层 list，不需要解析 message。

{}

{
  "success": true,
  "list": [
    {
      "avatar": "default",
      "url": "https://games.example.invalid/avatars/default.png"
    }
  ]
}

公开机台目录

POST /api/v1/game/tables

无参数，返回有效快照；message 为 JSON 字符串。仅上报机台的游戏会出现在目录中，空数组不表示全部游戏不可用。

{}

{
  "success": true,
  "message": "{\"tables\":[{\"server_id\":101,\"room_id\":1,\"game_id\":100,\"table_id\":1,\"game_code\":\"example-game\",\"occupied\":false,\"players\":0,\"capacity\":1,\"jackpot\":\"100000\"}]}"
}

message 解码后的业务对象（用于阅读，不是另一次 HTTP 响应）：

{
  "tables": [
    {
      "server_id": 101,
      "room_id": 1,
      "game_id": 100,
      "table_id": 1,
      "game_code": "example-game",
      "occupied": false,
      "players": 0,
      "capacity": 1,
      "jackpot": "100000"
    }
  ]
}

超过 15 秒未更新的实例快照不输出。目录与启动之间存在时间差；启动返回 machine unavailable 时刷新目录并重新选择。

游戏动态

POST /api/v1/game/activity

用于在线人数和中奖展示，不是交易查询接口。cursor 为可选字符串，首次为空；后续原样提交上次返回的 cursor，不要解析或自己构造。

{
  "cursor": ""
}

{
  "success": true,
  "message": "{\"cursor\":\"EPOCH:42\",\"reset\":true,\"games\":[{\"game_code\":\"baccarat\",\"online\":12,\"stale\":false}],\"wins\":[{\"event_id\":\"101:example-event\",\"game_code\":\"baccarat\",\"nickname\":\"示例玩家\",\"avatar\":\"default\",\"country_code\":\"CN\",\"amount\":\"1000\",\"amount_type\":\"net_win\",\"occurred_at\":1792000000}]}"
}

message 解码后的业务对象（用于阅读，不是另一次 HTTP 响应）：

{
  "cursor": "EPOCH:42",
  "reset": true,
  "games": [
    {
      "game_code": "baccarat",
      "online": 12,
      "stale": false
    }
  ],
  "wins": [
    {
      "event_id": "101:example-event",
      "game_code": "baccarat",
      "nickname": "示例玩家",
      "avatar": "default",
      "country_code": "CN",
      "amount": "1000",
      "amount_type": "net_win",
      "occurred_at": 1792000000
    }
  ]
}

真人动态按合作方过滤，机器人动态共享。首次或 reset 从全局最新至多 20 个序号开始，过滤后可能更少；内存保留最多 2000 条、展示窗口约 10 分钟，不保证历史重放。持续使用返回 cursor 获取后续批次。无参数 limit 或历史时间范围查询，不得据此对账。

健康检查

GET /api/v1/health

无请求体，无需 token。此接口只检查 HTTP 入口就绪情况。

{
  "status": "ok",
  "pending": 0
}

健康检查成功不能证明数据库、全部游戏实例、WebSocket 或第三方回调健康。公开路由不提供充值、余额修改或历史账本查询接口。