REST API 概览

平台后端提供统一的 REST API，Web 管理端本身也是这套 API 的消费者——界面上能做的，接口都能做。本页给出资源地图与调用约定；具体字段以 Swagger 为准。

一、在哪里看完整接口文档

服务启动后访问 Swagger：

http://<服务地址>/swagger

Swagger 里可以在线调试：点右上角 Authorize 填入访问令牌后，所有接口即可直接发起请求。

二、调用约定

约定	说明
认证	登录接口换取 JWT，后续请求携带 Authorization: Bearer <token>
数据边界	接口自动按当前账号的租户/客户身份过滤数据，无需（也无法）跨边界查询
响应壳	统一返回 { code, data, msg }；code 为 00000（或业务码）表示成功，非成功码时 msg 为可读错误信息
分页	列表接口通用 pageNum / pageSize 入参，返回分页结构与总数
风格	查询多用 POST + 请求体（含复杂筛选条件），遵循统一规范

三、资源地图

资源	路径前缀	说明
认证	api/v1/auth	登录、验证码、二维码登录、令牌刷新
用户	api/v1/users	用户 CRUD（租户管理员/系统管理员视角）
租户	api/v1/tenants	租户 CRUD 与启停（系统管理员）
客户	api/v1/customers	客户 CRUD 与客户用户管理
设备	api/v1/devices	设备 CRUD、网关/子设备、设备分配
设备档案	api/v1/device-profiles	设备档案模板（当前版本未启用）
遥测	api/v1/devices/telemetry	最新值（latest）、历史曲线（history）、删除
告警	api/v1/alarms	告警查询、确认、清除
告警规则	api/v1/calculated-fields	计算字段（告警规则）CRUD
操作日志	api/v1/logs	操作日志查询
文件	api/v1/files	文件上传（设备图片、固件包等）
实时推送	api/v1/sse	SSE 订阅，接收数据与通知推送
API Key	api/v1/account/api-keys	个人 API 密钥管理

四、两个高频接口的示例

查询设备最新遥测

POST /api/v1/devices/telemetry/latest
Content-Type: application/json
Authorization: Bearer <token>

{ "deviceId": "…", "pageNum": 1, "pageSize": 12 }

fields 留空返回该设备全部属性；每个属性各自带 updatedAt（该属性最后上报时间）。

查询历史曲线

POST /api/v1/devices/telemetry/history
Content-Type: application/json
Authorization: Bearer <token>

{
  "deviceId": "…",
  "fields": ["temperature"],
  "from": "2026-10-01T00:00:00Z",
  "to": "2026-10-02T00:00:00Z",
  "interval": "10min",
  "aggregate": "avg"
}

• fields 传逻辑属性名（temperature），不要带类型后缀；
• interval 与 aggregate 成对使用（如 10min + avg），省略则返回原始点；
• 返回按请求的字段逐条给出序列，无数据的字段返回空点集。

五、程序化接入：API Key

个人中心的 API Key 适用于服务器到服务器的调用场景：

1. 在个人中心创建 Key 并设置过期时间；
2. 用 Key 代替账号密码获取访问令牌（具体方式见 Swagger 中认证相关接口）；
3. 后续调用与普通令牌一致。

注意 Key 的最近使用时间会在个人中心展示，定期清理不再使用的 Key。

六、版本与兼容

• 接口前缀带 v1，破坏性变更会升版本号；
• 枚举值以字符串名称传输（如告警等级 CRITICAL、状态 ACTIVE），而非数字——对接时按名称处理；
• 分页上限等细节约束以 Swagger 各接口的参数说明为准。

---

下一步：接入或使用中遇到问题，请查《常见问题排查》。