概览
本服务提供国服查询、国际服查询、礼包与解屏蔽。程序接入走 /api/v1，网页场景走 /web/v1。
快速开始
控制台签发令牌后，三次调用即可完成一次国服查询。默认 wait=true，服务端阻塞至完成或超时。
签发令牌
登录控制台创建 API Token。请求头写入 X-API-Key，也可使用查询参数 api_key。
提交查询
POST /api/v1/query，字段 query 为好友码或 UUID。action 取 block 或 delete。
取得结果
同步模式直接读 data。若 wait=false，用返回的 task_id 轮询任务接口。
鉴权
令牌按优先级读取。缺少或无效一律 HTTP 401，不进入业务逻辑。
| 来源 | 名称 | 优先级 |
|---|---|---|
| Request Header | X-API-Key | 1（推荐） |
| Query String | api_key | 2 |
| Request Header | Content-Type | application/json |
令牌视为密钥，禁止写入路径、日志或前端仓库。网页版不使用该头，改走卡密或 PoW。
调用模型
国服查询支持同步与异步。国际服为同步返回。任务状态机：pending → running → completed / failed / timeout。
同步 · wait = true
默认行为。服务端等待任务结束，成功时 status=completed 并带 data。客户端 HTTP 超时建议大于 timeout，推荐 70 秒。
异步 · wait = false
立即返回 task_id、status、queue_position。随后 GET /api/v1/task/{id} 直到终态。任务不存在返回 404。
接口参考
点击条目查看请求字段与示例。健康检查与队列状态同样需要令牌。
错误码
鉴权失败为 401。业务失败多数仍返回 HTTP 200，以 success=false 与 message 说明原因。
| HTTP | code | 说明 | 处理建议 |
|---|---|---|---|
| 401 | API_KEY_MISSING | 未提供令牌 | 补齐 Header 或 api_key |
| 401 | API_KEY_INVALID | 令牌无效、禁用或超额 | 更换令牌或调整配额 |
| 400 | validation | 字段格式不合法 | 检查 query / uuid 字符集 |
| 404 | — | 任务不存在 | 确认 task_id，避免过期后再查 |
| 503 | — | 队列不可用或提交失败 | 退避重试 |
| 200 | success=false | 业务失败、超时或功能关闭 | 读 message；可改异步后轮询 |
网页版
不便携带请求头时使用。国服 action=block 需卡密；action=delete 需先完成 PoW。
| 方法 | 路径 | 说明 | 鉴权 |
|---|---|---|---|
| GET | /web/v1/pow/challenge | 获取 salt、difficulty、signature | 无 |
| POST | /web/v1/query | 国服查询，字段 query / action | 卡密或 PoW |
常见问题
根路径为什么不是查询结果？
站点根路径为开发者说明。查询必须调用 POST /api/v1/query，请求体使用 query 字段，不是 friend_code。
同步调用一直等到超时怎么办？
将 wait 设为 false，保存 task_id 后轮询 GET /api/v1/task/{id}。客户端超时需大于服务端 timeout。
国际服能否用好友码？
不能。国际服、礼包、解屏蔽均要求标准 UUID：8-4-4-4-12 十六进制。
网页版和开放接口如何选择？
程序、脚本、服务端一律使用 /api/v1 与令牌。浏览器或无法自定义 Header 的环境使用 /web/v1。