物联地带 API 接入指南：Webhook 异步控制、设备查询与 MQTT

将现场设备接入客户业务系统，需要先取得设备列表，再读取状态、下发命令并处理异常。物联地带提供HTTP接口和MQTT长连接：HTTP用于鉴权、设备查询与控制，MQTT用于订阅设备状态和发送控制命令。

本次更新：命令异步下发，设备结果主动回传

物联地带API新增Webhook消息推送与异步控制。客户系统提交命令后，无需持续等待设备返回；平台将设备响应推送到指定服务器，由业务系统接收结果、更新状态并记录执行过程。

新增能力	接入价值
异步下发命令	命令提交与设备回传分开处理，业务请求无需等待设备响应。
设备消息主动推送	监听指定设备的MQTT消息，减少为获取新消息而反复发起的查询。
地址验证与消息签名	启用前验证回调地址，接收时校验消息签名，核对来源与内容完整性。
失败重试与状态查询	查询推送状态、失败周期及停用原因，便于发现和处理回调异常。

查看异步控制接口文档 ↗

三种接入方式，匹配不同业务流程

接入方式	处理流程	适用需求
HTTP同步控制	通过原control接口查询状态或下发命令，处理同步响应。	单次查询、单次控制和现有系统接入。
Webhook异步控制	提交命令后由平台向客户服务器回传设备消息。	需要把设备响应接入业务流程、状态记录或运维系统。
MQTT长连接	客户系统保持连接，订阅状态主题并向控制主题发布命令。	具备MQTT客户端能力、需要持续订阅设备消息的系统。

原HTTP接口和MQTT主题继续使用。Webhook异步控制需先配置并验证回调地址，再将目标设备加入监听列表。接口返回“发送成功”表示命令已交给MQTT发布；设备执行结果以回调内容及对应型号协议为准。

接入条件与调用顺序

接口基础地址为 https://api.netrelay.cn/，原HTTP接口的POST请求体采用 application/x-www-form-urlencoded；新增Webhook配置与异步控制接口同时支持JSON。账号需已注册、已添加设备，并开通企业账号。4G设备的接口调用频率需结合流量和账号额度安排。

1. 使用平台注册用户名和密码获取AppSecret。
2. 携带AppSecret读取账号下的设备列表，取得设备序列号SN、型号与通道信息。
3. 按SN查询设备，或通过控制接口读取状态、下发通道及定时命令。
4. 读取返回码与状态更新时间，区分鉴权、参数、网络和设备离线问题。
5. 按业务流程选择Webhook回调或MQTT长连接接收设备消息；Webhook异步控制先完成地址验证和设备监听配置。

查看API接口文档 · 平台API与系统接入 · 物联地带平台介绍

获取 AppSecret

POST /api/v1/secret

获取账号的 AppSecret。除手动重置外，AppSecret 永久有效，其他 HTTP 接口均需携带该参数。

请求参数

响应字段

响应示例

{
  "code": 0,
  "message": "成功",
  "data": { "secret": "YOUR_APPSECRET" }
}

获取设备列表

GET /api/v1/list

获取当前账号下的设备序列号列表以及设备、通道和输入名称。

请求参数

响应字段

响应示例

{
  "code": 0,
  "message": "成功",
  "data": [{
    "sn": "G85c8922xxxxxx",
    "ver": "ZMRN0804-G8L",
    "name": "设备名称示例",
    "iccid": "123456789",
    "relays": [{ "index": 1, "name": "输出1" }],
    "inputs": [{ "index": 1, "name": "输入1" }]
  }]
}

查询设备信息

GET /api/v1/getInfo

查询账号下指定设备的信息，响应字段与“获取设备”接口一致。

请求参数

返回 sn、ver、name、iccid、relays 和 inputs。

读取状态与控制设备

POST /api/v1/control

操作单个设备，支持控制、查询设备和读取状态。响应数据为设备协议内容，不同设备可能返回不同字段。

请求参数

主要响应字段

{
  "code": 0,
  "message": "请求成功",
  "data": {
    "cmd": "state",
    "output": "10000001",
    "input": "0000",
    "sn": "G85xxxxxxx9bf9",
    "update_time": 1700719306722
  }
}

配置Webhook消息推送

POST /api/v1/webhook/config 配置客户服务器的回调地址和监听设备。该接口支持 application/json 与 application/x-www-form-urlencoded。

参数	类型	要求与说明
appsecret	string	必填，当前企业账号的AppSecret。
callback_url	string	启用时必填，接收消息的HTTP/HTTPS POST地址。
devices	string / array	启用时必填，JSON数组或英文逗号分隔的设备SN，仅允许当前账号设备。
enabled	boolean	默认true；false暂停推送。
rotate_secret	boolean	true时重新生成签名密钥。

{
  "appsecret": "YOUR_APPSECRET",
  "callback_url": "https://example.com/netrelay/webhook",
  "devices": ["SN001", "SN002"],
  "enabled": true
}

回调地址验证

首次启用、更换回调地址或重新启用时，平台发送 webhook.verify POST请求。客户服务器返回HTTP 2xx，并在JSON中原样返回收到的 challenge；验证失败时配置不会保存。

// 平台发送
{ "event": "webhook.verify", "challenge": "RANDOM_CHALLENGE" }

// 客户服务器响应
{ "challenge": "RANDOM_CHALLENGE" }

异步下发设备命令

POST /api/v1/webhook/control 向当前账号下、已加入Webhook监听列表的设备发送命令。请求体支持JSON与表单编码。接口确认MQTT发布后返回，设备响应随后通过Webhook推送。

参数	类型	要求与说明
appsecret	string	必填，当前企业账号的AppSecret。
sn	string	必填，属于当前账号且已在监听列表中的设备SN。
cmd	string	必填，命令标志，与param中的命令一致。
param	string	必填，如state=?或setr=10xx；通道控制内容按实际通道数设置。
type	int	默认0；设为1时，param为包含cmd的JSON字符串。

{
  "appsecret": "YOUR_APPSECRET",
  "sn": "SN001",
  "cmd": "state",
  "param": "state=?"
}

成功响应：

{
  "code": 0,
  "message": "发送成功，设备响应将通过Webhook推送",
  "data": { "status": "sent", "sn": "SN001", "cmd": "state" }
}

code=0表示命令已发送，不代表设备已经执行。业务系统应根据设备回调中的命令类型、设备SN及协议字段更新执行状态。

接收设备消息与校验签名

平台以 application/json POST设备消息，客户服务器返回任意HTTP 2xx即视为接收成功。事件包含 event_id、event、received_at、topic、sn和 data。

{
  "event_id": "EVENT_ID",
  "event": "mqtt.message",
  "received_at": "2026-10-10T08:00:00.000Z",
  "topic": "SN001state",
  "sn": "SN001",
  "data": { "cmd": "state", "sn": "SN001", "output": "1000" }
}

使用配置响应中的 data.signing_secret 校验签名。请求头包含 X-Netrelay-Event-Id、X-Netrelay-Timestamp与 X-Netrelay-Signature。

HMAC-SHA256(signing_secret, timestamp + "." + 原始请求体)
X-Netrelay-Signature: sha256=计算得到的签名

签名计算使用收到的原始请求体，不能用重新序列化的JSON替代。按 event_id 记录处理结果，同一事件再次推送时避免重复执行业务动作。

读取推送状态与处理失败

GET /api/v1/webhook/config?appsecret=YOUR_APPSECRET 读取当前账号的推送配置。AppSecret与签名密钥由客户服务端保存和使用。

响应字段	用途
data.enabled / data.callback_url / data.devices	确认推送开关、目标地址与监听设备。
data.signing_secret	校验回调签名。
data.verified_at / data.updated_at	查看地址验证时间和配置更新时间。
data.failure_since / data.last_failure_at	查看连续失败周期开始时间，以及最近一次全部重试后仍失败的时间。
data.disabled_reason	continuous_delivery_failure表示因连续推送失败而自动停用。
data.auto_disable_after_days	连续失败自动停用的配置天数，0表示关闭自动停用。

推送失败按服务端配置重试。一条消息完成全部重试仍失败后，才计入连续失败；期间任意一次推送成功都会清零计时。达到配置的连续失败时长后自动暂停推送，重新启用时再次验证回调地址。

客户系统可将设备消息用于状态展示、业务记录与运维告警。重试消息可能重复到达，接收端应先验签，再按事件编号幂等处理。

通道控制与定时命令

setr 控制字符

字符	通道动作
0	关闭
1	开启
2	点触，1秒后自动关闭
3	翻转当前状态
4	与相邻通道互锁
x	保持原状态，不动作

setr=1x          // 2 通道：开启第 1 路，第 2 路不动作
setr=11          // 2 通道：同时开启两路
setr=20          // 2 通道：点触第 1 路，关闭第 2 路
setr=1xxxxxxxx0  // 10 通道：开启第 1 路，关闭第 10 路

timer 格式

cmd 固定为 timer，param 使用 timer序号=HHMMSS/星期掩码/控制内容。序号范围为 1–16，星期掩码按周一至周日排列，1 表示开启，0 表示关闭。

cmd: timer
param: timer4=173040/0101010/x11xxxxxxx

示例表示定时器 4 在周二、周四、周六 17:30:40 执行；10 通道设备的第 2、3 路开启。请勿设置 00:00:00 执行动作。

设备离线判断

1. 发送 state=?，比较响应中的 update_time 与当前时间；相差超过 10 分钟可判断设备离线。
2. 接口请求时，如果设备最近更新数据超过 10 分钟，系统返回错误码 10008，并在 data.update_time 中给出最近更新时间。

{
  "code": 10008,
  "message": "设备离线",
  "data": {
    "cmd": "offline",
    "sn": "G85xxxxxxx9bf9",
    "update_time": 1700719306722
  }
}

MQTT 长连接与设备主题

主题

设备主题

用途	主题	消息
订阅设备状态	设备SN直接拼接state	设备状态数据
发送控制命令	设备SN直接拼接ctr	通用命令的param内容

例如设备SN为 test，状态主题为 teststate，控制主题为 testctr，中间不加斜杠。自建MQTT服务可联系平台获取接入支持。

接口错误码

常见问题

AppSecret是否需要每次请求重新获取？

不需要。除手动重置外，AppSecret持续有效；其他HTTP接口携带appsecret参数。

查询设备信息与查询状态有什么区别？

getInfo返回设备型号、名称、通道等基础信息。读取输入输出状态时，通过control接口发送cmd=state、param=state=?。

控制字符串能否在不同通道数设备间直接复用？

不能。setr的控制字符串长度必须等于设备实际通道数。x表示该通道不动作，0关闭，1开启。

MQTT是否使用AppSecret登录？

MQTT使用物联地带账号和密码，Client ID需随机且唯一，订阅和发布QoS均为0。AppSecret用于HTTP接口。

Webhook异步控制与原control接口有什么区别？

原control接口用于同步请求；webhook/control确认MQTT发布后返回，设备结果通过已配置的Webhook地址推送。原HTTP接口和MQTT主题继续使用。

异步接口返回code=0，是否表示设备已经执行？

不表示。code=0只确认命令已交给MQTT发布。最终结果根据设备回调及对应型号协议判断。

如何避免重试消息重复执行业务动作？

校验X-Netrelay-Signature后，按event_id记录并去重。同一事件再次到达时，不重复执行已经完成的业务动作。

推送失败后如何恢复？

读取webhook/config检查enabled、failure_since及disabled_reason，处理回调异常后重新启用；重新启用需再次完成回调地址验证。

接口文档与项目对接

接口路径、参数和通用命令可在API接口文档中查阅。设备返回字段按对应型号协议使用，涉及客户系统接入、物联网平台或私有化部署，可联系贞明电子：16605298829。