接口调用与调试

填写参数即可运行接口，并生成多语言对接代码。

02 · 填写参数

请求配置

POST

接口基础地址

可改为您的测试或私有部署地址。

REQUEST

RUN RESULT

请求结果

先获取 AppSecret

调用获取 AppSecret 接口后，将响应中的 data.secret 填入其他 HTTP 接口。

控制命令要一致

cmd 必须与 param 的命令类型一致；定时器使用 cmd=timer 与 param=timer1...。

设备离线判断

查询状态时可检查返回的 update_time；与当前时间相差超过 10 分钟表示设备可能离线。

GETTING STARTED

接入概览

开始对接前，请先确认服务地址、请求格式和账号接入条件。

HTTP 基础地址 https://api.netrelay.cn/

请求体格式 application/x-www-form-urlencoded

MQTT 地址 mqtt://ws.netrelay.cn:1883

接入条件

账号需已在控制平台注册并添加设备，且已联系厂商升级为企业账号。4G 设备流量有限，请合理控制接口调用频率。

PC端访问地址: https://pc.netrelay.cn

移动端访问地址: 微信关注公众号“物联地带”或搜索“物联地带”小程序

POST获取 AppSecret/api/v1/secret

获取账号的 AppSecret(也可以在控制平台登录，在秘钥中心获取获取https://pc.netrelay.cn/my/secret)。除手动重置外，AppSecret 永久有效，其他 HTTP 接口均需携带该参数。

请求参数

参数	类型	必填	说明
`username`	string	是	物联地带注册用户名
`password`	string	是	注册用户名对应密码

响应字段

字段	类型	说明
`data.secret`	string	用户 AppSecret

响应示例

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

GET获取设备/api/v1/list

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

请求参数

参数	类型	必填	说明
`appsecret`	string	是	通过获取 AppSecret 接口取得

响应字段

字段	类型	说明
`sn`	string	设备序列号，唯一 ID
`ver`	string	设备型号；RN 后两位数字代表通道数量
`name`	string	设备名称
`iccid`	string	设备物联网卡 ICCID
`relays`	array	设备通道名称
`inputs`	array	设备输入名称

响应示例

{
  "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

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

请求参数

参数	类型	必填	说明
`appsecret`	string	是	通过获取 AppSecret 接口取得
`sn`	string	是	设备序列号

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

POST控制设备/api/v1/control

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

请求参数

参数	类型	必填	说明
`appsecret`	string	是	通过获取 AppSecret 接口取得
`sn`	string	是	设备序列号，唯一 ID
`param`	string	是	设备控制命令，格式参考通用命令
`cmd`	string	是	命令标志；与 param 的命令类型保持一致

主要响应字段

字段	类型	说明
`data.cmd`	string	设备返回的命令类型
`data.output`	string	输出通道状态
`data.input`	string	输入通道状态
`data.sn`	string	设备序列号
`data.update_time`	int	最近心跳毫秒时间戳，仅 `state=?` 返回

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

POST配置消息推送/api/v1/webhook/config

配置客户服务器的 POST 回调地址和需要监听的设备。设备 MQTT 消息到达平台后会进入异步队列，不占用原控制接口的同步等待时间。

配置接口

请求体同时支持 application/json 和 application/x-www-form-urlencoded。

参数	类型	必填	说明
`appsecret`	string	是	当前企业账号的 AppSecret
`callback_url`	string	启用时是	接收消息的 HTTP/HTTPS POST 地址；本地开发环境允许 localhost 和内网地址
`devices`	string/array	启用时是	JSON 数组或英文逗号分隔的设备 SN，仅允许当前账号设备
`enabled`	boolean	否	默认 true；设为 false 可暂停推送
`rotate_secret`	boolean	否	设为 true 时重新生成签名密钥

appsecret=YOUR_APPSECRET&callback_url=https%3A%2F%2Fexample.com%2Fnetrelay%2Fwebhook&devices=SN001%2CSN002&enabled=true

回调地址验证

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

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

// 客户接口响应
{ "challenge": "RANDOM_CHALLENGE" }

平台回调

平台以 application/json POST 消息；客户接口返回任意 2xx 状态即视为成功，失败会按服务端配置重试。

连续失败会自动停用

每条消息完成全部重试后仍失败，才计入连续失败。期间任意一次推送成功都会清零计时；达到连续失败7天后，系统自动将该 Webhook 设为停用，客户重新启用时需要再次完成地址验证。

{
  "event_id": "mabc123-...",
  "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(secret, timestamp + "." + 原始请求体)，请求头值带 sha256= 前缀。客户应按 event_id 幂等处理重试消息。

GET读取推送配置/api/v1/webhook/config

读取当前 AppSecret 对应账号的 Webhook 状态、回调地址、监听设备和签名密钥。

请求参数

参数	位置	必填	说明
`appsecret`	query	是	当前企业账号的 AppSecret

GET /api/v1/webhook/config?appsecret=YOUR_APPSECRET

响应字段

字段	类型	说明
`data.enabled`	boolean	是否启用消息推送
`data.callback_url`	string	客户 POST 回调地址
`data.devices`	array	已监听的设备 SN
`data.signing_secret`	string	客户服务器校验 Webhook 签名使用的密钥
`data.verified_at`	string	回调地址最近验证通过时间
`data.failure_since`	string	当前连续失败周期的开始时间；推送成功后清空
`data.last_failure_at`	string	最近一次完成全部重试后仍失败的时间
`data.disabled_reason`	string	`continuous_delivery_failure` 表示因连续失败被自动停用
`data.auto_disable_after_days`	number	平台设置的连续失败自动停用天数，0 表示关闭自动停用
`data.updated_at`	string	配置最后更新时间，ISO 8601 格式

{
  "code": 0,
  "message": "成功",
  "data": {
    "enabled": true,
    "callback_url": "https://example.com/netrelay/webhook",
    "devices": ["SN001", "SN002"],
    "signing_secret": "WEBHOOK_SIGNING_SECRET",
    "verified_at": "2026-10-10T07:59:59.000Z",
    "failure_since": "",
    "disabled_reason": "",
    "auto_disable_after_days": 3,
    "updated_at": "2026-10-10T08:00:00.000Z"
  }
}

POSTWebhook 异步控制/api/v1/webhook/control

向已加入 Webhook 监听列表的设备下发命令。接口只确认命令已交给 MQTT 发布，不等待设备返回；设备响应会随后 POST 到配置的回调地址。

发送成功不等于设备执行成功

code=0 仅表示 MQTT 消息已发送。最终设备结果以 Webhook 回调内容为准。

请求参数

请求体支持 application/json 和 application/x-www-form-urlencoded。

参数	类型	必填	说明
`appsecret`	string	是	当前企业账号的 AppSecret
`sn`	string	是	必须属于账号且已加入 Webhook 监听列表
`param`	string	是	设备控制命令，例如 `state=?` 或 `setr=10xx`
`type`	int	否	默认 0；设为 1 时 param 为包含 cmd 的 JSON 字符串

appsecret=YOUR_APPSECRET&sn=SN001&param=state%3D%3F

响应示例

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

POSTWebhook 异步批量控制/api/v1/webhook/multiControl

向多个已加入 Webhook 监听列表的设备下发同一条命令。接口只等待 MQTT 发布结果，不等待设备执行结果；每台设备的响应会分别推送到已配置的回调地址。

提交前会校验全部设备

只要有一个设备不属于当前账号或未加入 Webhook 监听列表，整批请求都会被拒绝，不会向其他设备下发命令。

请求参数

请求体支持 application/json 和 application/x-www-form-urlencoded。

参数	类型	必填	说明
`appsecret`	string	是	当前企业账号的 AppSecret
`sns`	string/array	是	JSON 数组或英文逗号分隔的设备 SN；系统会自动去重
`param`	string	是	所有设备共同执行的控制命令，例如 `state=?` 或 `setr=10xx`
`type`	int	否	默认 0；设为 1 时 param 为包含 cmd 的 JSON 字符串

appsecret=YOUR_APPSECRET&sns=SN001%2CSN002&param=state%3D%3F

响应示例

{
  "code": 0,
  "message": "批量发送成功，设备响应将通过Webhook推送",
  "data": {
    "status": "sent",
    "total": 2,
    "sent": 2,
    "busy": 0,
    "failed": 0,
    "results": [
      { "sn": "SN001", "status": "sent" },
      { "sn": "SN002", "status": "sent" }
    ]
  }
}

当部分设备忙碌或 MQTT 发布失败时，接口返回 code=10005、data.status=partial，请根据 data.results 中每台设备的状态决定是否重试。

CMD通用命令state · device · setr · timer

cmd	param	说明
`state`	`state=?`	查询状态
`device`	`device=?`	查询设备型号
`setr`	`setr=控制内容`	设置设备输出通道
`timer`	`timer1=时间/星期/控制内容`	设置 1–16 号定时器

setr 控制字符

0关闭

1开启

2点触，1 秒后自动关闭

3翻转当前状态

4与相邻通道互锁

x不动作

通道数必须一致

控制字符串长度必须等于设备实际通道数，例如 4 通道设备使用 setr=xxxx，否则可能出现随机控制。

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 执行动作。

STATE设备离线判断update_time · code 10008

发送 state=? 时，平台优先读取统一的设备心跳缓存；默认 10 分钟内的状态可直接返回。
缓存缺失、损坏或超过离线阈值时，平台会向设备重新查询一次。补查成功后刷新 update_time；补查失败才返回错误码 10008，并保留最近一次更新时间。

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

MQTTMQTT 长连接mqtt://ws.netrelay.cn:1883

配置	值	说明
地址	`mqtt://ws.netrelay.cn:1883`	平台固定 MQTT 地址
Client ID	随机且唯一	每个连接使用独立 ID
username	物联地带账号	平台注册用户名
password	物联地带密码	平台注册密码
QoS	`0`	订阅和发布均设置为 0

主题

订阅设备状态SN + state例如 teststate

发送控制命令SN + ctr例如 testctr，message 为通用命令的 param

使用在线调试配置 MQTT 长连接

填写连接账号、设备 SN 和操作类型，即可生成 Node.js、Go、Python、Java 或 C# 对接代码。

ERR错误码0 · 10001–10010

错误码	描述
`0`	成功
`10001`	请求速度太快
`10002`	非法 AppSecret
`10003`	参数异常
`10004`	SN 错误或设备不存在
`10005`	控制失败，请重试（设备网络异常等）
`10006`	参数错误，cmd 与 param 中的命令不一致
`10007`	非企业账户，请联系厂商升级为企业账号
`10008`	设备离线
`10010`	今日额度已经用完

接口支持经理：15061962326 客服：16605298829

接口调用与调试

请求配置

请求结果

对接示例

先获取 AppSecret

控制命令要一致

设备离线判断

请求参数

响应字段

响应示例

请求参数

响应字段

响应示例

请求参数

请求参数

主要响应字段

配置接口

回调地址验证

平台回调

签名校验

请求参数

响应字段

请求参数

响应示例

请求参数

响应示例

setr 控制字符

timer 格式

主题