这套 API 是做什么的#

站内 API 用于把“查询账户、添加设备、管理设备、获取证书”接入您自己的面板、机器人或批处理脚本。公开 API 文档页目前收录 16 个接口，按 账户查询、设备管理、证书管理 三类组织：

• 账户查询：余额、价格、Token 有效期、更新 Token
• 设备管理：秒出添加、V2 添加、预约添加、批量添加、设备信息、设备列表、备注、启用/禁用、会员续期
• 证书管理：获取证书、证书检测

每个接口的参数、响应字段、错误示例、限流和代码示例，以 API 文档 页面实际显示为准。

第一步：获取 API Token#

1. 登录后进入 用户中心 → 账户
2. 打开 偏好 / Preferences 页签
3. 在 API Token 卡片中输入登录密码查看 Token
4. 根据需要设置失效时间

Token 是高权限凭据，请只放在服务器端或受控环境中。不要把它写进公开网页、前端 JavaScript、截图或提交到 Git 仓库。

如果 Token 泄露，可以在同一处刷新 Token。刷新后旧 Token 会立即失效，正在使用旧 Token 的程序需要同步更新配置。

第二步：理解通用请求格式#

身份认证

大多数接口通过名为 token 的参数认证。具体接口支持的载体以 API 文档为准：

• GET 接口通常放在 Query 参数中
• 传统添加接口支持 Query 或 application/x-www-form-urlencoded
• V2 和批量接口推荐使用 JSON body

所有接口都返回统一外层结构，成功通常是 code: 1，失败通常是 code: 0。不要只根据 HTTP 200 判断业务是否成功，应同时检查 code。

最小请求示例

bash curl -G 'https://你的站点域名/api/balance'
--data-urlencode 'token=你的_API_Token'

实际部署时请把域名、Token 和参数替换为您自己的值；不要把真实 Token 写进帮助文档或客户端代码。

第三步：选择添加接口#

单台设备：V2 接口

POST /api/adddevice/v2 是新系统优先推荐的单设备接口。它通过 mode 在两种流程间切换：

• mode=instant：秒出，成功时返回设备/证书数据
• mode=review：预约或审核，审核期间证书字段可能为空

常用参数包括 udid、mode、warranty、type、deviceType、beizhu 和可选的 code。其中 warranty 支持的值和价格由站点配置决定，API 文档列出的常见值为 0/1/2/3/4/6；review 模式仍受预约接口的档位限制。

bash curl -X POST 'https://你的站点域名/api/adddevice/v2'
-H 'Content-Type: application/json'
-d '{ "token": "你的_API_Token", "udid": "设备_UDID", "mode": "instant", "warranty": "1", "deviceType": "iphone" }'

接口返回的 data.id 是设备或预约记录标识；秒出成功时可能包含 Base64 编码的 mobileprovision 和 p12。请按接口详情页的字段说明处理，不要把证书内容直接打印到日志。

多台设备：批量接口

POST /api/adddevice/batch 用于批量处理 UDID。请求可使用：

• items：每项至少有一个 udid)，也可以覆盖单项的模式、售后、备注等参数
• udids：简化的 UDID 数组
• udids_text：用逗号、分号、空格或换行分隔的文本
• defaults：给整批设备设置默认参数
• continue_on_error：单项失败后是否继续处理，默认继续

批量响应中的 data.results 会逐条给出成功或失败结果。批量请求可能出现“部分成功”，调用方应按每条结果记录状态，不能只看总请求的 code。

批量接口限流更严格，适合控制并发、分批提交，并在客户端保留失败项以便人工复核。

设备和证书管理#

接入完成后通常按下面顺序组合接口：

1. 用 /api/device/list 保存或刷新设备列表
2. 用 /api/device/info 查询单台设备
3. 用 /api/device/remark 写入您的业务备注
4. 用 /api/device/status 启用、禁用或切换设备
5. 用 /api/device/membership/renew 处理设备权益续期
6. 用 /api/device/certcheck 检查证书状态
7. 用 /api/getcertificate 按接口支持的标识获取证书信息

设备查询接口通常支持 kid 或 udid 二选一；设备列表支持分页和状态筛选。请使用 API 文档中列出的字段名，不要把后台页面字段名自行映射成接口参数。

限流、扣费与错误处理#

• 每个接口限流不同，账户查询通常比添加和批量操作宽松；以接口详情页显示为准
• 添加设备会按当前用户、租户和站点价格规则扣费；批量接口可能部分成功
• Token 无效、过期或被刷新后，先停止重试并更新凭据
• UDID、设备类型、售后档位不匹配时，修正参数后再重试；不要在未知错误上无限重试
• 网络超时后不要立即重复提交添加请求，先查询设备列表或设备信息确认是否已经成功

联调顺序建议#

建议先按这个顺序接入，能快速定位问题：

1. 调用 /api/balance 验证 Token
2. 调用 /api/price 确认站点当前价格和可用档位
3. 用一台测试设备调用 V2 秒出接口
4. 用 /api/device/list 和 /api/device/info 验证落库结果
5. 最后再接批量接口，并实现逐条结果、超时和幂等保护

出现异常先看哪里#

批量出证、证书检测或接口响应异常时，先打开 服务状态页，确认对应组件和开放接口是否有进行中的事件。状态页展示实时信号、公开事件和最近 90 天的可用性历史；若服务整体正常，再结合接口返回的 msg、HTTP 状态、Token 有效期和请求参数排查。