查端记录

标识符不要混用

uuid：站内 USS 查端记录标识，如 USS-20260925-ABCDEF123456。不是 Minecraft/Mojang 账号 UUID，不证明账号所有权。
id：记录的数据库资源 ID，用于组织详情接口。
player_name：本次记录中的玩家名称；不能假定名称唯一或长期不变。

公开精确查询

GET /v1/records/{uuid}
Authorization: Bearer YOUR_API_KEY

需要 public:read。uuid 必须是完整 USS-YYYYMMDD-12位字母数字 格式，比较时忽略大小写。不提供公开玩家名称搜索、模糊查询或公开全量枚举。

{
  "ok": true,
  "data": {
    "id":"b2222222-2222-4222-8222-222222222222",
    "uuid":"USS-20260925-ABCDEF123456",
    "player_name":"ExamplePlayer",
    "game_category":"Minecraft",
    "game":"Example Server",
    "checked_at":"2026-09-25T03:00:00.000Z",
    "result":"clean",
    "result_label":"通过",
    "checker_name":"ExampleChecker",
    "public_notes":"本次查端公开说明。",
    "updated_at":"2026-09-25T03:05:00.000Z"
  },
  "request_id":"req_EXAMPLE"
}

result	含义
`clean`	本次查端通过
`warning`	可疑痕迹或警告，不应当作作弊的同义词
`cheating`	本次记录结论为作弊

未找到返回 404 RECORD_NOT_FOUND；格式不正确返回 422 INVALID_RECORD_UUID。

组织记录列表

GET /v1/partners/{partner_id}/records?limit=20

需要组织密钥和 records:read。仅返回绑定组织的记录，字段与公开记录对象相同；组织内部备注和 SSer 备注不会因此开放。

参数	类型	说明
`limit`	integer	1–100，默认 20
`cursor`	string	使用上次返回的 `next_cursor`，作为不透明值 URL 编码
`updated_after`	ISO 8601	包含该时间起发生更新的记录，使用 `>=` 比较
`result`	enum	clean / warning / cheating
`game`	enum	minecraft / fps
`player_name`	string	1–120 字符，完整名称精确匹配，忽略大小写

{"ok":true,"data":{"items":[],"next_cursor":null},"request_id":"req_EXAMPLE"}

空列表是成功结果，不是 404。未知筛选参数返回 422。Minecraft 对应 Minecraft 分类；其余受支持的查端游戏在此 API 中归入 fps 服务类别。

组织记录详情

GET /v1/partners/{partner_id}/records/{record_id}

需要 records:read。返回一个记录对象。该记录不存在或不属于此组织时统一返回 404 RECORD_NOT_FOUND。

增量同步与更正

首次遍历列表并以 id 保存记录。
后续使用 updated_after，保留几分钟重叠窗口，按 ID 和更新时间合并。
收到 record.updated 后重新请求详情，以最新数据替换原值。
收到 record.deleted 后移除本地记录的可见性。它也可能代表记录被转移到其他组织；事件不会透露目标组织。
定期完整核对：更新游标无法单独发现被删除的记录，Webhook 也有重试上限。

不要基于旧记录永久推断玩家当前状态。显示查端时间、结果来源和更正时间。删除后的记录详情可能立即返回 404，这是正常同步分支。