W77(人脸识别一体机)API

本 API 适用于序列号以 W77 开头的人脸识别一体机。W77 设备通过硬件云 APIv2 接入，开发者使用 app_id、app_secret 和设备序列号完成注册、远程开门、人脸/卡管理、设备配置、扫码回调、语音播报和 OTA 升级。

app_id 和 app_secret 请登录 https://wdev.wmj.com.cn 获取。

点击下面的序号展开。

1.注册设备

简要描述

将设备和 app_id、app_secret 绑定。注册成功后才能调用功能接口。

请求URL

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

请求方式

POST

请求格式

json

参数

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

参数说明

参数名	必选	类型	取值范围 / 格式	说明
app_id	是	string	平台分配	硬件云 app_id
app_secret	是	string	平台分配	硬件云 app_secret
device_sn	是	string	W77 开头的设备序列号	设备序列号

返回示例

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

{
  "code": 1005,
  "msg": "设备已注册"
}

2.公共请求结构

简要描述

除注册、解绑外，W77 功能接口统一调用发送指令接口，通过 data.cmd_type 区分具体功能。

请求URL

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

请求方式

POST

请求格式

json

基础参数

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

参数名	必选	类型	取值范围 / 格式	说明
app_id	是	string	平台分配	硬件云 app_id
app_secret	是	string	平台分配	硬件云 app_secret
device_sn	是	string	W77 开头的设备序列号	设备序列号
type	否	int	固定传 `1`	请求类型
data.cmd_type	是	string	本文档列出的命令名	命令类型
data.info	否	object	JSON 对象	命令参数

通用返回

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "msg_id": 1,
    "type": 1,
    "cmd": "",
    "cmd_type": "open",
    "info": {
      "code": 0,
      "msg": "",
      "result": "ok",
      "stateCode": 200
    }
  }
}

参数名	类型	说明
code	int	平台接口调用错误码，0 表示成功
data.info.code	int	业务错误码，0 表示成功，推荐使用
data.info.msg	string	业务错误信息，推荐使用
data.info.result	string	兼容保留字段，`ok` 或 `fail`
data.info.stateCode	int	兼容保留字段，200 表示成功
data.info.detail	string	失败详情，失败时可能返回

3.远程开门

简要描述

远程触发门禁继电器开门。open 为推荐命令，unlock 为兼容命令。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "open",
    "info": {
      "uid": "00001",
      "tts": "远程开门成功",
      "volume": 80
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`open`，兼容 `unlock`	远程开门命令
data.info.uid	否	string	1-64 字符建议	业务用户 ID，设备原值返回
data.info.tts	否	string	1-200 字建议	本次开门播报内容
data.info.text	否	string	1-200 字建议	本次开门播报内容，兼容字段
data.info.prompt_text	否	string	1-200 字建议	本次开门播报内容，兼容字段
data.info.open_tts_content	否	string	1-200 字建议	本次开门播报内容，兼容字段
data.info.volume	否	int	0-100	本次播报音量；不传时使用设备默认音量

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd_type": "open",
    "info": {
      "code": 0,
      "msg": "",
      "result": "ok",
      "stateCode": 200,
      "uid": "00001"
    }
  }
}

备注

未传播报内容时，设备使用配置中的远程开门提示语音或默认语音。
需要统一配置开门播报内容时，请使用 device_info_set 设置 remote_open_door_prompt_text。

4.添加人脸

简要描述

向设备添加一张人脸。图片 URL 支持 HTTP/HTTPS，建议使用设备可访问的 HTTPS 地址。也可以传入已经提取好的人脸特征值。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "face_add",
    "info": {
      "face_id": "10001",
      "name": "张三",
      "phone_number": "13800000000",
      "type": 1,
      "img_url": "https://example.com/face/10001.jpg",
      "download_timeout": 20
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`face_add`	添加人脸命令
data.info.face_id	是	string	1-64 字符建议	人脸唯一 ID，兼容旧字段 `sCertificateNumber`
data.info.name	否	string	0-64 字符建议	姓名，兼容旧字段 `sName`
data.info.phone_number	否	string	0-32 字符建议	手机号，兼容旧字段 `sTelephoneNumber`
data.info.type	否	int	业务自定义整数，常用 0/1	人员类型，兼容旧字段 `iType`
data.info.img_url	条件必填	string	HTTP/HTTPS 图片直链，建议 HTTPS	人脸图片 URL，兼容旧字段 `picURI`
data.info.feature	条件必填	string	Base64 字符串	人脸特征值；`img_url` 和 `feature` 至少传一个
data.info.download_timeout	否	int	正整数秒，默认 20	图片下载超时时间，传 0 或负数按 20 秒处理

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd_type": "face_add",
    "info": {
      "code": 0,
      "msg": "",
      "result": "ok",
      "stateCode": 200,
      "face_id": "10001",
      "face_algorithm": "arcsoft",
      "feature": "base64-feature"
    }
  }
}

备注

img_url 和 feature 至少传一个。
返回中的 feature 可用于后续迁移或批量下发。
如果同一张脸已经存在，返回中可能包含 repeat_face_id。

5.修改人脸

简要描述

修改已注册人脸的人员信息。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "face_edit",
    "info": {
      "face_id": "10001",
      "name": "张三",
      "phone_number": "13800000000",
      "type": 1,
      "start_time": 1719763200,
      "end_time": 1767225599
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`face_edit`	修改人脸命令
data.info.face_id	是	string	已存在的人脸 ID	人脸 ID，兼容旧字段 `sCertificateNumber`
data.info.name	否	string	0-64 字符建议	姓名，兼容旧字段 `sName`
data.info.phone_number	否	string	0-32 字符建议	手机号，兼容旧字段 `sTelephoneNumber`
data.info.type	否	int	业务自定义整数，常用 0/1	人员类型，兼容旧字段 `iType`
data.info.start_time	否	int	Unix 时间戳，秒	生效时间，兼容旧字段 `iBeginTime`
data.info.end_time	否	int	Unix 时间戳，秒；应大于 `start_time`	失效时间，兼容旧字段 `iEndTime`

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd_type": "face_edit",
    "info": {
      "code": 0,
      "msg": "",
      "result": "ok",
      "stateCode": 200
    }
  }
}

6.删除人脸

简要描述

按人脸 ID 删除设备上的人脸。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "face_del",
    "info": {
      "face_id": "10001"
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`face_del`	删除人脸命令
data.info.face_id	是	string	已存在的人脸 ID	人脸 ID

7.清空人脸

简要描述

清空设备本地所有人脸。

请求URL

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

请求方式

POST

请求格式

json

参数

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

8.查询人脸

简要描述

查询单个人脸、全部人脸 ID，或全部人脸及有效期信息。

请求URL

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

请求方式

POST

请求格式

json

查询单个人脸

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "face_find",
    "info": {
      "face_id": "10001"
    }
  }
}

查询全部人脸 ID

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

查询全部人脸有效期

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

9.添加或修改门卡

简要描述

添加或修改设备本地门卡。card_add 和 card_edit 使用相同参数。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "card_add",
    "info": {
      "card_id": "00ABCDEF",
      "name": "张三",
      "type": 1,
      "start_time": 1719763200,
      "end_time": 1767225599,
      "valid_num": 0
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`card_add` 或 `card_edit`	添加或修改门卡命令
data.info.card_id	是	string	16 进制字符串，建议大写	门卡卡号
data.info.name	否	string	0-64 字符建议	持卡人姓名
data.info.type	否	int	业务自定义整数，常用 0/1	卡类型
data.info.start_time	否	int	Unix 时间戳，秒	生效时间
data.info.end_time	否	int	Unix 时间戳，秒；应大于 `start_time`	失效时间
data.info.valid_num	否	int	0 或正整数	可用次数，0 表示不限制

10.删除和查询门卡

删除门卡

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "card_del",
    "info": {
      "card_id": "00ABCDEF"
    }
  }
}

清空门卡

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

查询门卡

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "card_find",
    "info": {
      "card_id": "00ABCDEF"
    }
  }
}

查询全部门卡

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

11.从设备发卡

简要描述

让设备进入发卡模式。该模式下，已注册卡正常识别，未注册卡刷卡时会注册为新卡。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "device_add_card",
    "info": {
      "state": 1,
      "timeout": 60,
      "name": "张三",
      "start_time": 1719763200,
      "end_time": 1767225599
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`device_add_card`	设备侧发卡命令
data.info.state	是	int	`0` 关闭，`1` 开启，`2` 查询	发卡模式状态
data.info.timeout	否	int	正整数秒，默认 10	发卡模式超时时间
data.info.name	否	string	0-64 字符建议	卡备注
data.info.start_time	否	int	Unix 时间戳，秒	生效时间
data.info.end_time	否	int	Unix 时间戳，秒；应大于 `start_time`	失效时间

设备发卡通知

{
  "cmd_type": "add_card_notify",
  "device_sn": "{{device_sn}}",
  "info": {
    "card_id": "00ABCDEF",
    "name": "张三",
    "start_time": 1719763200,
    "end_time": 1767225599
  }
}

12.从设备加人脸

简要描述

让设备进入添加人脸模式。该模式下，已注册人脸正常识别，未注册人脸识别成功后会注册为新人脸。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "device_add_face",
    "info": {
      "state": 1,
      "timeout": 60,
      "name": "张三",
      "face_id_prefix": "ST",
      "phone_number": "13800000000",
      "type": 1,
      "start_time": 1719763200,
      "end_time": 1767225599
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`device_add_face`	设备侧加人脸命令
data.info.state	是	int	`0` 关闭，`1` 开启，`2` 查询	加人脸模式状态
data.info.timeout	否	int	正整数秒，默认 10	加人脸模式超时时间
data.info.name	否	string	0-64 字符建议	姓名
data.info.face_id_prefix	否	string	0-16 字符建议	人脸 ID 前缀，设备注册时会拼接时间生成 face_id
data.info.phone_number	否	string	0-32 字符建议	手机号
data.info.type	否	int	业务自定义整数，常用 0/1	人员类型
data.info.start_time	否	int	Unix 时间戳，秒	生效时间
data.info.end_time	否	int	Unix 时间戳，秒；应大于 `start_time`	失效时间

设备添加人脸通知

{
  "cmd_type": "add_face_notify",
  "device_sn": "{{device_sn}}",
  "info": {
    "face_id": "ST1719763200",
    "name": "张三",
    "phone_number": "13800000000",
    "start_time": 1719763200,
    "end_time": 1767225599,
    "feature": "base64-feature"
  }
}

13.批量下发人脸和门卡

简要描述

设备支持从 URL 下载批量数据文件。批量任务会先返回受理结果，完成后再返回任务结果。

批量人脸

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "AddPersons",
    "info": {
      "url": "https://example.com/batch/faces.json",
      "retain": 1
    }
  }
}

查询批量人脸失败明细

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

批量门卡

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "AddCards",
    "info": {
      "url": "https://example.com/batch/cards.json",
      "retain": 1
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.info.url	是	string	HTTP/HTTPS JSON 文件 URL，建议 HTTPS	批量数据文件地址
data.info.retain	否	int	`0` / `1`	是否保留原有数据，具体以项目约定为准

14.读取设备信息

简要描述

读取设备配置、版本、网络、容量等信息。以下命令等价：device_info_get、getdevinfo、get_dev_info、DeviceInfo。

请求URL

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

请求方式

POST

请求格式

json

读取全部信息

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

读取指定字段

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "device_info_get",
    "info": {
      "volume": "",
      "version": "",
      "qrcode_recognition": "",
      "qrcode_post_url": "",
      "remote_open_door_prompt_text": ""
    }
  }
}

15.设置设备信息

简要描述

设置设备配置。常用配置包括音量、回调地址、扫码、识别阈值、提示语音文本、TTS 配置、继电器和补光灯配置等。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "device_info_set",
    "info": {
      "volume": 80,
      "face_post_url": "https://example.com/callback/face",
      "qrcode_recognition": "enable",
      "qrcode_post_url": "https://example.com/callback/scan",
      "remote_open_door_prompt_text": "远程开门成功"
    }
  }
}

常用配置字段

字段	类型	取值范围 / 格式	默认值	说明
volume	int	0-100	100	设备提示音、TTS 和本地提示音默认音量。`0` 表示静音
face_post_url	string	HTTP/HTTPS URL，建议 HTTPS	空	人脸识别、抓拍推送使用的业务回调地址
face_post_timeout	int	1-60 秒	3	人脸识别/抓拍回调超时时间
face_post_resulte_ignore	string	`enable` / `disable`	`disable`	是否忽略业务回调结果。`disable` 时可按业务响应决定动作
face_recognized_action	string	`default` / `post` / `default&post`，兼容 `default;post`	`default`	人脸识别成功后的动作：本地开门、上报、开门并上报
card_post_url	string	HTTP/HTTPS URL，建议 HTTPS	空	刷卡结果回调地址
card_post_timeout	int	建议 1-60 秒	3	刷卡回调超时时间
card_post_resulte_ignore	string	`enable` / `disable`	`disable`	是否忽略刷卡回调结果
qrcode_recognition	string	`enable` / `disable`	`disable`	反扫码识别开关
qrcode_post_url	string	HTTP/HTTPS URL，建议 HTTPS	空	反扫码结果回调地址
qrcode_post_timeout	int	建议 1-60 秒	3	扫码回调超时时间
callback_url	string	HTTP/HTTPS URL，建议 HTTPS	空	扫码回调地址兼容字段，写入后会自动开启扫码识别
qrcode_callback_url	string	HTTP/HTTPS URL，建议 HTTPS	空	扫码回调地址兼容字段
scan_callback_url	string	HTTP/HTTPS URL，建议 HTTPS	空	扫码回调地址兼容字段
scan_post_url	string	HTTP/HTTPS URL，建议 HTTPS	空	扫码回调地址兼容字段
barcode_callback_url	string	HTTP/HTTPS URL，建议 HTTPS	空	扫码回调地址兼容字段
recognition_rect	int	0-800	200	人脸识别区域配置
similarity_threshold	int	0-100	82	人脸相似度阈值，值越高越严格
register_quality_threshold	int	30-80	50	注册图片质量阈值
recognition_quality_threshold	int	30-80	30	识别质量阈值
recognition_quality_func	string	`enable` / `disable`	`disable`	是否启用识别质量过滤
face_register_min_size	int	建议 100-1000，默认 400	400	注册人脸最小尺寸，单位像素
face_capture_func	string	`enable` / `disable`	`disable`	抓拍功能开关
face_capture_width	int/string	正整数，默认 120	120	抓拍图片宽度，单位像素
face_capture_height	int/string	正整数，默认 180	180	抓拍图片高度，单位像素
capture_push_func	string	`enable` / `disable`	`disable`	抓拍后是否推送到 `face_post_url`
capture_open_func	string	`enable` / `disable`	`disable`	抓拍后是否执行开门
face_capture_push_option	string	字符串	空	抓拍上报扩展选项，按项目约定使用
remote_open_door_prompt_text	string	1-200 字建议	空	远程开门默认播报文本
open_tts_content	string	1-200 字建议	空	远程开门默认播报文本兼容字段
tts_func	string	`enable` / `disable`	`enable`	TTS 功能开关
tts_ws_url	string	`ws://` 或 `wss://` URL	平台默认地址	TTS WebSocket 合成地址，生产建议使用 `wss://`
tts_speaker	string	发音人标识，例如 `prompt_female_high`	`prompt_female_high`	默认发音人
tts_speed	string/number	建议 0.5-2.0	`1.0`	默认语速
tts_timeout	int/string	建议 3000-30000 毫秒	12000	单次合成超时时间
tts_cache_func	string	`enable` / `disable`	`enable`	TTS 缓存开关
tts_cache_max_mb	int/string	建议 10-500 MB	50	TTS 缓存最大空间
tts_cache_max_days	int/string	建议 1-365 天	30	TTS 缓存保留天数
timezone	string	系统支持的时区名称，例如 `Asia/Shanghai`	`Asia/Shanghai`	系统时区
system_time	string	ISO 时间，例如 `2026-06-24T12:00:00`	空	设置系统时间
time_format	string	`local` / `utc`	`local`	系统时间解析方式
white_led_init	string	Shell 命令	设备默认	白光补光灯初始化命令，高级硬件字段，常规业务无需配置
white_led_open	string	Shell 命令	设备默认	白光补光灯开启命令，高级硬件字段，常规业务无需配置
white_led_close	string	Shell 命令	设备默认	白光补光灯关闭命令，高级硬件字段，常规业务无需配置
white_led_schedule_func	string	`enable` / `disable`	`disable`	是否启用补光灯定时窗口
white_led_schedule_mode	string	`auto` / `always`	`auto`	定时窗口内的补光模式。`auto` 表示检测到人脸/活体目标时亮、人离开后灭；`always` 表示时间段内常亮
white_led_start_time	string	`HH:mm`，24 小时制	`18:00`	补光灯定时窗口开始时间
white_led_end_time	string	`HH:mm`，24 小时制	`06:00`	补光灯定时窗口结束时间
RC_time	int	建议 100-10000 毫秒	设备默认	继电器动作时长
board_type	string	主板型号字符串	设备默认	主板类型，只建议读取，不建议随意修改

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd_type": "device_info_set",
    "info": {
      "code": 0,
      "msg": "",
      "result": "ok",
      "stateCode": 200
    }
  }
}

备注

修改回调地址后建议调用 device_info_get 确认设备已保存。
扫码回调地址可使用 qrcode_post_url，也兼容 callback_url、qrcode_callback_url、scan_callback_url、scan_post_url、barcode_callback_url。
设置扫码回调地址且地址不为空时，设备会自动开启扫码识别。

16.抓拍通知设置

简要描述

配置人脸识别后的抓拍图片、抓拍上报和抓拍开门行为。抓拍推送地址使用 face_post_url，没有单独的 capture_post_url 字段。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "device_info_set",
    "info": {
      "face_post_url": "https://example.com/callback/face",
      "face_capture_func": "enable",
      "face_capture_width": "400",
      "face_capture_height": "640",
      "capture_push_func": "enable",
      "capture_open_func": "disable",
      "face_capture_push_option": ""
    }
  }
}

参数说明

字段	必填	类型	取值范围 / 格式	默认值	说明
face_post_url	是	string	HTTP/HTTPS URL，建议 HTTPS	空	抓拍推送地址。抓拍、识别上报都使用该地址
face_capture_func	是	string	`enable` / `disable`	`disable`	抓拍功能开关
face_capture_width	否	int/string	正整数，建议 120-800	120	抓拍图片宽度，单位像素
face_capture_height	否	int/string	正整数，建议 180-1280	180	抓拍图片高度，单位像素
capture_push_func	是	string	`enable` / `disable`	`disable`	抓拍后是否向 `face_post_url` 上报
capture_open_func	否	string	`enable` / `disable`	`disable`	抓拍后是否同时开门
face_capture_push_option	否	string	字符串	空	抓拍上报扩展选项，按项目约定使用

抓拍上报示例

设备向 face_post_url 发送 HTTP POST。业务系统建议 3-10 秒内返回 HTTP 2xx。

{
  "cmd_type": "capture_notify",
  "device_sn": "{{device_sn}}",
  "info": {
    "capture_image": "base64-image",
    "time": "2026-06-24 12:00:00"
  }
}

配置说明

只开启抓拍但不设置 face_post_url 时，设备可以生成抓拍图，但业务系统收不到推送。
需要识别成功也回调时，同时设置 face_recognized_action 为 post 或 default&post。
capture_image 为图片 Base64 字符串，业务系统应按实际图片大小调整请求体大小限制。

17.设置验证人脸后动作

简要描述

配置人脸识别成功后的动作，例如本地开门、向业务系统回调，或等待业务系统验证后再开门。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "device_info_set",
    "info": {
      "face_recognized_action": "default&post",
      "face_post_url": "https://example.com/callback/face",
      "face_post_resulte_ignore": "enable",
      "face_post_timeout": "10",
      "face_recognized": "等待云端验证..."
    }
  }
}

参数说明

字段	必填	类型	取值范围 / 格式	默认值	说明
face_recognized_action	是	string	`default` / `post` / `default&post`，兼容 `default;post`	`default`	识别成功后动作。`default` 表示本地开门，`post` 表示上报业务系统，`default&post` 表示开门并上报
face_post_url	条件必填	string	HTTP/HTTPS URL，建议 HTTPS	空	人脸识别回调地址；使用 `post` 动作或抓拍推送时必须配置
face_post_resulte_ignore	否	string	`enable` / `disable`	`disable`	是否忽略回调结果
face_post_timeout	否	int/string	1-60 秒	3	回调超时时间
face_recognized	否	string	1-100 字建议	`刷脸开门成功`	识别成功时屏幕显示文本

人脸识别回调示例

{
  "cmd": "face_recognized",
  "device_sn": "{{device_sn}}",
  "info": {
    "face_id": "10001",
    "name": "张三",
    "similarity": 0.96,
    "capture_image": "base64-image",
    "time": "2026-06-24 12:00:00"
  }
}

18.补光灯设置

简要描述

配置 W77 V5 白光补光灯。常规业务优先使用定时窗口和模式字段：可设置“人来亮、人走灭”的自动补光，也可设置时间段常亮作为夜间照明。高级硬件控制字段仅用于特殊底板适配或售后指导，开发者通常不需要配置。

请求URL

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

请求方式

POST

请求格式

json

定时补光：人来亮、人走灭

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "device_info_set",
    "info": {
      "white_led_schedule_func": "enable",
      "white_led_schedule_mode": "auto",
      "white_led_start_time": "18:00",
      "white_led_end_time": "07:00"
    }
  }
}

定时常亮：夜间照明

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "device_info_set",
    "info": {
      "white_led_schedule_func": "enable",
      "white_led_schedule_mode": "always",
      "white_led_start_time": "18:00",
      "white_led_end_time": "07:00"
    }
  }
}

关闭定时补光

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "device_info_set",
    "info": {
      "white_led_schedule_func": "disable"
    }
  }
}

读取当前配置

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "device_info_get",
    "info": {
      "white_led_schedule_func": "",
      "white_led_schedule_mode": "",
      "white_led_start_time": "",
      "white_led_end_time": ""
    }
  }
}

参数说明

字段	必填	类型	取值范围 / 格式	默认值	说明
white_led_schedule_func	是	string	`enable` / `disable`	`disable`	是否启用补光灯定时窗口
white_led_schedule_mode	否	string	`auto` / `always`	`auto`	定时窗口内的补光模式。`auto` 表示检测到人脸/活体目标时亮、人离开后灭；`always` 表示时间段内常亮
white_led_start_time	否	string	`HH:mm`，24 小时制	`18:00`	定时窗口开始时间
white_led_end_time	否	string	`HH:mm`，24 小时制	`06:00`	定时窗口结束时间

模式说明

auto：时间段内允许设备自动补光，设备检测到人脸或活体目标时开启补光灯，人离开后自动关闭，适合人脸识别补光。
always：时间段内保持补光灯常亮，适合需要夜间照明的场景。
支持跨天时间段，例如 18:00 到 07:00 表示当天 18:00 至次日 07:00。
开始时间和结束时间相同表示该定时窗口不生效。
时间段外不会因为 always 模式保持常亮；如关闭定时窗口，设备按默认识别补光逻辑运行。

版本说明

white_led_schedule_mode 需 W77 V5 非触摸版 5.0.38 及以上版本、触摸版 5.1.16 及以上版本支持。
旧版本可通过 device_info_get 或 getdevinfo 读取字段验证是否支持；不支持时请先升级固件。

高级字段说明

white_led_init、white_led_open、white_led_close 属于高级硬件控制字段，与设备底板适配有关，常规业务系统不建议直接修改。
如需确认当前底板配置，可通过 device_info_get 或 getdevinfo 读取上述字段；修改前请联系技术支持确认设备型号和底板版本。

19.音量设置

简要描述

设置设备提示音、TTS 播报和部分音频链路的默认音量。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "device_info_set",
    "info": {
      "volume": 80
    }
  }
}

参数说明

字段	必填	类型	取值范围 / 格式	默认值	说明
volume	是	int	0-100	100	设备提示音、TTS 播报和本地提示音默认音量，`0` 表示静音

20.语音设置

简要描述

配置本地固定提示音文件。启用 TTS 文本后，设备优先使用 TTS；TTS 不可用时可回退到这里配置的本地音频。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "audio_settings",
    "info": {
      "reg_success_audio": "https://example.com/audio/reg_success.wav",
      "enter_face_reg_mode_audio": "https://example.com/audio/enter_face.wav",
      "enter_card_reg_mode_audio": "https://example.com/audio/enter_card.wav",
      "exit_face_reg_mode_audio": "https://example.com/audio/exit_face.wav",
      "exit_card_reg_mode_audio": "https://example.com/audio/exit_card.wav",
      "remote_door_open_audio": "https://example.com/audio/open.wav",
      "face_expired_audio": "https://example.com/audio/face_expired.wav",
      "card_expired_audio": "https://example.com/audio/card_expired.wav",
      "face_rec_success_audio": "https://example.com/audio/face_success.wav",
      "card_rec_success_audio": "https://example.com/audio/card_success.wav",
      "face_rec_fail_audio": "https://example.com/audio/face_fail.wav",
      "card_rec_fail_audio": "https://example.com/audio/card_fail.wav"
    }
  }
}

重置本地语音

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

返回说明

返回中对应字段为 0 表示该项设置成功，1 表示该项设置失败。

21.获取人脸特征

简要描述

按人脸 ID 获取设备内保存的人脸特征值，用于迁移、备份或批量同步。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "GetFeature",
    "info": {
      "face_id": "10001"
    }
  }
}

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd_type": "GetFeature",
    "info": {
      "face_id": "10001",
      "feature": "base64-feature",
      "result": "ok",
      "stateCode": 200
    }
  }
}

22.配置提示音文本

简要描述

设备支持将固定提示音升级为可配置文本。启用 TTS 后优先播放合成语音，合成失败或接口不可用时回退本地固定语音。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "device_info_set",
    "info": {
      "remote_open_door_sound_text": "远程开门成功",
      "recognized_face_sound_text": "刷脸开门成功",
      "recognized_card_sound_text": "刷卡开门成功",
      "unrecognized_face_sound_text": "未注册人脸",
      "unrecognized_card_sound_text": "未注册卡",
      "qrcode_scan_text": "扫码成功",
      "qrcode_callback_success_text": "扫码回调成功",
      "qrcode_callback_fail_text": "扫码回调失败"
    }
  }
}

常用提示音文本字段

字段	类型	取值范围 / 格式	默认值	说明
remote_open_door_sound_text	string	1-200 字建议	`请通过`	远程开门提示音文本
remote_open_door_prompt_text	string	1-200 字建议	空	远程开门默认播报文本，优先级高于固定提示音
recognized_face_sound_text	string	1-200 字建议	`请通过`	人脸识别成功提示音文本
recognized_card_sound_text	string	1-200 字建议	`请通过`	刷卡成功提示音文本
face_overdue_sound_text	string	1-200 字建议	`人脸已过期`	人脸过期提示音文本
card_overdue_sound_text	string	1-200 字建议	`卡已过期`	门卡过期提示音文本
unrecognized_face_sound_text	string	1-200 字建议	`未注册人脸`	未注册人脸提示音文本
unrecognized_card_sound_text	string	1-200 字建议	`未注册卡`	未注册卡提示音文本
qrcode_scan_text	string	0-200 字建议	空	扫码提示音文本，空时可只播放扫码提示音
qrcode_callback_success_text	string	1-200 字建议	`扫码回调成功`	扫码回调成功提示音文本
qrcode_callback_fail_text	string	1-200 字建议	`扫码回调失败`	扫码回调失败提示音文本
sw_update_sound_text	string	1-200 字建议	`正在升级，请勿断电`	OTA 升级提示音文本

23.云喇叭播放

简要描述

让 W77 直接播放一段文本，接口兼容云喇叭 play 指令。长文本由设备排队连续播放。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "play",
    "info": {
      "number_mode": "digit",
      "speaker": "prompt_female_high",
      "tts": "欢迎使用微门禁",
      "volume": 4
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`play`，兼容 `ttsplay`、`tts_play`	云喇叭播放命令
data.info.tts	是	string	1-500 字建议	播放文本，兼容 `text`、`content`、`message`
data.info.speaker	否	string	发音人标识，例如 `prompt_female_high`	发音人
data.info.number_mode	否	string	`digit` 等平台支持值	数字读法
data.info.volume	否	int	1-10 或 0-100	传 1-10 时按云喇叭音量映射到 10-100；也可直接传 0-100
data.info.fallback_wav	否	string	本地 WAV 路径或可下载 URL	TTS 不可用时回退的本地音频

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd_type": "play",
    "info": {
      "code": 0,
      "msg": "",
      "result": "ok",
      "stateCode": 200,
      "detail": "播放任务已加入队列"
    }
  }
}

24.配置反扫码

简要描述

开启设备扫码识别，并配置扫码结果回调地址。适用于用户展示二维码或条码给设备摄像头识别的场景。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "device_info_set",
    "info": {
      "qrcode_recognition": "enable",
      "qrcode_post_url": "https://example.com/callback/scan",
      "qrcode_post_timeout": 10
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	默认值	说明
data.cmd_type	是	string	`device_info_set`	-	设置设备配置
data.info.qrcode_recognition	是	string	`enable` / `disable`	`disable`	是否开启反扫码识别
data.info.qrcode_post_url	是	string	HTTP/HTTPS URL，建议 HTTPS	空	扫码结果回调地址
data.info.qrcode_post_timeout	否	int/string	建议 1-60 秒	3	扫码回调超时时间
data.info.callback_url	否	string	HTTP/HTTPS URL，建议 HTTPS	空	扫码回调地址兼容字段，写入后会自动开启扫码识别
data.info.qrcode_callback_url	否	string	HTTP/HTTPS URL，建议 HTTPS	空	扫码回调地址兼容字段
data.info.scan_callback_url	否	string	HTTP/HTTPS URL，建议 HTTPS	空	扫码回调地址兼容字段
data.info.scan_post_url	否	string	HTTP/HTTPS URL，建议 HTTPS	空	扫码回调地址兼容字段
data.info.barcode_callback_url	否	string	HTTP/HTTPS URL，建议 HTTPS	空	扫码回调地址兼容字段

备注

qrcode_post_url 建议使用 HTTPS。
也可以使用 callback_url、qrcode_callback_url、scan_callback_url、scan_post_url、barcode_callback_url，设备会写入扫码回调地址并自动开启扫码识别。

25.视频广告设置

简要描述

配置 MP4 视频广告。视频文件需设备可下载，建议使用 H.264 视频流和 AAC 音频流。

请求URL

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

请求方式

POST

请求格式

json

下载或更新视频广告

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "advertising_set",
    "info": {
      "operate": 0,
      "url": "https://example.com/ad/video.mp4",
      "timeout": 240
    }
  }
}

查询下载状态

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

开启视频广告

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "advertising_set",
    "info": {
      "operate": 3
    }
  }
}

关闭视频广告

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "advertising_set",
    "info": {
      "operate": 2
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`advertising_set`	视频广告命令
data.info.operate	是	int	`0` 下载，`1` 查询下载状态，`2` 关闭广告，`3` 开启广告，`4` 设置参数	操作类型
data.info.url	条件必填	string	HTTP/HTTPS MP4 URL，建议 HTTPS	`operate=0` 时必填
data.info.timeout	否	int	正整数秒，默认 60	下载超时时间
data.info.volume	否	int	0-100	视频广告播放音量

26.图片广告设置

简要描述

配置图片广告素材和展示参数。适用于支持屏幕广告展示的 W77 设备。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "AdvertisementControl",
    "info": {
      "option": 0,
      "ad_id": 123,
      "url": [
        "https://example.com/ad/ad1.jpg",
        "https://example.com/ad/ad2.jpg"
      ],
      "ad_validBegin": 1751690044,
      "ad_validEnd": 1877145600,
      "ad_display_time": 5,
      "display_mode": 1,
      "transparency": 0.5
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`AdvertisementControl`	图片广告命令
data.info.option	是	int	`0` 新增/更新广告，`1` 删除广告	操作类型
data.info.ad_id	是	int	正整数	广告 ID
data.info.url	新增时必填	array	图片 URL 数组，建议 HTTPS	图片素材列表
data.info.ad_validBegin	否	int	Unix 时间戳，秒	广告生效时间
data.info.ad_validEnd	否	int	Unix 时间戳，秒；应大于 `ad_validBegin`	广告失效时间
data.info.ad_display_time	否	int	1-30 秒，默认 5	单张图片展示时长
data.info.display_mode	否	int	`0` 带预览，`1` 不带预览，`2` 透明模式，`3` 分割模式	显示模式
data.info.transparency	否	number	0.0-1.0，默认 0.7	透明度

27.开启或关闭图片广告

简要描述

通过设备配置项开启或关闭图片广告展示。

请求URL

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

请求方式

POST

请求格式

json

开启图片广告

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

关闭图片广告

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "device_info_set",
    "info": {
      "ad_func": "disable"
    }
  }
}

28.设置屏幕二维码

简要描述

设置设备屏幕显示的二维码内容。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_qrcode",
    "info": {
      "qrcode_data": "https://example.com",
      "update_time": 10
    }
  }
}

29.OTA 升级

简要描述

让设备下载 OTA 信息文件并执行升级。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_ota",
    "info": {
      "url": "http://fm.wmj.com.cn/update/info/5.0.25.json",
      "reboot": 1
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`set_ota`	OTA 升级命令
data.info.url	是	string	HTTP/HTTPS OTA 信息 JSON URL	OTA 信息文件 URL
data.info.reboot	否	int	`0` / `1`	是否请求升级完成后重启，最终以 OTA 文件配置为准

30.软件恢复

简要描述

触发设备执行软件恢复命令。该接口用于设备软件恢复场景，执行前请确认设备状态和业务影响。

请求URL

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

请求方式

POST

请求格式

json

参数

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

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd_type": "SWRecovery",
    "info": {
      "result": "ok",
      "stateCode": 200
    }
  }
}

31.重启、定时重启和恢复

重启设备

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

设置定时重启

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "TimeReboot",
    "info": {
      "timeStart": "04:00"
    }
  }
}

恢复数据

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "reset",
    "info": {
      "face_reset": 1,
      "card_reset": 1,
      "configuration_reset": 0
    }
  }
}

32.网络配置

设置静态 IP

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_static_ip",
    "info": {
      "mode": "static",
      "ip": "192.168.1.100",
      "netmask": "255.255.255.0",
      "gateway": "192.168.1.1",
      "dns": "114.114.114.114"
    }
  }
}

恢复 DHCP

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_static_ip",
    "info": {
      "mode": "dhcp"
    }
  }
}

查询网络配置

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

重置 WiFi

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "wifireset",
    "info": {
      "wifi_ssid": "ExampleWiFi",
      "wifi_password": "{{wifi_password}}"
    }
  }
}

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`wifireset`	WiFi 重置命令
data.info.wifi_ssid	否	string	1-32 字符	WiFi 名称
data.info.wifi_password	否	string	0-64 字符	WiFi 密码

33.触摸版房号配置

简要描述

触摸版 W77 支持下发房号/楼栋配置，用于屏幕选择房间或呼叫目标。非触摸版不使用该接口。

请求URL

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

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "room_config_set",
    "info": {
      "device_type": "unit_gate",
      "area_name": "示例小区",
      "rooms": [
        {
          "room_id": "101",
          "room_name": "101"
        }
      ],
      "show_selector": 1,
      "show_device_list": 1
    }
  }
}

34.回调与上报

简要描述

设备在上线、离线、识别、刷卡、扫码等事件发生时，可向业务系统配置的回调地址发送 HTTP POST。业务系统请根据 cmd 或 cmd_type 区分事件类型。

业务系统要求

建议使用 HTTPS 回调地址。
建议 3 到 10 秒内返回 HTTP 2xx。
响应体建议为 JSON。
同一事件可能重复投递，业务系统应按设备序列号、事件类型、业务 ID 或时间做幂等处理。

回调地址对应关系

事件	配置字段	取值范围 / 格式	说明
人脸识别成功	`face_post_url`	HTTP/HTTPS URL，建议 HTTPS	`face_recognized_action` 包含 `post` 时上报
抓拍通知	`face_post_url`	HTTP/HTTPS URL，建议 HTTPS	抓拍推送没有单独地址，需同时开启 `face_capture_func` 和 `capture_push_func`
刷卡识别	`card_post_url`	HTTP/HTTPS URL，建议 HTTPS	配合刷卡动作配置使用
反扫码	`qrcode_post_url`	HTTP/HTTPS URL，建议 HTTPS	兼容 `callback_url`、`scan_callback_url` 等字段

上线回调示例

{
  "cmd": "OnLine",
  "device_sn": "{{device_sn}}",
  "info": {
    "time": 1680857941
  }
}

离线回调示例

{
  "cmd": "OffLine",
  "device_sn": "{{device_sn}}",
  "info": {
    "time": 1680857941
  }
}

人脸识别回调示例

{
  "cmd": "face_recognized",
  "type": 2,
  "device_sn": "{{device_sn}}",
  "info": {
    "face_id": "10001",
    "name": "张三",
    "time": 1680857941,
    "result": "ok"
  }
}

扫码回调示例

{
  "cmd": "qrcode_scan",
  "type": 2,
  "device_sn": "{{device_sn}}",
  "info": {
    "qrcode": "USER_QRCODE_VALUE",
    "time": 1680857941
  }
}

35.常见问题

设置后设备没有生效

先调用 device_info_get 或 getdevinfo 确认配置是否已写入设备。如果平台返回成功但设备没有行为变化，请检查固件版本、设备是否在线、字段名是否正确。

扫码没有回调

确认 qrcode_recognition 为 enable，并确认 qrcode_post_url 或兼容字段已设置为业务系统可访问的 HTTPS 地址。

抓拍没有推送到业务系统

抓拍推送地址使用 face_post_url，不是 qrcode_post_url，也没有单独的 capture_post_url。请确认 face_capture_func=enable、capture_push_func=enable，并且 face_post_url 是设备可访问的 HTTPS 地址。

音量设置为 0 后仍有声音

调用 getdevinfo 查看 volume 是否为 0，同时确认本次开门或播放指令中没有单独传入 volume 覆盖设备配置。

图片 URL 下载失败

建议使用 HTTPS，并确保设备网络可以解析域名、访问图片地址。图片地址应直接返回图片内容，不要依赖登录态或防盗链。

36.解绑设备

简要描述

解除设备与 app_id、app_secret 的绑定。解绑后该应用不能继续控制设备。

请求URL

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

请求方式

POST

请求格式

json

参数

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

返回示例

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

更新日志

日期	内容
2026-06-30	【非触摸版 `5.0.38` / 触摸版 `5.1.16`】补充 W77 V5 补光灯定时模式：新增 `white_led_schedule_mode`，区分 `auto` 人来亮人走灭与 `always` 时间段常亮；补充读取示例和版本说明。
2026-06-25	【触摸版】发布 W77 `5.1.13`：同步非触摸版网络稳定性优化；网络优先级按有线、WiFi、4G 依次选择；有线接入时自动修复默认路由，避免误切 WiFi/4G 导致 MQTT 断开；补充上线网络标识上报，WiFi 场景包含 SSID、BSSID、IP 和网关。
2026-06-25	【非触摸版】发布 W77 `5.0.36`：优化长期在线网络稳定性；网络优先级按有线、WiFi、4G 依次选择；修复有线已接入但默认路由异常导致设备离线或 MQTT 断开的问题；补充网络标识上报，WiFi 场景显示 SSID 和 BSSID。
2026-06-25	【触摸版】发布 W77 `5.1.11`：完善 TTS WebSocket 长连接、语音缓存、队列播放和长文本连续播报；支持云喇叭 `play` 兼容接口、远程开门播报文本、提示音文本配置、扫码回调成功/失败提示音；修复提示音末字不清晰的问题。
2026-06-25	【非触摸版】发布 W77 `5.0.35` 及后续版本：补齐 `getdevinfo` 兼容读取设备信息接口；支持 HTTPS 图片下载注册人脸；完善反扫码回调、云喇叭播放和可配置提示语音。
2026-06-24	补充 W77 参数取值范围、默认值和抓拍推送地址说明，明确抓拍推送使用 `face_post_url`。
2026-06-24	按 APIv2 结构重整 W77 文档，补充 `getdevinfo`、从设备发卡/加人脸、抓拍通知、验证后动作、补光灯、音量、语音设置、获取人脸特征、反扫码、云喇叭播放、广告、OTA、网络配置和触摸版房号配置说明。

作者：极客师傅创建时间：2025-03-21 23:23
最后编辑：极客师傅更新时间：2026-07-07 23:12

上一篇： W76F(WiFi五路门禁控制器)API
下一篇： W894(4G联网锁)API