集成 API 使用说明

集成 API 面向需要把机器接进自有系统的用户：查询服务状态、读取流量、提交电源操作。

一、获取令牌

在「账户设置 → 集成」页面生成 API 令牌。令牌只在生成时完整显示一次，请立刻存到你的密钥管理里。轮换会立即作废旧令牌。

二、认证方式

所有请求在 Authorization 头里带上令牌：

Authorization: Bearer <你的令牌>

基础地址为当前站点的 /api/v1/integration。

三、可用接口

GET  /services                    列出你的服务
GET  /services/{id}               单个服务详情，含连接信息
GET  /services/{id}/traffic       当前周期流量用量
POST /services/{id}/actions       提交操作

提交操作的请求体：

{ "action": "power_on" }

action 可选值为 power_on、power_off、reboot、reinstall。

四、响应格式

所有响应统一为：

{ "code": 0, "message": "ok", "data": { ... } }

code 为 0 表示成功，非 0 表示业务错误，message 里有可读原因。HTTP 状态码同时反映结果，不要只看其中一个。

五、操作是异步的

提交操作会返回一个任务 ID，不代表操作已完成。用 GET /services/{id} 轮询 active_action 字段查看进度，或者等站内通知。电源操作通常几秒内完成，重装需要更久。

六、限流

每个令牌每分钟 120 次请求。超出返回 429，响应头里有 Retry-After。轮询请设置合理间隔，5 秒一次足够。