接入概览

本页用于在正式接入前建立共同模型。它不会展开每个接口的参数，而是解释 WLTE OpenAPI 的核心对象、调用方式、设备状态和命令结果应该如何理解。

如果你只想马上跑通一次调用，可以直接进入快速开始。

WLTE OpenAPI 是什么？

WLTE OpenAPI 面向服务端系统使用，让你的业务系统可以读取、控制和监控 WLTE 设备。

典型能力包括：

• 获取账号下可访问的设备列表
• 读取单台设备状态和外设数据
• 获取设备类型定义和可用操作能力
• 提交继电器、RS485、配置类设备命令
• 查询命令执行结果
• 通过 WebSocket 接收实时设备事件

核心概念

概念	说明
API Client	你在开发者后台创建的调用身份，用于代表一个应用访问 OpenAPI
clientId / clientSecret	API Client 的服务端凭证，用于换取 access token
access token	调用受保护接口时使用的短期访问令牌
Device	账号下可访问的 WLTE 设备
Device Type	设备类型定义，描述设备支持哪些外设和操作能力
Peripheral State	外设状态，例如继电器、数字输入、传感器、模拟量输入等
Command	一次设备操作请求，例如继电器开关、RS485 透传、配置修改
WebSocket Event	设备状态变化、上下线、断电等实时通知

接入模型

你的服务端应保存 clientSecret，并负责获取 access token。浏览器、移动 App 或其他客户端不应直接保存 clientSecret。

REST API 与 WebSocket

REST API 和 WebSocket 不是互相替代的关系，它们承担不同职责。

场景	推荐方式
获取 access token	REST API
查询设备列表	REST API
查询设备类型定义	REST API
提交设备命令	REST API 或 WebSocket，取决于你的连接模型
查询命令结果	REST API
单台设备主动刷新	REST API GET /devices/{deviceId} 或 WebSocket device.state.get
监听上下线、断电、状态变化	WebSocket

首次接入建议先用 REST API 跑通认证、设备列表和单设备状态查询。需要实时事件后，再接入 WebSocket。

更多差异见 REST API 与 WebSocket 如何选择。

设备状态模型

设备状态不是一个单一概念，需要按使用场景区分。

数据	用途	说明
设备列表状态	列表页、看板、后台同步	来自平台已同步的数据，适合批量展示
单设备实时状态	详情页刷新、操作前后确认	服务端会尝试主动刷新单台设备
WebSocket 事件	持续监听状态变化	用于接收上下线、断电、外设变化等实时通知

不要为了监听外设、离线或断电状态，对所有设备做 HTTP 高频轮询。持续监听应使用 WebSocket 事件；断线恢复后，再用设备列表或单设备状态接口重新校准关键状态。

命令模型

设备命令通常会经历两个阶段：

1. 平台接受请求。
2. 设备返回最终确认，或等待超时。

常见状态：

状态	含义
SUCCESS	设备已确认执行结果
TIMEOUT	等待时间内未收到最终确认
FAILED	命令执行失败或被明确拒绝
SENT	命令已发送但还没有最终状态，通常只在查询历史命令时看到

TIMEOUT 不等于设备一定没有执行。设备可能已执行，但确认消息延迟或丢失。对可能产生副作用的命令，不要在超时后盲目重复调用；应先读取设备当前状态再决策。

权限与安全模型

API Client 通过 scope 控制权限。常见规则：

• 只读查询通常需要 device:read
• 设备控制通常需要 device:control
• 设备配置通常需要 device:config
• 设备管理通常需要 device:manage

如果返回 AUTH_SCOPE_DENIED，响应会指明缺少的权限。你需要在开发者后台调整 API Client 权限，并重新获取 access token。

安全边界：

• clientSecret 只能保存在服务端
• 不要把 clientSecret、access token 或 WebSocket ticket 写入前端代码、公开仓库和日志
• 停用或删除 API Client 后，已签发 token 也会被拒绝
• 轮换 secret 后，应更新服务端密钥配置并重新获取 token

推荐接入路径

1. 在开发者后台创建 API Client。
2. 用 Bruno 跑通认证、设备列表和单设备状态查询。
3. 查询设备类型定义，确认目标设备支持的外设和操作能力。
4. 根据业务选择 REST API、WebSocket 或两者结合。
5. 在服务端接入 SDK 或直接调用 HTTP/WebSocket。
6. 上线前检查权限、限流、重试、幂等和日志脱敏。

下一步：进入快速开始。