查询绑定

GET /v1/query-binding

查询指定合作方用户在指定游戏中的绑定关系及角色信息。

Request

通过 Query String 传递参数：

Property	Type	Required	Description
game_id	string	True	游戏 ID。
partner_user_id	string	True	合作方平台的用户唯一标识。

示例：

GET /v1/query-binding?game_id=example_game&partner_user_id=user_12345

Response

Property	Type	Description
bound_at	int64	绑定时间，Unix 秒级时间戳。
role	Role	绑定的角色详情。角色信息从游戏侧获取，存在短暂缓存（分钟级），可能与游戏内实际数据有轻微延迟。

Role

Property	Type	Description
server_id	int	游戏服务器 ID。
server_name	string	服务器名称。
role_id	string	角色 ID。
role_name	string	角色昵称。
role_level	int	角色等级。
avatar_url	string	角色头像 URL。为空表示无头像。
last_login_time	int64	最近一次登录时间，Unix 秒级时间戳。
extra	object	游戏侧扩展信息（例如职业等），结构因游戏而异。暂未提供，当前不返回该字段。

示例：

{
  "bound_at": 1714444800,
  "role": {
    "server_id": 10001,
    "server_name": "星耀服",
    "role_id": "1054832",
    "role_name": "彼岸繁花",
    "role_level": 60,
    "avatar_url": "https://game.seayoo.com/avatar/1054832.png",
    "last_login_time": 1714531200,
    "extra": {
      "class": "warrior"
    }
  }
}

信息

extra 字段的结构由游戏侧定义，不同游戏返回的内容不同。合作方如需了解某款游戏可提供的扩展字段，请联系世游技术对接人。

Errors

Error	Description
invalid_request	请求参数缺失或格式错误。
invalid_signature	签名验证不通过。
partner_disabled	合作方已被禁用。
binding_not_found	该用户在该游戏中未绑定角色。
role_not_found	绑定的角色不存在（例如角色已被删除）。
internal_error	服务端内部错误。