W76M(WiFi+蓝牙mini门禁控制器)API

W76M（WiFi+蓝牙 mini 门禁控制器）API

概述

W76M 是单门 WiFi+蓝牙门禁控制器，设备序列号以 W76M 开头。本文档说明设备注册、远程开门、门磁与继电器配置、WiFi 配置、在线查询、OTA 和蓝牙应急开门协议。

API 基础地址：https://wdev.wmj.com.cn
云端命令地址：POST https://wdev.wmj.com.cn/deviceApi/send
当前回调维护版本：76.0.8，适用 W76M 硬件 1.0.0、软件 76.0.x 版本线。
76.0.5 支持 set_ext_button 及开门按钮事件；旧版本使用前应通过 getdevinfo 确认返回 ext_button_enabled 字段。

除单独标明的地址外，下列云端命令均使用 POST https://wdev.wmj.com.cn/deviceApi/send，请求头为 Content-Type: application/json。

云端接口的 code=0 表示平台请求成功；设备命令还应检查 data.info.code。涉及配置变更时，建议再次调用 getdevinfo 回读最终状态。

点击下面的序号展开

1.注册设备

简要描述

将 W76M 设备绑定到开发者账号。注册成功后才能调用设备控制接口。

请求URL

https://wdev.wmj.com.cn/deviceApi/register

请求方式

POST

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}"
}

参数名	必选	类型	说明
`app_id`	是	string	开发者 app_id
`app_secret`	是	string	开发者 app_secret
`device_sn`	是	string	W76M 设备序列号

返回示例

{
  "code": 0,
  "msg": "注册成功"
}

2.远程开门

简要描述

按设备当前配置的继电器脉冲时长触发开门。脉冲时长通过 set_relay 设置。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "open",
    "info": {
      "sn": "{{device_sn}}"
    }
  }
}

参数名	必选	类型	说明
`data.cmd_type`	是	string	固定为 `open`
`data.info.sn`	否	string	传入时必须与目标设备序列号一致

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "type": 1,
    "cmd_type": "open",
    "info": {
      "doorstate": 0,
      "err_code": 0,
      "code": 0,
      "msg": ""
    }
  }
}

备注

doorstate 是门磁输入状态，不等同于继电器动作反馈。
若设备处于常开模式，开门命令只进行提示，不重复改变常开状态。

3.获取设备信息

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "getdevinfo",
    "info": {}
  }
}

主要返回字段

字段	类型	说明
`sw_ver`	string	软件版本
`hw_ver`	string	硬件版本
`project`	string	固定为 `W76M`
`net_type`	string	固定为 `wifi`
`sta_ssid`	string	当前 WiFi 名称
`rssi`	number	WiFi 信号强度，单位 dBm
`doorstate`	number	门磁状态：`0` 或 `1`
`switch_state`	number	当前继电器输出状态
`nonc`	number	`0`=常闭模式，`1`=常开模式
`relay1`	number	开门继电器脉冲时长，单位毫秒
`device_sound`	number	蜂鸣器：`0`=关闭，`1`=启用
`ext_button_enabled`	number	开门按钮：`0`=停用，`1`=启用；仅支持该字段的固件返回
`ble_advertising`	boolean	蓝牙是否正在广播
`mqtt_connected`	boolean	MQTT 是否已连接
`free_heap`	number	当前空闲堆内存
`min_free_heap`	number	本次启动后的最小空闲堆内存
`uptime_ms`	number	本次启动后的运行时间，单位毫秒
`code`	number	设备业务码，`0` 表示成功
`msg`	string	设备业务说明

备注

设备信息可能包含配置字段，业务系统不应将完整原始响应写入公开日志。

4.获取门状态

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "getdoorstate",
    "info": {}
  }
}

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd_type": "getdoorstate",
    "info": {
      "doorstate": 0,
      "err_code": 0,
      "code": 0,
      "msg": ""
    }
  }
}

5.设置常开/常闭模式

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_nonc",
    "info": {
      "type": 0
    }
  }
}

参数名	必选	类型	说明
`data.info.type`	是	number	`0`=常闭模式，`1`=常开模式

返回说明

成功时 data.info.nonc 返回最终模式。配置会持久保存。

6.设置继电器脉冲时长

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_relay",
    "info": {
      "relay1": 1000
    }
  }
}

参数名	必选	类型	取值范围	说明
`data.info.relay1`	是	number	`100`～`60000`	开门继电器脉冲时长，单位毫秒

成功时 data.info.relay1 返回保存后的时长。

7.设置蜂鸣器

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_device_sound",
    "info": {
      "device_sound": 1
    }
  }
}

参数名	必选	类型	说明
`data.info.device_sound`	是	number	`0`=关闭提示音，`1`=启用提示音

8.远程配置WiFi

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_wifi",
    "info": {
      "ssid": "ExampleWiFi",
      "passwd": "example-password"
    }
  }
}

参数名	必选	类型	说明
`data.info.ssid`	是	string	2.4GHz WiFi 名称，最长32字节
`data.info.passwd`	是	string	WiFi 密码；开放网络可传空字符串，最长63字符

备注

兼容字段 password，新接入建议统一使用 passwd。
此接口只保存 WiFi 配置，不立即切换当前连接。保存成功后，在允许设备短暂离线的维护窗口调用 restart 使新配置生效，再查询在线状态并回读 sta_ssid；不要以保存应答代替联网结果。

9.修改设备密码

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_pwd",
    "info": {
      "device_pwd": "new-device-password",
      "admin_pwd": "new-admin-password"
    }
  }
}

参数名	必选	类型	说明
`data.info.device_pwd`	否	string	本地应急开门密码，最长31字符
`data.info.admin_pwd`	否	string	配网页面管理密码，最长31字符

至少传入一个需要修改的密码。密码属于敏感信息，禁止记录在公开日志中。

10.设置开门按钮

版本要求

当前 76.0.5 支持此协议。旧版本应先检查 getdevinfo 是否返回 ext_button_enabled；不返回时请先升级，不能假定接口可用。

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_ext_button",
    "info": {
      "enable": 1
    }
  }
}

参数名	必选	类型	说明
`data.info.enable`	是	number	只接受数字 `0` 或 `1`

行为说明

1：启用短按开门和 ext_button 事件。
0：停用短按开门和事件；不影响长按5秒进入配网及长按15秒恢复出厂。
配置持久保存。成功后应调用 getdevinfo 校验 ext_button_enabled。

11.开门按钮主动事件

启用按钮后，每次确认短按上报一次 type=2 事件：

{
  "device_sn": "{{device_sn}}",
  "type": 2,
  "cmd_type": "ext_button",
  "info": {
    "event": "press",
    "state": 1,
    "uptime_ms": 123456,
    "event_uid": "{{device_sn}}-2-123456-1"
  }
}

业务系统应使用 event_uid 做幂等去重。设备离线时本地按钮开门不受影响，但事件不会补发。

12.重启设备

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "restart",
    "info": {}
  }
}

设备先返回应答，约1.2秒后重启。应通过在线状态和 getdevinfo.uptime_ms 确认重启结果。

13.OTA固件升级

适用W76M硬件1.0.0，目标版本76.0.8。POST https://wdev.wmj.com.cn/deviceApi/send，Content-Type: application/json。

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_ota",
    "info": {
      "hw_ver": "1.0.0",
      "sw_ver": "76.0.8",
      "url": "http://fm.wmj.com.cn/ota/W76M/W76M_v76.0.8_ota.bin"
    }
  }
}

目标版本必须高于当前版本。ACK仅表示升级受理；重启上线后通过getdevinfo回读版本并验证业务。

14.查询在线状态

请求URL

https://wdev.wmj.com.cn/deviceApi/getOnLine

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}"
}

返回示例

{
  "code": 0,
  "data": {
    "online": 1
  },
  "msg": "查询成功"
}

部分旧版服务可能返回兼容字段 on_line，取值同样为 0 或 1。

15.蓝牙应急开门

获取临时密码

POST https://wdev.wmj.com.cn/deviceApi/TPassword

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}"
}

成功后读取 data.pwd，并通过BLE写入设备：

开锁服务：FEE0
写特性：FEE1
通知特性：FEE2

向 FEE1 写入：

{
  "cmd_type": "ble_pwd_open_lock",
  "info": {
    "data": "12345678"
  }
}

设备通过 FEE2 通知执行结果：

{
  "state": 1,
  "info": {
    "code": 0,
    "msg": "Unlock success"
  }
}

临时密码采用滚动码校验，开门成功后状态会推进；业务端不得缓存后重复使用。

16.本地配网与应急能力

设备持续提供以序列号命名的 SoftAP，并支持2.4GHz WiFi配网。
手机连接设备热点后可访问 http://192.168.4.1/；主流系统会尝试自动弹出配网页面。
BLE配网服务 UUID 为 0D38；蓝牙应急开门服务为 FEE0。
断网时仍可通过本地配网页面输入设备应急开门密码，不依赖云端连接。

17.常见错误

场景	处理建议
平台返回设备不在线	先调用 `getOnLine`；不要通过反复发送控制命令探活
配置命令平台返回成功但设备字段未改变	检查 `data.info.code`，再使用 `getdevinfo` 回读
OTA收到应答但版本未改变	核对硬件版本、目标版本、URL和应用固件类型，并等待设备重连回读
蓝牙能发现但无法开门	重新获取临时密码，确认写入 `FEE1` 并监听 `FEE2` 通知

17.1 配置回调地址与开门通知

统一开门回调协议

适用 W767 67.1.22、W76M 76.0.8，硬件1.0.0。使用前通过 getdevinfo 确认型号和版本；旧版本不能只按版本数值推断支持全部回调。

配置及回读

POST https://wdev.wmj.com.cn/deviceApi/send，Content-Type: application/json。

{"app_id":"{{wmjv2appid}}","app_secret":"{{wmjv2appsecret}}","device_sn":"{{device_sn}}","type":1,"data":{"cmd_type":"set_callback","info":{"url":"https://example.com/callback","enabled":1}}}

url 为 HTTP(S) 地址，最多255字节；enabled 必须为数值0或1。兼容 callback_url/callback_enabled 别名；同时提交两套字段时值必须一致。省略字段保留原值。空参数、错误类型、冲突值、启用但URL为空均返回设备 data.info.code 非零。平台 code=0 不等于设备配置或投递成功。

{"app_id":"{{wmjv2appid}}","app_secret":"{{wmjv2appsecret}}","device_sn":"{{device_sn}}","type":1,"data":{"cmd_type":"get_callback","info":{}}}

回读设备 data.info 示例：

{"code":0,"err_code":0,"msg":"","callback_ready":true,"callback_url":"https://example.com/callback","callback_enabled":1,"pending_callbacks":0,"callback_capacity":4,"callback_success":1,"callback_failed":0,"callback_dropped":0,"callback_storage_errors":0,"callback_last_http":200,"callback_last_error":0}

ready 表示回调功能初始化状态；pending/capacity 为待发数和容量。success/failed/dropped/storage_errors 为本次启动计数，不是终身计数。last_http 为最近HTTP状态；last_error 为传输错误码，0表示无传输错误，仍须检查HTTP状态。

POST 通知格式

设备向配置的URL发送 HTTP POST，Content-Type: application/json，不包裹 data/info：

{"device_sn":"{{device_sn}}","event":"door_opened","open_type":"api","event_uid":"example-device-8ce5dafcc085d6d8","callback_id":627159385,"msg_id":206,"timestamp":23,"rssi":-40,"cmd_id":"order-001","user_id":"user-001"}

字段	类型	说明
device_sn	string	设备序列号
event	string	door_opened，表示控制器执行开门动作，不代表物理门已打开；门磁需另查
open_type	string	api / ble / button / web / schedule / delay
event_uid	string	幂等键，重试及重启补发保持不变
callback_id	number	数字事件编号，优先以event_uid去重
msg_id	number	API open消息ID；其他入口为0
timestamp	number	事件产生时设备本次启动的秒数，不是Unix时间戳
rssi	number	当时WiFi信号dBm；获取失败可能为0
cmd_id	string，可选	API open.info透传，最多96字节
user_id	string，可选	API open.info透传，最多96字节，不代表设备自动识别用户

api 为API触发开门；ble 为蓝牙鉴权后开门；button 为控制器可感知的开门按钮；web 为本地应急网页；schedule 为定时计划；delay 为延时到期。蓝牙/按钮等不带 cmd_id/user_id，其他自定义字段不透传。关闭或释放继电器不产生door_opened。

W76M 开门按钮支持button；W767板载按键用于配网/复位，不因此变成开门按钮。外接按钮若绕过控制器直接接门禁电源，固件无法感知其操作。

投递、离线及错误处理

接收端返回 HTTP200/201/204 表示成功，正文不限；其他状态和网络失败重试。不跟随重定向。
重试间隔10/20/40/80/160/300秒，之后上限300秒；必须按event_uid幂等，不能假设只到达一次或严格按发生顺序到达。
最多4条持久化待发记录；断网期间启用状态下的开门记录入队，联网后补发。满队列不会覆盖旧记录，新记录可能丢弃，应监测callback_dropped/storage_errors；不保证无限离线事件留存。
API open应答中的callback_queued/callback_error独立于开门结果。队列失败不撤销开门动作；禁用时不入队。仅ACK成功不能证明业务服务器收到通知。
禁用暂停旧队列；重新启用后按事件原URL补发，已在途请求可能完成。恢复出厂清除回调配置与队列。升级前产生的旧事件保留原内容，可能仍含旧值mqtt。
建议使用HTTPS并校验业务关联。本载荷没有应用级签名，不应仅凭此通知授予新的开门权限。

验证范围：两款均已验证API开门、延时回调及失败重启补发；W76M另有按钮实测。蓝牙、网页、定时计划的回调入口已接入，但本轮尚未完成对应现场触发验证；HTTPS、满队列与长时间离线需按业务环境验证。

18.解绑设备

请求URL

https://wdev.wmj.com.cn/deviceApi/logout

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}"
}

返回示例

{
  "code": 0,
  "msg": "解绑成功"
}

更新日志

日期	内容
2026-09-14	更新 76.0.8 回调维护版本及OTA示例，统一六种开门来源、配置别名、完整通知字段和重试去重规则，明确验证范围。
2026-09-09	发布 76.0.5 量产维护版本，明确适用硬件及版本线，完善统一请求方式、按钮接口版本要求与 OTA 使用说明，明确远程 WiFi 配置保存后需重启生效。
2026-09-08	更新 76.0.5 固件下载及升级示例，改善长时间无法连接云端时的自动恢复，减少重复网络错误日志，补充升级忙状态处理。
2026-08-30	首次发布 W76M 开发者接口文档，补充云端控制、WiFi配置、在线查询、OTA、BLE应急开门、本地配网及开门按钮版本边界。

作者：极客师傅创建时间：2026-08-30 00:09
最后编辑：极客师傅更新时间：2026-09-14 11:42

上一篇： W764(4G门禁控制器)API
下一篇： W765(门禁面板机)API