PUBG·ALY API 对接文档

1. 对接前必读

• 服务地址：https://pubg.213344.vip
• 鉴权：所有请求带请求头 X-API-Key: <注册得到的KEY>
• 数据格式：请求与响应均为 Content-Type: application/json
• 账号标识：全程只用游戏昵称——上传和拉取都填昵称，无需也无需维护 account_id（服务器内部映射，响应里附上仅供参考）
• 只读权限隔离：只能管理/读取你自己上传过的账号——不关心别人的条目
• ⚠️ 本服务不提供任意昵称的实时查询：服务器只在后台名单内按配额轮转查询，API 返回的是已备好的缓存。想查某个号，先用 watchlist/sync 加入监控名单，等服务器轮到它（新号约 3~15 分钟）再来拉。
  这是刻意设计，不是功能缺失：前台实时查询会让访客随意消耗官方 10 RPM 配额、挤掉后台名单的正常轮转，进而拖慢所有用户。配额必须优先保障后台名单。

2. 你能拿到什么

服务器已准备好的玩家数据（当前赛季）：

• 段位（中文文本，如「大师 I」）、段位分 RP、历史最佳段位/分
• 账号状态（正常 / 临时封禁 / 永久封禁 / 未找到账号——官方查无此号）
• 四个模式的排位战绩：场次 / 胜场 / 击杀 / 助攻 / 击倒 / 死亡 / 总伤害 / 场均击杀 / 平均排名 / 胜率 / 前十率 / KDA / KDR

3. 使用频率建议

本服务对下游请求不设速率限制（拉取的是服务器已备好的缓存，不消耗任何上游额度），只需遵守下方红线与合理节奏。

⚠️ 高频红线（所有 API 生效）：同一 KEY 每秒最多 5 次——超限返回 429；连续超限 20 次 = KEY 自动吊销，需管理员恢复。心跳每 3 秒一次（0.33 次/秒）远低于红线。

A · 老名单轮询（已监控的老号，全量拉一遍的间隔）

服务器每分钟最多查询 6 个号；心跳会返回当前查询名单总数 watchlist_total。轮询间隔这样算：

全名单轮完一圈 ≈ watchlist_total ÷ 6（分钟）

推荐轮询间隔 = watchlist_total ÷ 6 + 3~5 分钟余量

例：总数 30  → 30÷6 + 3 ≈ 8 分钟拉一次全量
    总数 100 → 100÷6 + 3 ≈ 20 分钟拉一次全量
    总数 200 → 200÷6 + 3 ≈ 36 分钟拉一次全量

余量是为了：① 服务器偶发排队/网络波动 ② 同一圈里可能混有新号插队。按此间隔拉全量，每次都能拿到基本刷新的数据。

B · 新添加的号（单独快节奏，3~5 分钟即可开始查）

新号服务器会优先更新（插队转换/查询），所以不用等整轮：

添加后 3~5 分钟 → 发起首次拉取（只查这个新号即可，不必拉全量）
converting → 再等 3 分钟重试，直到转换完成
no_cache → 建议先按「未定位」展示，等下轮全量拉取自动更新；也可等 10 分钟再查确认
no_ranked → 直接显示「未定位」，无需另外拉取（等批次全量刷新自动更新）
not_found_account → 见情况 6（多半已改名/注销，重新 add 新昵称即可）

C · 其它说明

• 整表轮询（A）与单号首查（B）节奏独立，不互相等待
• 一次 batch 传多个昵称只算 1 次请求——拉全量时分批传（每批 ≤300 个）最省
• 别在收到 hit:false 后立刻反复重试（防滥用 + 数据确实没变）

4. 指令如何配置（4 个动作）

所有命令把 你的KEY 替换成真实 KEY 即可复制运行。请求示例与返回示例都用深色框圈出，与说明文字区分。

动作一注册，拿 KEY

打开 https://pubg.213344.vip/register → 填「你在群里微信名」+ 社区验证号 → 提交。页面显示 网站地址 / 备注名 / 客户端ID / API KEY，点「复制全部资料」存进客户端配置。无需编程。

动作二添加 / 取消监控（按昵称）

游戏ID仅支持英文/数字/常用符号，不允许中文——含中文的 add 会被拒绝（result:"invalid"）。

完整地址：https://pubg.213344.vip/api/v1/watchlist/sync；请求头 X-API-Key: 你的KEY。用途：告诉服务器你要监控谁（加）或不再监控谁（删）。单次最多 300 条指令，超过会截断并提示分批。

▶ 请求示例 —— 添加一个昵称：

curl -X POST "https://pubg.213344.vip/api/v1/watchlist/sync" \
  -H "X-API-Key: 你的KEY" -H "Content-Type: application/json" \
  -d '{"ops":[{"op":"add","game_id":"玩家游戏昵称"}]}'

▶ 请求示例 —— 一次加多个 / 取消监控：

# 一次加多个
-d '{"ops":[{"op":"add","game_id":"昵称A"},{"op":"add","game_id":"昵称B"}]}'

# 取消监控（把 add 改成 remove）
-d '{"ops":[{"op":"remove","game_id":"昵称A"}]}'

◀ 响应逐条判断（done 数组，按你发的顺序一一对应）：

情况 1 · 添加成功 —— created: true

{"op":"add","game_id":"昵称A","uploader":"YSQ","created":true}

• 已加入监控，服务器开始准备数据；约 15 分钟后用动作三查询

情况 2 · 本来就在名单 —— created: false

{"op":"add","game_id":"昵称B","uploader":"YSQ","created":false}

• 无需处理，当作“已在监控中”即可，不用重复加

情况 3 · 取消成功（整行删除）—— result:"removed"

{"op":"remove","game_id":"昵称A","uploader":"YSQ","result":"removed"}

• 该昵称已从你的监控中移除（若没人再传，条目也删了）

情况 4 · 只摘除你、别人还在监控 —— result:"released"

{"op":"remove","game_id":"昵称C","result":"released",
 "note":"名单仍被其他成员监控"}

• 你不再监控它了（正常）；服务器仍会为其他成员保留，与你无关

情况 5 · 名单里没有 / 非你上传 —— result:"not_found"

{"op":"remove","game_id":"随便一个号","result":"not_found",
 "note":"名单中不存在该昵称，或非你上传"}

• 正常现象不是错误：你从没加过它，或 48 小时无人拉取已被自动清理——客户端忽略即可

🛑 必读约定：客户端一旦不再需要监控某个账号（本地删除/停止关注），必须立即调用本动作发 remove 取消监控——服务器收到后立刻释放该号的查询配额给其它账号使用。虽然你不发、48 小时后该号也会因无人拉取被自动清理（兜底），但主动 remove 能当场省下配额——删号必同步取消监控。

动作三拉取玩家数据

完整地址：https://pubg.213344.vip/api/v1/players/batch；请求头同上。用途：把你想看的昵称发给服务器，服务器返回缓存好的玩家数据。单次最多 300 个昵称，超过会截断并提示分批。

▶ 请求示例：

curl -X POST "https://pubg.213344.vip/api/v1/players/batch" \
  -H "X-API-Key: 你的KEY" -H "Content-Type: application/json" \
  -d '{"names":["玩家1昵称","玩家2昵称"]}'

◀ 响应逐条判断（每个昵称固定带 hit 字段）：

情况 1 · 命中 —— "hit": true

{"hit":true,"account_id":"account.xxx","data":{ ...玩家数据... },
 "age":120,"stale":false}

• 直接解析 data 展示；stale:true 表示数据略旧但可用，不用特殊处理

情况 2 · 不在你的监控名单 —— reason:"not_in_list"

{"hit":false,"reason":"not_in_list",
 "hint":"该昵称不在你的监控名单，请先调用 watchlist/sync 添加"}

• 先回动作二把它 add 进名单，等 15 分钟再查；直接重试 batch 会一直命中此情况

情况 3 · 转换中（刚添加未就绪）—— reason:"converting"

{"hit":false,"reason":"converting","retry_after":180,
 "hint":"新号优先更新中——请 3 分钟后再查，未中就每 3 分钟重试一次"}

• 标记该号“等待中”，按 retry_after（180 秒）到点再查，期间不请求

情况 4 · 数据不完整，缺失排位数据 —— reason:"no_cache"

{"hit":false,"reason":"no_cache","retry_after":600,
 "hint":"数据暂不完整（缺失排位数据，原因未确认）——建议先按未定位展示，等待下轮全量拉取时自动更新；也可等 10 分钟后再查确认",
 "data":{"name":"玩家昵称","ban":"Innocent","ban_signal":"IIIIIIIIII","season_no":42}}

• 此时无法区分「后台还没轮到它查」和「该账号没打排位」——服务器只是还没有它的完整档案
• data 是部分数据：ban / ban_signal 来自 players 端点采样，与排位无关——未打排位的号照样可能被封禁，这部分可正常展示；排位字段（tier/rp/modes）此时不存在
• 建议处置：先按「未定位」展示，等下轮全量拉取时自动更新
• 若之后转为 no_ranked → 见情况 5（确认未定位）；若一直停在 no_cache，请联系管理员检查后台是否在运行

情况 5 · 已明确确认未定位 —— reason:"no_ranked"

{"hit":false,"reason":"no_ranked",
 "hint":"已确认该账号本赛季未定位（官方无排位记录）——建议直接显示未定位，无需另外拉取；等批次全量刷新缓存时状态会自动更新",
 "data":{"name":"玩家昵称","ban":"TemporaryBan","ban_signal":"TIIIIIIIII","season_no":42,
         "tier":"Unranked","tier_cn":"未定位","rp":0,"best_tier":"Unranked","best_rp":0,"modes":{}}}

• 这是明确结论：服务器已查询完毕，官方确认该账号本赛季没有排位记录（未定位 / Unranked），直接按“未定位”展示
• data 是部分数据：账号状态字段完整可用——ban / ban_signal 必须展示（未定位的号也可能被封禁，甚至未定位就是被处罚的结果）；排位字段为默认值：tier:"Unranked"、rp:0、modes:{}，按"无排位数据"处理
• 无需另外发起拉取：状态由服务器批次全量刷新自动维护——他打完排位后，下轮批次刷新缓存会自动产出数据，你下一次全量拉取时自然变为 hit:true
• 与情况 4 的区别：no_cache 是“数据不完整、原因未确认”，no_ranked 是“已确认未定位”

情况 6 · 官方查无此号 —— reason:"not_found_account"（终态）

{"hit":false,"reason":"not_found_account",
 "hint":"官方查无此号（可能已改名/注销）——请从监控名单中移除该账号"}

• 官方连 players 端点都查不到这个号——多半是改名了（用新昵称重新 add 即可）或账号注销
• 建议调用动作二发 remove 移除；不移除服务器也会在连续多次确认后自动清理，但早点移除省配额

ban_signal 封禁信号解读

命中数据内的 ban_signal 是该账号最近 10 次状态采样的序列，按时间先后排列，最右为最新：

解读示例："TITIIIIIITI" = 最近 10 次查询中多数正常、近期出现临时封禁信号。服务端判定采用多数确认（最近 10 次中临时/永久封禁出现 ≥4 次才标记、正常出现 ≥8 次即恢复），单次闪烁不影响 data.ban 的稳定性。

动作四双向握手（每 3 秒）

完整地址：https://pubg.213344.vip/api/v1/heartbeat。用途：让服务器知道你在线、你也知道服务器在线。客户端每 3 秒发一次，不带请求体。

▶ 请求示例：

curl -X POST "https://pubg.213344.vip/api/v1/heartbeat" -H "X-API-Key: 你的KEY"

◀ 正常返回（服务端状态同步回给你）：

{"ok": true, "service": "ok",
 "server_time": 1788593000,            // 服务端时间，客户端可用来校时
 "season": {"season_no": 42, "season_id": "division.bro.official.pc-2018-42"},
 "watchlist_total": 32}                // 当前查询名单总数（全局）

• 能收到响应 = 服务端在线且你的 KEY 有效；连续几次收不到 = 服务端异常/断网 → 客户端提示并退避重试
• watchlist_total 反映服务器端查询名单规模，供客户端参考拉取间隔
• 服务器收不到你的心跳 = 你离线（管理台“最后在线”可见）
• 旧 /api/v1/status 已合并进本端点

{
  "name": "游戏昵称",
  "ban": "Innocent",             // 账号状态（当前稳定判定）
  "ban_signal": "ITIIIIIITI",    // ⭐ 封禁信号样本：最近 10 次采样序列，按时间先后排列（最右为最新）
  //  信号含义：I=正常  T=临时封禁  P=永久封禁  N=未找到账号
  //  客户端可统计 T/P 占比或趋势自行分析；也可直接信任 data.ban（服务端已用相同样本判定）
  "season_no": 42,               // 当前赛季
  "tier_cn": "大师 I",            // 段位（中文，展示直接用）
  "rp": 7062,                    // 当前段位分
  "best_rp": 7346,               // 本季最高段位分
  "modes": { ... 每模式核心战绩字段 ... }
  // 注：account_id 不在 data 内，由批次响应条目顶层提供
}
  // 每模式字段：roundsPlayed/wins/losses/kills/deaths/assists/dBNOs/
  //            damageDealt/avgKill/avgRank/winRatio/top10Ratio/kda/kdr
  // 段位四模式统一，只在顶层（tier_cn/rp），modes 不重复段位
}