变更记录
本页记录文档与接口的版本变更。对接方在升级前请先查看本页，确认是否有影响你的改动。
v3.6.0 当前版本
接口契约
| 项 | 说明 |
|---|---|
| 接口地址 | 无变化 |
| 请求方法 | 无变化 |
| 请求参数 | 无变化 |
| 返回字段 | 无变化 |
本版只改文档，接口行为无变化，对接方无需改动代码。
文档
★ address 控制地址全量表 重写 ★
| 改进 | 说明 |
|---|---|
| 位定义完整展开 | 每个功能项都写明"第 1 位 = 什么、第 2 位 = 什么"，不再用占位表述 |
| 补充示例 | 每一类控制（5 位开窗类 / 4 位开关类 / 3112 四路输出 / 上层风机 / 指定位置 / 电机停止 / 灌溉计划）都给出可直接复制的请求 JSON |
| 补齐 address | 带 address 数值的功能项从 16 个增加到 26 个，另附补齐方法 |
| 明确指定位置用法 | 区分「切模式」与「下发开度」两步，给出两段完整请求示例 |
全站示例数据统一：所有示例中的设备名称、设备编码统一为中性示例值，便于对照替换。
v3.5.0
接口契约
| 项 | 说明 |
|---|---|
| 接口地址 | 无变化 |
| 请求方法 | 无变化 |
| 请求参数 | 无变化 |
| 返回字段 | 无变化 |
本版只改文档，接口行为无变化，对接方无需改动代码。
文档
address 控制地址全量表 完善：
- 带
address数值的功能项扩充到 26 个，每项附位宽与位定义 - 控制值速查拆分为三类位串（5 位位置类 / 4 位开关类 /
3112四路输出），便于按控制场景查找 - 补充「指定位置」两步操作的说明
- 补充「哪些功能项共用同一类位定义」的说明
若你按旧版文档硬编码过 address
「开窗 / 遮阳幕 / 保温帘 / 外翻窗」这一组的 address 请以本版文档为准。
v3.4
接口契约
| 项 | 说明 |
|---|---|
| 接口地址 | 无变化 |
| 请求方法 | 无变化 |
| 请求参数 | 无变化 |
| 返回字段 | ★ 历史数据 的每条因子读数新增 breakdown（该测点是否故障）；同时 alarm 的含义扩展为「数值超出量程 或 该测点故障」★ |
兼容性说明
- 新增字段，老对接方无需改动（原有字段名称、类型、含义都不变）。
breakdown只对 2026-10-08 之后的记录存在；更早的历史不可回填， 取不到时按false处理。- ⚠️
alarm的行为有变化：以前只在"数值超出量程"时为true， 现在"该测点故障"也会为true⇒ 若你原来用它判断量程告警，报警会更早出现。 需要区分「超量程」与「故障」时请改用breakdown。 - ★ 判断故障请用
name（完整因子名）匹配，不要用icon—— 同一因子的多路（atc/atc_1/atc_2）icon都是atc★
文档
- 历史数据：字段表新增
breakdown，补充alarm语义说明与多路故障示例。
v3.0
文档
首个正式版本。覆盖数据查询、设备控制、实时推送三类开放接口，共 13 个 HTTP 接口与 3 个 WebSocket 通道。
内容组织：
| 章节 | 内容 |
|---|---|
| 一、接入指南 | 快速开始、接入流程、环境与域名说明 |
| 二、认证鉴权 | 获取访问凭证、使用凭证 |
| 三、接口规范 | 通用说明、错误码 |
| 四、数据查询 | 站点、设备、实时数据、历史数据、聚合曲线、视频地址、在线状态（7 个接口） |
| 五、设备控制 | 读取控制参数、读取地址值、批量读控制参数、控制设备（4 个接口） |
| 六、实时推送 | WebSocket 接口（3 个通道） |
| 七、附录 | address 控制地址全量表、因子对照表、设备类型映射表 |
文档中的接口地址、请求参数、返回字段、错误码，均以真实调用结果为准。
接口契约
| 项 | 说明 |
|---|---|
| 接口地址 | 无变化 |
| 请求方法 | 无变化 |
| 请求参数 | 无变化 |
| 返回字段 | 无变化 |
本文档不做接口变更
本文档只描述平台当前生效的接口行为。接口如有变更，会先在本页登记。
接口清单
数据查询
| # | 接口 | 方法 | 域名 |
|---|---|---|---|
| 1 | /api/account/sign-in | POST | 业务 |
| 2 | /api/station | GET | 业务 |
| 3 | /api/device | GET | 业务 |
| 4 | /api/sensor-data | GET | 实时控制 |
| 5 | /api/weather-data/list | GET | 业务 |
| 6 | /api/weather-data/avg | GET | 业务 |
| 7 | /api/video-data/list | GET | 业务 |
设备控制与状态
| # | 接口 | 方法 | 域名 |
|---|---|---|---|
| 8 | /api/mqtt-client-status | GET | 实时控制 |
| 9 | /api/control/mqtt | GET | 业务 |
| 10 | /api/device_status | GET | 实时控制 |
| 11 | /api/get-value | GET | 实时控制 |
| 12 | /api/set-value/flush | GET | 实时控制 |
| 13 | /api/set-value | POST | 实时控制 |
实时推送
| 通道 | 协议 | 域名 |
|---|---|---|
/ws/device-status | WebSocket | 实时控制 |
/ws/sensor-data/weather-station-data/{deviceCode} | WebSocket | 实时控制 |
/ws/set-value | WebSocket | 实时控制 |