接入流程

第三方系统接入平台，分为申请 → 联调 → 上线三个阶段。本文说明每个阶段要做什么、产出什么。

流程总览

① 申请账号            ② 获取凭证            ③ 联调             ④ 上线
联系运营方提供资料  →  调用登录接口拿 token  →  按文档调各接口  →  切换生产配置
   ↓                    ↓                     ↓                  ↓
客户主体信息          拿到 customerId        验证数据正确性      正式流量接入
使用场景说明          拿到 token             验证控制可用性      建立监控告警
预计调用量                                  处理错误码

阶段一：申请账号

平台账号由运营方人工开通（文档注明：「使用此文档前，请先申请账户」）。

需要提供：

资料	说明	是否必须
客户主体名称	用于创建 customerId 与账号	必须
对接联系人	姓名 / 电话 / 邮箱	必须
使用场景说明	例如「把温室环境数据同步到我们的种植管理系统」	必须
预计接入的站点	站点名称或 ID；决定账号可见的数据范围	必须
预计调用量	QPS / 日请求量，用于容量评估	建议
是否需要控制权限	仅查询 / 允许下发控制指令	必须

控制权限默认不开放

设备控制类接口会真实驱动现场物理设备。默认只开通查询权限； 需要控制能力时，请在申请时明确说明，并由运营方评估后开通。

开通后你会拿到：

• 登录 URL（见 环境与域名说明）
• 账号 username
• 初始密码 password
• 所属客户 ID customerId（登录返回，用于核对数据归属）

账号安全

• 请勿把账号密码硬编码进客户端或前端页面
• 请勿把账号借给第三方使用；一个对接方一个账号，便于审计与限流
• 密码泄露时立即联系运营方重置

阶段二：获取凭证

调用 POST /api/account/sign-in 换取访问凭证 token，随后所有接口在请求头带上：

Authorization: Bearer <token>

完整说明见：

• 获取访问凭证
• 使用凭证（有效期与过期处理）

建议的实现方式

在你的服务端维护一个 token 缓存：

1. 首次调用前登录一次，缓存 token 与其过期时间
2. 每次业务请求前检查剩余有效期，不足则提前重新登录
3. 收到 401 时立即重新登录并重试一次

不要把「每次请求都登录一次」写进代码——登录接口本身有频率限制且性能开销更大。

阶段三：联调

按功能模块推进，建议顺序：

顺序	内容	涉及接口
1	打通鉴权	/api/account/sign-in
2	建立站点/设备的本地映射	/api/station、/api/device
3	拉实时数据并核对与平台页面是否一致	/api/sensor-data
4	拉历史数据、验证曲线	/api/weather-data/list、/api/weather-data/avg
5	查在线状态并做掉线告警	/api/mqtt-client-status、/api/control/mqtt
6	视频接入（如需）	/api/video-data/list
7	读控制参数、核对位语义	/api/device_status、/api/get-value
8	**（需授权）**下发控制指令	/api/set-value
9	实时推送替换轮询（如需）	/ws/device-status 等

联调检查清单

• [ ] 所有接口都带上了 Authorization 请求头
• [ ] 站点/设备 ID 使用接口返回的 id，设备指令使用 code
• [ ] 时间戳统一使用毫秒级 Unix 时间戳（见 通用说明）
• [ ] 分页参数 pageSize 不超过 100
• [ ] 控制类接口在测试设备上验证通过后再接生产
• [ ] 对 401 / 403 / 404 分别做了处理，而不是一律重试
• [ ] 把 /api/get-value 的返回值解析逻辑（从右往左数位）写进了单元测试

阶段四：上线

事项	建议
域名切换	测试与生产使用同一套域名，无需改代码；关键是账号权限
调用频率	查询类接口建议 ≥ 30 秒一次；实时性要求高时改用 WebSocket
监控告警	至少对「登录失败率」「非 200 响应占比」「数据为空」三项设告警
日志留存	记录 requestId，便于向平台方追溯问题
凭证轮换	密码变更后同步更新配置；变更窗口内旧 token 可能短暂不可用

关于 requestId

平台大部分接口的返回体都带 requestId（UUID）。报障时请把 requestId 一并提供， 平台方可以据此在服务端日志中定位该次请求，排查效率远高于只描述「调不通」。

下一步

• 想马上跑通第一个请求 → 快速开始
• 想确认域名与网络要求 → 环境与域名说明
• 直接看接口 → 接口文档