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

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

当前公开维护版本：V3 为 3.0.25，V5 非触摸版稳定发布版本为 5.0.70，V5 触摸版为 5.1.33。不同版本线对应不同硬件和交互形态，升级时请保持原版本线，不要混用升级包。升级由维护人员按设备兼容情况安排，本次发布不启用全量自动升级。

2026-09-10 新增网线配置候选版本：非触摸 5.0.75、触摸 5.1.38。完善云端网线参数校验、保存结果与 Web 读回一致性；增加显式重启参数。暂不替代稳定维护版本，网线静态地址实际访问、断插网线与 DHCP 恢复仍待验证。

2026-09-08 新增局域网 Web 管理候选版本：非触摸版 5.0.74、触摸版 5.1.37。两个版本均完成对应测试设备升级与 Web 接口回归，供维护人员安排小范围验证，暂不替代上述稳定维护版本。使用静态 IP 的场景需先完成现场有线连通性验证，不建议直接批量升级。

点击下面的序号展开。

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": "",
      "wifi_ssid": "",
      "wifi_password": ""
    }
  }
}
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_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 读取字段验证是否支持；不支持时请先升级固件。
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 信息文件并执行升级。下面示例仅适用于 W77 V5 非触摸版；触摸版必须使用对应的 5.1.x 升级地址，两个版本线不能混用。

触摸版当前维护版本为 5.1.33，仅对原 5.1.x 设备使用 http://fm.wmj.com.cn/update/info/5.1.33.json，其余请求结构与下例一致。非触摸设备继续使用下例的 5.0.70 地址。

候选版本升级地址（2026-09-08）

以下地址供经维护人员确认的小范围测试使用，请只替换请求中的 data.info.url，其余结构不变。调用成功仅表示设备接受升级命令，应等待设备重新上线后用 getdevinfo 核对实际版本。

设备类型 候选版本 OTA 信息地址 使用限制
V5 非触摸版，原 5.0.x 5.0.75 http://fm.wmj.com.cn/update/info/5.0.75.json 不适用于 5.1.x、V1 或 V3
V5 触摸版，原 5.1.x 5.1.38 http://fm.wmj.com.cn/update/info/5.1.38.json 不适用于 5.0.x、V1 或 V3

本次候选版本完善局域网 Web 管理的有线参数校验与保存、联网校时结果提示、配置后重启流程和手机端显示。静态 IP 实际访问及不同现场网络环境仍需验证；请保留现场维护条件，勿将“参数保存成功”等同于新地址已可访问。现有 APIv2 命令和业务配置保持兼容。

请求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.70.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 密码

候选版本增强参数（5.0.75 / 5.1.38）

仅适用于上述对应版本线的测试候选；原版本不要直接套用新增字段。待完成现场网线连通性验证后，再安排生产使用。

set_static_ip 的 info 支持：

参数 类型 范围与默认值
mode string static（默认）或 dhcp
ip string static 必填，规范单播 IPv4；不接受回环、169.254、组播、网络/广播地址
netmask string 默认255.255.255.0，连续掩码，前缀1～30
gateway string 默认空；非空须为同子网、不同于本机的有效主机地址；外网访问需正确填写
dns string 默认空；非空为一个有效单播 IPv4，不支持分号列表；域名联网须有可用 DNS
reboot integer 默认0：只保存，下次重启生效；1：保存成功约3秒后正常重启；不接受字符串、布尔值、null或其他数值

示例：保留原请求外层，只替换 data：

{
  "cmd_type": "set_static_ip",
  "info": {
    "mode": "static",
    "ip": "192.168.1.210",
    "netmask": "255.255.255.0",
    "gateway": "192.168.1.1",
    "dns": "223.5.5.5",
    "reboot": 0
  }
}

地址仅为示例，请按现场实际填写。成功的 data.info 包含 result:"ok"、stateCode:200、saved:true、reboot_required:true。仅保存时 reboot_scheduled:false、reboot_seconds:0；显式重启时为 true 和 3。非法参数或保存失败返回失败，不安排重启。必须检查内层结果，不能仅凭 HTTP 200 判断成功。

get_static_ip 新增 active_ip、active_netmask、active_gateway、active_dns、carrier 和 mac。静态模式的 ip/netmask/gateway/dns 为保存值，active_* 为运行值；网关仅取网线接口，active_dns 是系统当前首个有效 IPv4 DNS，可能来自其他联网接口。无可用值返回空字符串。

若要把 DHCP 地址固定：先查询网线当前地址、掩码、网关和 DNS，再在路由器保留/排除该地址，防止分配冲突。用 reboot:0 保存并读回；确认现场维护时间和恢复手段后，再用相同参数及 reboot:1 应用。恢复后核对运行地址、云端在线与局域网访问。DHCP 恢复使用 {"mode":"dhcp","reboot":1}。重启会短暂影响识别及门禁服务。

如只需地址不变，也可在路由器为设备 MAC 设置 DHCP 地址保留，设备继续使用 DHCP。参数保存成功不等于新地址已生效或现场没有地址冲突。

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-09-10 【非触摸版 5.0.75，候选】完善云端网线参数校验、保存失败提示和配置读回，增加显式重启参数；网线静态地址实际连通性待验证，暂不替代稳定版
2026-09-10 【触摸版 5.1.38，候选】同步网线参数保存、运行地址区分及显式重启方式；网线静态地址实际连通性待验证，暂不替代稳定版
2026-09-08 【非触摸版 5.0.74，候选】完善局域网 Web 有线参数校验、配置保存及重启流程，校时提示反映实际执行结果，优化手机页面显示；已完成测试设备升级和 Web 接口回归，静态 IP 现场连通性需先验证。仅适用于 5.0.x，暂不替代稳定版
2026-09-08 【触摸版 5.1.37，候选】同步局域网 Web 有线参数校验、配置保存及重启流程、联网校时结果提示与手机布局优化；已完成测试设备升级和 Web 接口回归，静态 IP 现场连通性需先验证。仅适用于 5.1.x，暂不替代稳定版
2026-09-08 【触摸版 5.1.33】完善局域网 Web 管理页面加载与网络状态显示，正确区分有线和 Wi-Fi 连接，完善门禁设置默认值显示及参数输入校验；保留现有业务配置和 APIv2 调用方式。仅适用于 5.1.x，不适用于非触摸版 5.0.x
2026-09-07 【非触摸版 5.0.70】修复局域网 Web 管理页面无法打开的问题，提升页面资源加载可靠性；保留现有配置和 APIv2 调用方式。仅适用于 5.0.x，不适用于触摸版 5.1.x
2026-09-06 【非触摸版 5.0.68，稳定发布】提升设备启动后人脸识别可用性，优化摄像头及识别链路异常恢复；APIv2 指令和业务配置格式不变。仅适用于 5.0.x，不适用于触摸版 5.1.x
2026-09-06 【非触摸版 5.0.66】提升设备配置保存和异常恢复稳定性；规范设备信息查询返回范围，保留已公开业务配置、WiFi 配置和运行状态查询，接口调用方式不变
2026-08-20 【V3 3.0.25】优化人脸识别业务回调，补充 HTTPS 地址兼容，并统一识别结果与抓拍图片的上报字段
2026-08-14 【非触摸版 5.0.60】优化远程开门指令响应，减少界面繁忙时的开门等待；连续开门时保持时间可平滑延长，接口格式不变
2026-08-10 【非触摸版 5.0.59 / 触摸版 5.1.29】提升设备长期联网、弱网恢复和固件升级兼容性；现有 APIv2 指令、回调地址和业务数据格式不变
2026-08-02 【触摸版 5.1.28】优化人脸识别结果显示与播报一致性，避免空姓名沿用上一次结果，并修复识别成功状态被后续提示覆盖的问题
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-09-14 10:34
上一篇：
下一篇：