01
快速开始
三次调用完成一次国服查询。默认 wait=true，服务端阻塞到完成或超时。
01
签发令牌
控制台创建 Token。请求头写 X-API-Key，也可使用查询参数 api_key。
02
提交查询
POST /api/v1/query，字段 query 为好友码或 UUID。action 为 block 或 delete。
03
读取结果
同步模式直接读 data。若 wait=false，用 task_id 轮询任务接口。
02
鉴权
令牌按优先级读取。缺少或无效一律 HTTP 401，不进入业务逻辑。
| 来源 | 名称 | 优先级 |
|---|---|---|
| Header | X-API-Key | 推荐 |
| Query | api_key | 次选 |
| Header | Content-Type | application/json |
安全约定
令牌按密钥保管，不要写入 URL 路径或前端仓库。网页版不使用该头，改走卡密或 PoW。
03
调用模型
国服支持同步与异步。国际服同步返回。客户端 HTTP 超时应大于 timeout，建议 70 秒。
pending
running
completed
failed / timeout
同步 · wait = true
默认。成功时
status=completed 并带 data。超时仍会返回 task_id，可继续轮询。
异步 · wait = false
立即返回
task_id、status、queue_position。随后 GET /api/v1/task/{id} 直到终态。
04
接口参考
左侧选择接口。健康检查与队列状态同样需要令牌。
05
错误码
鉴权失败为 401。业务失败多数仍是 HTTP 200，以 success=false 说明原因。
| 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 |
06
网页版
不便携带请求头时使用。action=block 需卡密；action=delete 需先完成 PoW。
| 方法 | 路径 | 说明 | 鉴权 |
|---|---|---|---|
| GET | /web/v1/pow/challenge | 获取 salt、difficulty、signature | 无 |
| POST | /web/v1/query | 国服查询，字段 query / action | 卡密或 PoW |
07
常见问题
根路径为什么不是查询结果？
根路径是文档。查询请调用 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。