API 概述

本文档介绍 ZundaLink 对访问者公开的 JSON API。接口与网页端使用同一套账号权限；如果网页没有显示某项功能，脚本也不应尝试猜测或调用未记录的接口。

基础地址

当前网页端默认使用的基础地址为：

https://xn--9er778cb3e.xn--igrr70arr3c.vip/zundalink/api/v0

服务地址可能调整。部署自己的客户端时，建议把基础地址放在可配置项中，不要写死在多个文件里。

请求格式

• 使用 HTTPS；
• JSON 请求使用 Content-Type: application/json；
• 字符编码为 UTF-8；
• Token 通过请求体中的 token 字段传递；
• 文件下载接口可能返回图片、文件或 JSON 错误对象。

最小请求示例：

curl -X POST "${ZDL_API}/token/validate" \
  -H "Content-Type: application/json" \
  -d '{"token":"<TOKEN>"}'

通用响应

大多数接口使用以下字段：

{
  "success": true,
  "msg": "success"
}

字段	类型	说明
success	boolean	业务请求是否成功
msg	string	面向用户的结果或错误说明

部分接口会使用 valid、data、fileList、playlogList 等专用字段；请以对应页面为准。

认证与权限

1. 通过注册与认证或Token 生命周期获取 Token。
2. 每次调用时在 JSON 请求体中携带 Token。
3. 不要把 Token 放入 URL、日志、截图或前端公开代码。
4. 机台账号和用户账号的可见接口不同，权限不足时应直接显示服务返回的错误。

错误处理建议

• 4xx：检查参数、Token、账号权限和验证码；
• 401/403：重新验证账号，确认当前账号类型；
• 404：确认路径和 API 版本；
• 429：降低请求频率，按退避策略重试；
• 5xx：保留请求时间和响应消息，稍后重试；
• JSON 解析失败：先读取响应的 Content-Type，文件接口可能返回二进制内容。

不要在客户端中无限重试，也不要把错误响应原样公开给其他用户。

公开接口目录

分类	用途
注册与认证	注册、登录和绑定密码
Token 生命周期	获取、验证和退出 Token
访问码与二维码	生成访问码、绑定网页登录
配方管理	读取和修改当前账号可见的配方
相片管理	列出、读取和删除相片
数据缓存	备份和恢复账号缓存
上传缓存	管理上传快照
用户乐曲数据	读取成绩页所需的乐曲数据
成绩互动	点赞、评论和内容反馈
游玩记录	分页读取历史记录
机台查卡	读取公开的机台在线与会话统计
地区统计	读取公开地区聚合数据
公开统计	读取服务级聚合统计
API 错误模型与重试	HTTP、业务失败、文件响应和重试边界
分页、范围与文件接口	范围分页、去重、二进制和导出
API 兼容性与版本迁移	新字段、缺失字段、版本和迁移
API 数据最小化与日志安全	凭据、日志、缓存和安全事件
公开 API 客户端测试	测试夹具、不变量和工作流回归
公开 API 可观测性	脱敏事件、延迟、轮询、写入状态和追踪
公开 API 大数据导出	分块读取、检查点、去重、取消和校验
公开 API 按任务示例集	登录、配方、缓存、互动、查卡和安全关闭
API 字段校验与输入边界	字符串、数字、JSON、文件、分页和写入前检查
成绩互动与内容反馈工作流	评论、回复、互动、反馈和审核状态
公开缓存备份格式与迁移	普通备份、上传快照、账号导出和恢复演练
公开 API 权限与可见性矩阵	账号类型、入口隐藏、目标范围和切换边界

JavaScript 基础示例

const API = 'https://xn--9er778cb3e.xn--igrr70arr3c.vip/zundalink/api/v0';

async function validateToken(token) {
  const response = await fetch(`${API}/token/validate`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token }),
  });

  const data = await response.json();
  if (!response.ok || data.valid === false) {
    throw new Error(data.msg || 'Token 无效');
  }
  return data;
}