VF-MQTT 协议文档_V1.1.37.13（Vbar版本）

# 📘 VF-MQTT 协议文档 V1.1.37-13

# 一、概述

## 1.1 文档简介

本文档提供一套直接访问设备的接口规范，用于推送和获取设备信息。使用者购买设备后，可根据本接口说明进行自定义开发，构建完整的门禁系统或相关应用系统。

**核心功能**

本协议文档涵盖以下核心功能模块：

| 功能模块 | 说明 |
|---------|------|
| **设备管理** | 远程配置设备参数、网络设置、系统升级、设备控制等 |
| **用户管理** | 用户注册、修改、删除、查询，支持批量同步操作 |
| **凭证管理** | 人脸凭证、IC卡、二维码等多种认证方式的添加与删除 |
| **权限管理** | 用户通行权限的配置与同步 |
| **记录上报** | 通行记录、报警信息、设备状态等实时上报 |
| **信息传递** | 心跳、日志、门磁状态等信息的主动上报 |

**通信协议**

接口使用 **MQTT（Message Queuing Telemetry Transport）** 通信协议，具有以下特点：

- **轻量级**：基于发布/订阅模式，协议开销小，适合物联网设备
- **双向通信**：支持设备与服务器之间的双向实时通信
- **可靠性**：支持QoS（服务质量）等级，确保消息可靠传输
- **灵活性**：可对接各种通用的MQTT代理（Broker），如EMQ X、Mosquitto、RabbitMQ等

**快速开始**

1. **准备MQTT代理**：部署MQTT Broker，配置设备接入参数
2. **设备接入**：配置设备连接MQTT服务器，确保设备在线
3. **接口调用**：根据本文档接口规范，通过MQTT Topic进行消息收发
4. **业务集成**：将设备功能集成到自有业务系统中

## 1.2 应用场景

当需要对接自己的业务系统时，可以通过使用接口通过MQTT协议直接与设备通讯。

**系统架构示意**

![](/media/202603/image_20260318171219600569.png)

图1\.1\-1 MQTT代理业务

上图展示了典型的MQTT通信架构：
- **设备端**：智能终端设备（人脸识别门禁机）
- **MQTT代理**：消息中间件，负责设备与业务系统之间的消息转发
- **业务系统**：客户自有的管理平台或应用系统
- **通信方式**：设备与业务系统通过MQTT协议进行双向通信

## 1.3 接口规范

接口使用MQTT协议，分为上行与下行：

上行：是指设备上发消息给后台或应用。

下行：是指后台或应用下发消息给设备。

通信中间通过MQTT代理，消息包含消息topic与消息内容，格式如下：

**消息topic**

消息标题,不管是上行还是下行，发送指令和返回指令的规则是”指令”和”指令\_reply”。格式如下：

```text
下行：20211214/cmd/{#deviceSn}/xxxx
```
对应的返回指令（上行）：20211214/cmd/xxxx\_reply

```text
上行：20211214/event/yyyy
```
对应的返回指令（下行）：20211214/event/{\#deviceSn}/yyyy\_reply

注：20211214是接口版本的特定标识，cmd表示由后台或应用主动给设备发送指令，event表示设备主动给后台或应用发送消息或触发事件。

**消息内容**

文本格式的消息内容，内容为Json格式

**发送消息**

发送指令的格式固定，都包含serianNo、deviceSn、data，如：
```json
{
	"serialNo": "00000001af",
	"deviceSn": "xxxxxxxx",
	"data": ""
}
```
serialNo：消息序列号，10位字符串，包含的字母和数字，必需要有。

deviceSn：设备序列号，设备的唯一地址，用于通讯时保证设备是有效的设备，必须要有。

data：不同的指令对应的 data 内容不一样，可以是任何类型。

**返回消息**

返回消息格式固定都包含serianNo、deviceSn、result、code、message、data，如：
```json
{
	"serialNo": "00000001af",
	"deviceSn": "xxxxxxxx",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "",
	"data": ""
}
```
serialNo：消息序列号，10位字符串，包含的字母和数字。

deviceSn：设备序列号，设备的唯一地址，用于通讯时保证设备是有效的设备。

result ：0表示成功，非0表示失败。

code ：错误码。

message ：出错的原因信息或成功的提示信息，

data：不同的指令对应的 data 内容不一样，可以是任何类型。

## 1.4 注意事项

1. 若调用接口返回提示“参数异常”，请按以下步骤检查：
* 检查参数名称是否拼错、参数名称中是否带有空格或回车。
* 检查参数值是否符合规范，如 Int 值未定义、 id 含有数字字母以外的非法字符等。
* Json 中是否多了或少了"，请仔细核对每个接口的 消息内容。

## 1.5 适用范围

此文档适用范围为：

1. 版本号为： v1\.1\.37\-x 及更高版本的设备。版本号中的 X 表示任意数字。
2. 弃用的接口将用红色字体标识，未使用的接口将用橙色字体标识，某些针对具体设备设备的接口将用蓝色字体标识。

## 1.6 适配设备
| **设备型号** | **设备名称** | **适配版本** | **备注** |
| - | - | - | - |
| VF105 | - |  VF105-v1.1.37-4626316 | VF105 37版本首版 |

# 二、设备管理类接口

## 2.0 接口概述

设备管理类接口提供对智能终端设备的全方位远程管理能力，是构建门禁系统的核心基础。通过这些接口，管理员可以在不接触物理设备的情况下，完成设备的配置、监控、维护和升级等操作。

### 功能分类

| 分类 | 接口 | 功能说明 |
|------|------|----------|
| **安全管理** | 2.1 设置设备密码 | 配置设备登录密码和HTTP接口密码 |
| **状态控制** | 2.2 设备禁用/启用 2.3 设备重置 2.10 远程控制 | 控制设备运行状态、恢复出厂设置、执行远程指令 |
| **系统维护** | 2.4 设备升级 2.5 设备信息查询 2.11 摄像头标定 | 系统升级、获取设备状态、校准摄像头 |
| **配置管理** | 2.6 设备配置查询 2.7 设置设备配置 2.8 网络配置 2.9 设置设备时间 | 查询和修改设备配置参数、网络设置、系统时间 |

### 核心能力

**主界面配置**：设置设备屏幕首页显示内容（如欢迎语、公司 Logo、时间日期、自定义 UI 模块等）；

**认证方式管理**：启用或配置多种身份验证方式，包括人脸识别、二维码扫描、IC/ID卡刷卡、指纹识别等；

**通信协议配置**：设置设备与平台之间的通信方式，例如 MQTT、HTTP、WebSocket 等，包括服务器地址、端口、Topic、QoS 等参数；

**网络功能设置**：配置 Wi\-Fi / 有线网络连接参数、静态 IP 或 DHCP、DNS、NTP 时间同步等；

**系统策略下发**：远程更新设备工作模式（如常开/常闭门禁）、音量、语音提示、休眠策略等。

### 使用建议

1. **初始化配置**：设备首次上线时，建议先调用 `2.1 设置设备密码` 修改默认密码，然后配置 `2.8 网络配置` 确保网络稳定
2. **日常维护**：定期调用 `2.5 设备信息查询` 检查设备状态，关注磁盘空间和系统版本
3. **批量管理**：对于多台设备，建议使用配置模板统一设置，通过 `2.7 设置设备配置` 批量下发
4. **安全策略**：重要操作（如重置、升级）前，建议先 `2.2 设备禁用` 暂停服务，操作完成后再启用

## 2.1 设置设备密码

该接口用于修改设备的登录密码或HTTP协议的配置密码，是设备安全管理的基础接口。设备出厂时设有默认密码，建议设备首次接入网络后立即修改，以保障系统安全。

**2.1.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/password** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 配置数据 | Object | Y | 如下表 |

data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| devOldPwd | WebServer登录密码和配置码密码 | String | Y | 设备默认密码为password，修改密码时，分别传入新、旧密码注：此接口所有操作均会校验此密码，请妥善保管。若忘记密码，则需重置设备恢复默认密码，设备会清空所有数据 |
| devNewPwd | WebServer登录密码和配置码密码 | String | N/Y | 当修改是此项为必填，修改成功后新密码为此项 |
| apiOldPwd | HTTP接口调用密码 | String | N/Y | 注：密码不可为空("")或空格(" ")新设备或重置的设备，调用HTTP接口前，需要先进行初始密码设置，apiOldPwd和apiNewPwd传入一样的值即可 |
| apiNewPwd | HTTP接口调用密码 | String | N/Y | 注：密码不可为空("")或空格(" ")修改密码时，分别传入新、旧密码 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"devOldPwd": "password",
		"devNewPwd": "123456",
		"apiOldPwd": "0",
		"apiNewPwd": "1"
	}
}
```

**2.1.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/password\_reply** |
| --- | --- |

消息参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |
| data | 信息数据 | Object | Y | 详见下表 |

data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| isSetApiPwd | 是否设置接口密码 | Int | Y | 0：未设置，1：已设置 |
| apiPwd | HTTP接口调用密码 | String | N/Y | isSetApiPwd为1时必传 |
| devPwd | WebServer登录密码和配置码密码 | String | N/Y | 新WebServer登录密码和配置码密码，仅在修改密码时为必传 |

返回示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功",
	"data": {
		"isSetApiPwd": 1,
		"apiPwd": "1",
		"devPwd": "123456"
	}
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN\_EXP\-1000 | 未知错误 | 未知错误 |
| | LAN\_EXP\-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| 参数不合法 | LAN\_EXP\-3300 | 密码错误或参数异常 | |
| | LAN\_EXP\-3301 | 密码修改失败 | |
| | LAN\_EXP\-3302 | 接口密码不一致 | |
| | LAN\_EXP\-3303 | 密码初始化失败 | |
| | LAN\_EXP\-3304 | 接口密码错误 | |
| | LAN\_EXP\-3305 | 接口密码修改失败 | |
| 操作正确 | LAN_SUS-0000 | 成功 | 成功 |

## 2.2 设备禁用\启用

该接口用于远程控制设备的启用/禁用状态。设备被禁用后，将暂停所有业务功能（如人脸识别、门禁控制等），仅保留设备管理和系统升级等维护操作。适用于设备维护、异常处理或安全管控场景。

**2.2.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/deviceDisable** |
| --- | --- |

设备禁用\\启用参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 配置数据 | Object | Y | 详见下表 |

data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| isDisable | 是否禁用 | Boolean | Y | true：禁用， false：解除禁用 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"isDisable": true
	}
}
```

**2.2.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/deviceDisable\_reply** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |

返回示例:

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功"
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN\_EXP\-1000 | 未知错误 | 未知错误 |
| | LAN\_EXP\-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| 操作正确 | LAN_SUS-0000 | 设置成功 | |

## 2.3 设备重置

该接口用于将设备恢复到出厂默认状态，会清空所有业务数据（用户、权限、凭证、通行记录等）和配置信息。适用于设备转让、系统故障恢复或重新部署场景。操作后设备将自动重启。

**2.3.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/deviceReset** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest"
}
```

**2.3.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/deviceReset\_reply** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |

返回示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "设备重置成功，自动重启后生效"
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN\_EXP\-1000 | 未知错误 | 未知错误 |
| | LAN\_EXP\-1004 | 设备已被禁用，请先启用再做其它操作 | 设备禁用中，拒绝此接口 |
| | LAN\_EXP\-1005 | 设备正忙，请稍候再试 | 设备正在升级、设置网络或其他任务进行中 |
| 操作正确 | LAN_SUS-0000 | 操作成功。 | 设备即将清空数据，并将设备配置恢复出厂设置 |

## 2.4 设备升级

该接口用于远程升级设备固件或应用程序。通过传入升级包下载地址和MD5校验值，设备会自动下载并安装升级包。支持完整系统升级（PKG包）和增量升级（tar.xz包）两种模式。

**2.4.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/deviceUpgrade** |
| --- | --- |

设备升级参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 升级参数 | Object | Y | 详见下表 |

data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| type | 升级包类型 | Int | Y | 0：升级包为xxx.pkg完整的PKG包升级包较大，适合用于设备整体升级包括（u\-boot、kernel、system）1：升级包为xxx.tar.xz自定义升级包，升级包较小，用来更换配置文件（图片、语音等）、以及应用程序的升级。 |
| url | 升级包地址 | String | Y | 调用接口时访问该 url，设备开始下载文件，但文件不一定正确，是否安装成功需要查看设备具体界面。 |
| md5 | 升级包MD5值 | string | Y | 升级包进行MD5验证 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"type": 1,
		"url": "http://xx.xxx.xx.x/aio.tar.xz",
		"md5": "521c2bdc835d4f13b5f9d6db164f0881"
	}
}
```

**2.4.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/deviceUpgrade\_reply** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |

返回示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "设备即将开始下载"
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN\_EXP\-1000 | 未知错误 | 未知错误 |
| | LAN\_EXP\-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| 参数异常 | LAN\_EXP\-2700 | url 参数异常 | 参数名拼写错误、参数漏传、参数在请求中的位置不正确、参数名带有空格或回车、参数值异常 |
| | LAN\_EXP\-2701 | md5 参数异常 | |
| | LAN\_EXP\-2702 | type 参数异常 | |
| 操作正确 | LAN_SUS-0000 | 设备即将开始下载 | 设备访问 url 并尝试下载文件确 |

## 2.5 设备信息查询

该接口用于查询设备的运行状态和基本信息，包括系统版本、存储空间、网络状态、已注册人员数量等。适用于设备监控、状态巡检和故障排查。

**2.5.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/deviceInformation** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest"
}
```

**2.5.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/deviceInformation\_reply** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |
| data | 信息数据 | Object | Y | 详见下表 |

data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| version | 版本号 | String | Y | 设备系统版本号 |
| subVersion | 应用版本号 | String | Y | 应用程序aio的版本号 |
| releaseData | 应用发布日期 | String | Y | 2021/06/30 |
| sn | 设备地址序列号 | String | Y |  |
| time | 时间 | String | Y | 2021/06/30 当前时间 |
| diskTotal | 设备总空间 | Int | Y | 单位 M |
| diskUsed | 已用空间 | Int | Y | 单位 M |
| diskFree | 剩余空间 | Int | Y | 单位 M |
| persionCount | 注册人员数 | Int | Y |  |
| passRecordCount | 通行记录总数 | Int | Y |  |
| eth0Mac | 以太网mac地址 | String | Y |  |
| wlan0Mac | Wifi无线mac地址 | String | Y |  |
| ppp0Mac | 4g网络mac地址 | String | Y |  |

返回示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功",
	"data": {
		"diskTotal": 5778,
		"diskUsed": 337,
		"diskFree": 5441,
		"version": "v2.0.3rc_r2",
		"subVersion": "VF105-v1.1.37-4225C26",
		"releaseData": "2026/01/09 15:00",
		"sn": "vguangTest",
		"time": "2026/01/10 11:16:01",
		"persionCount": 0,
		"whiteListCount": 1,
		"passRecordCount": 0,
		"eth0Mac": "a8:e2:91:1d:d2:4f",
		"wlan0Mac": "a8:e2:91:1d:d2:4f",
		"ppp0Mac": "00:00:00:00:00:00"
	}
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN\_EXP\-1000 | 未知错误 | 未知错误 |
| | LAN\_EXP\-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| 操作正确 | LAN_SUS-0000 | 查询成功 | 设备信息查询成功 |

## 2.6 设备配置查询

该接口用于查询设备的完整配置信息，包括网络参数、认证方式、显示设置、语音配置等所有可配置项。适用于配置备份、故障排查和批量设备配置同步。

**2.6.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/getConfig** |
| --- | --- |

消息参数说明

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |

消息发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest"
}
```

**2.6.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/getConfig\_reply** |
| --- | --- |

消息参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |
| data | 配置数据 | Object | Y | 详见下表 |

data参数

见 附表3

返回示例：
```json
{
  "serialNo": "0000000001",
  "deviceSn": "vguangTest",
  "result": 0,
  "code": "LAN_SUS-0000",
  "message": "成功",
  "data": {
    "tcpEn": 0,
    " ":" "#略
  }
}
```
返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN\_EXP\-1000 | 未知错误 | 未知错误 |
| | LAN\_EXP\-1004 | 设备已被禁用，请先启用再做其它操作 | 设备禁用中，拒绝此接口 |
| | LAN\_EXP\-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| 操作正确 | LAN_SUS-0000 | 查询成功 | deviceSn 正确即可 |

## 2.7 设置设备配置

该接口用于修改设备的各项配置参数，支持网络设置、认证方式、显示界面、语音提示、工作模式等所有配置项的修改。适用于设备初始化配置、批量配置下发和配置调整。

**2.7.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/setConfig** |
| --- | --- |

消息参数说明

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 配置数据 | Object | Y | 所有配置集合 |

设备配置data域可选参数

见 附表3

消息发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"tcpEn": 0
	}
}
```

**2.7.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/setConfig\_reply** |
| --- | --- |

消息参数说明

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y | 错误码 |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |
| data | 配置数据 | Object | Y | 仅包含当前配置的集合 |

返回示例：
```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "配置成功",
	"data": {
		"tcpEn": 0
	}
}
```
返回错误码

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN\_EXP\-1000 | 未知错误 | 未知错误 |
| |LAN\_EXP\-1004 | 设备已被禁用，请先启用再做其它操作 | 设备禁用中，拒绝此接口 |
| |LAN\_EXP\-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| 参数异常 | LAN\_EXP\-2800 | data参数异常 | data 参数异常 |
| 操作正确 | LAN_SUS-0000 | 设置成功 | "data":{设备当前配置参数} |

## 2.8 网络配置

该接口用于单独配置设备的网络连接参数，包括以太网、WiFi、4G等网络类型的设置。支持DHCP自动获取和静态IP手动配置两种模式，适用于设备网络初始化或网络环境变更场景。

**2.8.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/setNetInfo** |
| --- | --- |

网络配置参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 配置数据 | Object | Y | 所有配置集合 |

网络配置data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| netType | 网络类型 | Int | Y | 0：以太网，1：WiFi，2：4g传入1：设备使用WiFi连接，ssid 必须传入且不可为空 |
| ssid | Wifi账号 | String | N/Y | netType\=1为必填 |
| pwd | WiFi密码 | String | N/Y | netType\=1为必需存在 |
| isDHCPMod | DHCP 模式选择 | bool | Y | 设备默认为 DHCP 模式传入true：设备配置为 DHCP 模式，无须传入其余参数传入 false：自定义网络配置，ip、gateway、subnetMask、dns必须传入且不可为空 |
| ip | ip 地址 | String | N/Y | isDHCPMod\=false为必填，例：192\.168\.1\.123 |
| gateway | 网关 | String | N/Y | isDHCPMod\=false为必填，例：192\.168\.1\.1 |
| subnetMask | 子网掩码 | String | N/Y | isDHCPMod\=false为必填，例：255\.255\.255\.0 |
| dns | DNS服务器 | String | N/Y | isDHCPMod\=false为必填，例：114\.114\.114\.114 |
| MacAddr | MAC地址 | String | N | 只针对netType\=0或1， 00:00:00:00:00:00 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"netType": 0,
		"isDHCPMod": true
	}
}
```

**2.8.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/setNetInfo\_reply** |
| --- | --- |

消息参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |

返回示例

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功"
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN\_EXP\-1000 | 未知错误 | 未知错误 |
| | LAN\_EXP\-1004 | 设备已被禁用，请先启用再做其它操作 | 设备禁用中，拒绝此接口 |
| | LAN\_EXP\-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| 参数异常 | LAN\_EXP\-2400 | netType参数异常 | 传入参数格式错误或缺少必传参数 |
| | LAN\_EXP\-2402 | ssid 参数异常 | netType\=1为必填 |
| | LAN\_EXP\-2403 | pwd 参数异常 | netType\=1为必需存在 |
| | LAN\_EXP\-2404 | isDHCPMod 参数不合法 | |
| | LAN\_EXP\-2405 | ip 参数异常 | isDHCPMod\=false为必填 |
| | LAN\_EXP\-2406 | gateway 参数异常 | isDHCPMod\=false为必填 |
| | LAN\_EXP\-2407 | dns 参数异常 | isDHCPMod\=false为必填 |
| | LAN\_EXP\-2408 | subnetMask 参数异常 | isDHCPMod\=false为必填 |
| 操作正确 | LAN_SUS-0000 | success |  |

## 2.9 设置设备时间

该接口用于手动设置设备的系统时间。当设备无法连接公网进行NTP自动校时，或需要与特定时间源保持同步时，可通过此接口配置Unix时间戳。

**2.9.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/setTime** |
| --- | --- |

时间参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 时间数据 | Object | Y | 详见下表 |

网络配置data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| timestamp | Unix 秒级时间戳 | Int | Y | 配置成功后，设备使用该设置时间若设备未连入公网，时间设置成功后，会按照设置的时间增长若设备连入公网，设备本身有网络时间校对机制（需要设置为自动更新时间），每隔 30 分钟会联网校对一次时间，将设备时间调整与公网时间一致。 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"timestamp": 1617350260
	}
}
```

**2.9.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/setTime\_reply** |
| --- | --- |

消息参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |

返回示例

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功"
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN\_EXP\-1000 | 未知错误 | 未知错误 |
| | LAN\_EXP\-1004 | 设备已被禁用，请先启用再做其它操作 | 设备禁用中，拒绝此接口 |
| | LAN\_EXP\-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| 参数不合法 | LAN\_EXP\-2500 | timestamp 参数异常 | timestamp 含有非法字符 |
| 操作正确 | LAN_SUS-0000 | 设置成功。 |  |

## 2.10 远程控制

该接口用于远程控制设备执行特定动作，包括开门、播报语音、485/韦根输出、播放音频、重启设备等。适用于远程开门、紧急广播、设备维护等场景。

**2.10.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/control** |
| --- | --- |

时间参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 时间数据 | Object | Y | 详见下表 |

网络配置data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| command | 命令 | Int | Y | 1：开继电器，2：播报语音（仅支持中英），3：485输出内容，4：韦根输出内容，5：取消门磁检测异常状态，6：播放音频文件，94：下载企业微信，95：人脸抓拍；96：特征值计算，97：触摸测试，98：屏幕测试，100：重启，101：PING |
| otherData | 其他数据 | String | N | command\=2，播的音频command\=3，传入输出的值command\=4，传入输出的值command\=6：音频文件名称（路径默认为/data/cus\_wav/,名称默认为 cus\_0\.wav）command\=95，传入JSON格式的字符串，例如：{\\"extra\\":{\\"name\\":\\"刘德华\\",\\"type\\":2,\\"userId\\":\\"123\\"}}，其中type为1时只返回图片的base64，为2时只返回特征值，为0时都返回command\=96，传入照片base64值command\=101，PING的地址 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"command": 1
	}
}
```

**2.10.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/control\_reply** |
| --- | --- |

消息参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |
| data | 其他信息 | obj | N |  |

data内容：

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| otherData | 传入的data | String | N | 95时，为传入的otherdata |
| necessaryData | 必要的data | String | Y | 96时为特征值。101时为ping结果 |
| faceBase64 |  | String | N | 95时，type\=0或1有图片 |
| featureBase64 |  | String | N | 95时，type\=0或2有特征值 |
| command | 命令 | Int | Y |  |

返回示例

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功"
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN\_EXP\-1000 | 未知错误 | 未知错误 |
| | LAN\_EXP\-1004 | 设备已被禁用，请先启用再做其它操作 | 设备禁用中，拒绝此接口 |
| | LAN\_EXP\-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| 参数不合法 | LAN\_EXP\-2150 | command参数异常 | command不支持 |
| 操作正确 | LAN_SUS-0000 | 成功 | 成功 |

## 2.11 摄像头标定

该接口用于校准红外活体摄像头与彩色摄像头的位置重合度，确保人脸识别时两个摄像头的画面能够准确对齐。适用于设备安装后首次调试或摄像头位置发生偏移后的重新校准。

**2.11.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/cameraCalibrate** |
| --- | --- |

消息参数说明

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 标定参数 | Object | Y | 详见下表 |

data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| timeout | 标定超时 | Int | Y | 单位秒（注：标定时，设备计算不消耗超时） |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"timeout": 60
	}
}
```

**2.11.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/cameraCalibrate\_reply** |
| --- | --- |

消息参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |

返回示例

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功"
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN\_EXP\-1000 | 未知错误 | 未知错误 |
| | LAN\_EXP\-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| 参数不合法 | LAN\_EXP\-3100 | timeout参数异常 |  |
| 操作正确 | LAN_SUS-0000 | 查询成功 | 设备信息查询成功 |

# 三、用户管理类接口

## 3.0 接口概述

用户管理类接口是门禁系统的核心业务模块，提供完整的人员生命周期管理能力。基于"用户 + 凭证"双层模型设计，实现身份主体与认证载体的解耦，支持灵活的多因子认证和精细化的权限控制。

### 功能分类

| 分类 | 接口 | 功能说明 |
|------|------|----------|
| **用户管理** | 3.1 用户注册 3.2 用户删除 3.3 用户修改 3.4 用户查找 3.5 用户同步 | 用户的增删改查及批量同步操作 |
| **凭证管理** | 3.6 人脸凭证添加 3.7 人脸凭证删除 3.8 人脸凭证查询 3.12 人员注册（feature） | 人脸凭证的管理，支持图片和特征值两种注册方式 |
| **权限管理** | 3.9 用户权限同步 3.10 用户权限查询 | 用户通行权限的配置与查询 |
| **在线认证** | 3.11 在线认证 3.13 同步密钥（VG103动态码） | 实时在线权限校验和动态码认证 |

### 核心设计理念

**"用户 + 凭证"双层模型**

为实现精细化的身份控制与权限治理，37版系统采用双层模型进行人员管理：

1. **先创建用户**：每个操作主体需首先在系统中注册为独立的"用户"实体，包含唯一标识、姓名等基础信息
2. **后绑定凭证**：为已存在的用户关联一个或多个"凭证"（人脸、IC卡、二维码等），同一用户可拥有多种凭证
3. **权限独立授权**：用户的访问权限与其凭证分离，统一基于用户身份进行策略配置

### 核心能力

**多因子认证支持**：同一用户可配置人脸、IC卡、二维码等多种凭证，实现灵活的身份验证方式。

**批量操作能力**：支持用户的批量同步（单次100个用户，不是人脸凭证）和权限的批量下发，提高大规模人员管理效率。

**在线动态认证**：支持在线实时权限校验和动态二维码认证，满足高安全性场景需求。

**数据一致性**：提供完善的查询接口，确保用户、凭证、权限数据在设备与后台系统之间保持一致。

### 使用建议

1. **用户创建流程**：先调用 `3.1 用户注册` 创建用户，再调用 `3.6 人脸凭证添加` 添加凭证，最后通过 `3.9 用户权限同步` 配置权限
2. **批量管理**：对于大规模人员导入，建议使用 `3.5 用户同步` 和 `3.9 用户权限同步` 进行批量操作
3. **离职处理**：人员离职时，调用 `3.2 用户删除` 可同时清除用户、凭证和权限，确保数据安全
4. **在线认证场景**：对于访客管理或临时授权场景，建议开启 `3.11 在线认证` 模式，实现动态权限控制

## 3.1 用户注册

该接口用于在设备上创建新用户，建立用户基本信息（用户ID、姓名、权限类型）。用户创建后，可进一步为其添加人脸、IC卡等凭证。支持创建管理员和普通用户两种权限类型。

**3.1.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/userCreate** |
| --- | --- |

消息参数说明

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 人员信息 | Object | Y | 详见下表 |

data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| userId | 用户ID | String | Y | 用户ID（不允许出现 ',' '\\' '/' 这种字符符号） |
| userName | 用户姓名 | String | N | 用户姓名 |
| userAdmin | 用户方式 | Int | Y | 1：管理员，2：普通用户 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"userId": "00001",
		"userName": "刘德华",
		"userAdmin": 1
	}
}
```

**3.1.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/userCreate\_reply** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |

返回示例

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功"
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 用户注册 | LAN\_EXP\-3101 | 用户ID不能为空 | 用户ID为空 |
| | LAN\_EXP\-3102 | 用户ID已存在 | 用户ID已存在 |
| | LAN\_EXP\-3111 | 创建用户失败 | 创建用户失败 |
| 操作正确 | LAN_SUS-0000 | 用户添加成功 |  |

## 3.2 用户删除

该接口用于删除设备上的用户及其关联数据。删除用户时会同时删除该用户的所有凭证（人脸、IC卡等）和权限信息。支持按用户ID删除指定用户，或清空所有用户数据。

**3.2.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/userDelete** |
| --- | --- |

消息参数说明

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 人员信息 | Object | Y | 详见下表 |

data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| userId | 用户ID | String | N | 存在即删除指定，不存在清空用户表和权限表 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"userId": "00001"
	}
}
```

**3.2.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/userDelete\_reply** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |

返回示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功"
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 用户注册 | LAN\_EXP\-3103 | 用户ID不存在 |  |
| | LAN\_EXP\-3104 | 清空权限表失败，停止后续操 | 清空权限表失败，停止后续操 |
| | LAN\_EXP\-3105 | 凭证表和权限表已清空，清空用户表失败 | 清空用户表失败，停止后续操作 |
| | LAN\_EXP\-3112 | 删除用户失败 |  |
| 操作正确 | LAN_SUS-0000 | 删除用户成功清空用户成功 |  |

## 3.3 用户修改

该接口用于修改已存在用户的基本信息，包括用户姓名和权限类型（管理员/普通用户）。通过用户ID定位目标用户，修改后即时生效。

**3.3.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/userUpdate** |
| --- | --- |

消息参数说明

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 人员信息 | Object | Y | 详见下表 |

data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| userId | 用户ID | String | Y | 用户ID（不允许出现 ',' '\\' '/' 这种字符符号） |
| userName | 用户姓名 | String | N | 用户姓名 |
| userAdmin | 用户方式 | Int | Y | 1：管理员，2：普通用户 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"userId": "00001",
		"userName": "刘德华",
		"userAdmin": 1
	}
}
```

**3.3.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/userUpdate\_reply** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |

返回示例

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功"
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 用户注册 | LAN\_EXP\-3101 | 用户ID为空 |  |
| | LAN\_EXP\-3103 | 用户ID不存在 |  |
| | LAN\_EXP\-3113 | 用户更新失败 |  |
| 操作正确 | LAN_SUS-0000 | 用户更新成功 |  |

## 3.4 用户查找

该接口用于查询设备上的用户信息，支持按用户ID、姓名、权限类型等条件进行筛选。采用分页查询方式，适用于用户列表展示和特定用户检索。

**3.4.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/userFind** |
| --- | --- |

消息参数说明

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 人员信息 | Object | Y | 详见下表 |

data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| Index | 当前页码 | Int | Y |  |
| length | 每页条数 | Int | Y |  |
| userId | 用户ID | String | N |  |
| userName | 用户姓名 | String | N |  |
| userAdmin | 用户权限 | Int | N | 1：管理员，2：普通用户 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"index": 0,
		"length": 1
	}
}
```

**3.4.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/userFind\_reply** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |
| pageInfo | 分页信息 | Obj | Y |  |
| userList | 用户列表 | Array | N |  |

pageInfo参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| size | 查询数量 | Int | Y |  |
| index | 页数 | Int | Y |  |
| length | 每页条数 | String | N |  |
| total | 总数 | String | N |  |
| totalPage | 总页数 | Int | N |  |

userList参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| userId | 用户ID | String | N |  |
| userName | 用户姓名 | String | N |  |
| userAdmin | 用户权限 | Int | N |  |

返回示例

```json
{
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "查询用户成功",
	"seriaNo": "0000000001",
	"success": true,
	"userLists": [
		{
			"userId": "00001",
			"userAdmin": 1,
			"userName": "0001"
		}
	],
	"pageInfo": {
		"totalPage": 1,
		"total": 1,
		"length": 1,
		"index": 0,
		"size": 1
	}
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 用户注册 | LAN\_EXP\-3104 | 分页失败 |  |
| | LAN\_EXP\-3114 | 查找失败 |  |
| | LAN\_EXP\-3115 | 没有这个用户 |  |
| 操作正确 | LAN_SUS-0000 | 用户更新成功 |  |

## 3.5 用户同步

该接口用于批量同步用户数据，支持添加、修改、删除三种操作类型。单次最多处理100个用户，适用于系统初始化、数据迁移或定期同步场景。可选择是否先清空设备现有用户数据。

**3.5.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/userSync** |
| --- | --- |

消息参数说明

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 人员信息 | Object | Y | 详见下表 |

data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| syncFlag | 全量标志 | Int | N | 1：会先清空设备内的用户 |
| userLists | 用户组 | Array | N | 同步的用户数组（单次最大100个） |

userLists参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| sycnType | 操作类型 | Int | Y | 1：添加，2：修改，3：删除 |
| userId | 用户ID | String | N |  |
| userName | 用户姓名 | String | N |  |
| userAdmin | 用户权限 | Int | N | 1：管理员，2：普通用户 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"userLists": [
			{
				"syncType": 1,
				"userId": "00001",
				"userName": "0001",
				"userAdmin": 1
			},
			{
				"syncType": 1,
				"userId": "00002",
				"userName": "0002",
				"userAdmin": 2
			},
			{
				"syncType": 1,
				"userId": "00003",
				"userName": "0003",
				"userAdmin": 2
			}
		]
	}
}
```

**3.5.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/userSync\_reply** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |
| msg | 详细内容 | String | N |  |

返回示例
```json
{
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "用户同步成功",
	"seriaNo": "0000000001",
	"success": false,
	"msg": "第1条数据:创建用户成功,第2条数据:创建用户成功,第3条数据:创建用户成功.添加用户:3,修改用户:0,删除用户:0"
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 用户注册 | LAN\_EXP\-3105 | 用户列别为空 |  |
| 操作正确 | LAN_SUS-0000 | 用户更新成功 |  |

## 3.6 人脸凭证添加

该接口用于为已存在的用户添加人脸凭证，支持通过Base64图片直接注册或触发设备拍照注册。可设置是否替换已有的人脸数据。注册成功后，用户可通过人脸识别进行身份验证。

**3.6.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/personCreate** |
| --- | --- |

消息参数说明

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 人员信息 | Object | Y | 详见下表 |

data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| userFlag | 注册用户表类型 | Int | N | 1：创建管理员权限用户；2：创建普通权限用户；0/不存在：不创建用户。注：如果不创建用户，设备将不能管理内部人员信息 |
| employeeNumber | 用户Id | String | Y | 员工号，E.g SW200 |
| name | 人员名称 | String | Y | 人脸识别显示的名字，必传且有内容。长度128以内。 |
| photoFromCapture | 拍照注册 | Int | N | 1：拍照注册 |
| replace | 替换标志 | Int | N | 1：如果已存在该ID的人脸数据，将替换。 |
| registerBase64 | 照片base64数据 | String | Y/N | 注册人员的Base64图片，当photoFromCapture \= 1时可不传，当photoFromCapture !\= 1时为必传项 |

发送示例：
```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"userFlag": 1,
		"employeeNumber": "0001",
		"replace": 0,
		"name": "0001",
		"photoFromCapture": 0,
		"registerBase64": "/9j/4QAY..."
	}
}
```

**3.6.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/personCreate\_reply** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |

返回示例
```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功"
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN\_EXP\-1000 | 未知错误 | 未知错误 |
| | LAN\_EXP\-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| 参数异常 | LAN\_EXP\-3000 | employeeNumber 参数异常 | 参数名拼写错误、参数漏传、参数在请求中的位置不正确、参数名带有空格或回车、参数值异常 |
| |LAN\_EXP\-3001 | name 参数异常 | |
| |LAN\_EXP\-3002 | registerBase64 参数异常 | |
| 注册异常 | LAN\_EXP\-3003 | employeeNumber 已被占用 | 人员ID已经注册 |
| | LAN\_EXP\-3004 | registerBase64 数据错误 | 非base64编码数据 |
| | LAN\_EXP\-3005 | registerBase64 图片错误 | 图片脸部特征过低，人脸库存在相似度过高的图片等情况。 |
| | LAN\_EXP\-3006 | 拍照注册中 | 上次注册未完成 |
| | LAN\_EXP\-3007 | 注册数量已达最大值 |  |
| 操作正确 | LAN_SUS-0000 | 人员信息添加成功 | 人员信息成功写入数据库确 |

## 3.7 人脸凭证删除

该接口用于删除指定用户的人脸凭证，仅移除人脸数据，不会删除用户本身及其权限信息。删除后该用户将无法通过人脸识别验证，但其他凭证（如IC卡）仍可正常使用。

**3.7.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/personDelete** |
| --- | --- |

消息参数说明

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 人员数据 | Object | Y | 详见下表 |

data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| employeeNumber | 人员 ID | String | Y | 若删除多个人员， 需要用英文逗号拼接如果传入\-1，则删除所有人员只允许数字和英文字母，最大长度为 255 |

发送示例：
```json
{
  "serialNo": "0000000001",
  "deviceSn": "vguangTest",
  "data": {
    "employeeNumber": "-1"
  }
}
```

**3.7.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/personDelete_reply** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |

返回示例
```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功"
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN\_EXP\-1000 | 未知错误 | 未知错误 |
| | LAN\_EXP\-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| 参数异常 | LAN\_EXP\-3000 | employeeNumber 参数异常 | 参数名拼写错误、参数漏传、参数在请求中的位置不正确、参数名带有空格或回车、参数值异常 |
| 操作正确 | LAN_SUS-0000 | 删除成功 | 成功删除指定的 id |

## 3.8 人脸凭证查询

该接口用于查询设备上的人脸凭证信息，支持按用户ID、姓名等条件筛选，可获取人脸照片的Base64数据。适用于凭证备份、数据同步和人员信息核查场景。

**3.8.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/personFind** |
| --- | --- |

消息参数说明

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 查询参数 | Object | Y | 详见下表 |

data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| picLarge | 照片 | Int | N | 是否返回注册时照片，0或者不传不返回，1：返回 |
| employeeNumber | ID | String | N | 查询指定 id 的人脸凭证 |
| name | 姓名 | String | N | 查询指定姓名的人脸凭证 |
| length | 个/页 | int | Y | 返回图片范围(0,50],不返回图片(0,1000] |
| index | 页码 | int | Y | 页码，从 0 开始。 index 的传入值必须小于总页码数，如：总页码数为 1， index 只能传入 0 |

发送示例：
```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"employeeNumber": "",
		"name": "",
		"picLarge": 1,
		"length": 100,
		"index": 0
	}
}
```

**3.8.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/personFind\_reply** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |
| data | 配置数据 | Object | Y | 详见下表 |

人员查询data参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| pageInfo | 查询页数据 | Object | Y | 详见\<pageInfo数据\>表 |
| personInfos | 人员数组 | Array | Y/N | 详见\<personInfos数据\>表 |

pageInfo数据

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| index | 当前页 | Int | Y |  |
| length | 每页大小 | Int | Y |  |
| total | 总数 | Int | Y |  |
| totalPage | 总页数 | Int | Y |  |
| size | 当前页大小 | Int | Y |  |

personInfos数据

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| employeeNumber | 人员ID | String | Y |  |
| name | 人员姓名 | String | Y |  |
| idCardNumber | 卡号 | String | Y |  |
| picBase64 | 注册照片 | String | Y/N | Base64照片数据 |

返回示例
```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功",
	"data": {
		"pageInfo": {
			"index": 0,
			"length": 20,
			"total": 2,
			"totalPage": 1,
			"size": 2
		},
		"personInfos": [
			{
				"employeeNumber": "100001",
				"name": "张三",
				"idCardNumber": "123456",
				"picBase64": "/9j/4AAQSkZJRgABAQEAYAB…"
			},
			{
				"employeeNumber": "100002",
				"name": "李四",
				"idCardNumber": "456789",
				"picBase64": "/9j/4AAQSkZJRgABAQEAYAB…"
			}
		]
	}
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN\_EXP\-1000 | 未知错误 | 未知错误 |
| | LAN\_EXP\-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| | LAN\_EXP\-1006 | The XX method is not supported. | Method 与 url 不匹配 |
| 参数异常 | LAN\_EXP\-3016 | length 参数异常 | 参数名拼写错误、参数漏传、参数在请求中的位置不正确、参数名带有空格或回车、参数值异常 |
| | LAN\_EXP\-3017 | index 参数异常 |  |
| 操作正确 | LAN_SUS-0000 | 查询成功 | 查询操作成功 |

## 3.9 用户权限同步

该接口用于批量同步用户的通行权限配置，包括通行时间段、有效日期、允许的门禁点等。支持添加、修改、删除权限，单次最多处理100条权限记录。适用于权限批量下发和定期同步场景。

**3.9.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/whiteListSync** |
| --- | --- |

消息参数说明

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 人员信息 | Object | Y | 详见下表 |

data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| syncFlag | 同步标识 | Int | Y | 1\-全量，2\-增量 |
| whiteLists | 白名单数组 | Array | N | 白名单Json数组详见下表 |

whiteLists数组，大小最好控制在500以内，单个元素为Object类型，参数如下

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| permissionId | 权限ID | Int | N/Y | 更新必传，用来指定要修改的权限 |
| userFlag | 自动创建用户策略 | Int | N | 指定当设备上不存在该用户时的处理方式： **1** - 自动创建为**管理员**用户 **2** - 自动创建为**普通**用户 **10** - 不检查用户是否存在，直接同步权限（需确保用户已存在） **NULL/0** - 如果用户不存在，**拒绝同步**权限并返回错误 |
| userId | 用户ID | String | Y | 用户ID |
| userName | 用户姓名 | String | Y | 用户姓名 |
| userType | 用户类型 | Int | Y | 100\-普通码，101\-101码制，103\-103码制，202\-卡，303\-人脸，404\-密码 |
| userData | 验证数据 | String | Y | 二维码内容/卡号/人脸ID（默认和用户ID一致）/密码 |
| beginTime | 开始时间 | Int | N | 时间戳，单位秒，小于等于0则不限制结束时间 |
| endTime | 结束时间 | Int | N | 时间戳，单位秒，小于等于0则不限制结束时间 |
| repeatType | 重复类型 | Int | N | 1\-每天重复，2\-每周重复，3\-每月重复，4\-周重复，其他\-不重复 |
| repeatBeginTime | 重复开始时间 | Int | N/Y | repeatType\=1：开始时间为距0点的时间，范围[0,86400]，eg:28800表示当天8点；repeatType\=2：开始时间为周几，取值[1, 7]eg: 1\-周一，2\-周二；repeatType\=3：开始时间为某日，取值[1, 31]。eg：1。 |
| repeatEndTime | 重复结束时间 | Int | N/Y | repeatType\=1：结束时间为距0点的时间，范围[0,86400]。eg:28800表示当天8点；repeatType\=2：结束时间为周几。eg: 1\-周一，2\-周二 … 取值[1, 7]；repeatType\=3：结束时间为某日，取值[1, 31]。eg：1。 |
| weekPeriodTime | 周重复规则 | Object | N/Y | repeatType\=4：周重复规则，规则见下表 |
| syncType | 同步类型 | Int | Y | syncFlag\=2时有效，1\-增加，2\-修改，3\-删除（当为删除时，如果beginTime, endTime\<\=0，则删除所有符合要求的，不忽略userType、userId；如beginTime\>0，则增加条件开始时间beginTime，并匹配userType与userId;如endTime\> 0，则增加条件结束时间endTime，并匹配userType与userId） |

weekPeriodTime参数如下，每天的时间格式为："HH:MM\-HH:MM"，24小时制时分。最多5个时间段，每个时间段用 \| 做分割，内容不要有空格。Eg："08:00\-09:30\|10:00\-11:30"。周1\~7至少有一天为必传

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| 1 | 周一 | String | N/Y | 无此项代表周一无权限，"00:00\-24:00"：代表周一全天有效，Eg:"08:00\-09:30\|10:00\-11:30\|12:00\-13:30\|15:00\-16:30\|17:00\-18:30" |
| 2 | 周二 | String | N/Y | 同上 |
| 3 | 周三 | String | N/Y | 同上 |
| 4 | 周四 | String | N/Y | 同上 |
| 5 | 周五 | String | N/Y | 同上 |
| 6 | 周六 | String | N/Y | 同上 |
| 7 | 周日 | String | N/Y | 同上 |

发送示例：
```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"syncFlag": 1,
		"whiteLists": [
			{
				"userType": 202,
				"userId": "00001",
				"userName": "00001",
				"userData": "cdb332be",
				"beginTime": 1640917147,
				"endTime": 1672453147,
				"repeatType": 0,
				"repeatBeginTime": 0,
				"repeatEndTime": 0,
				"syncType": 1
			}
		]
	}
}
```

**3.9.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/whiteListSync\_reply** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |

返回示例
```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功"
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN\_EXP\-1000 | 未知错误 | 未知错误 |
| | LAN\_EXP\-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| 参数异常 | LAN\_EXP\-3010 | whiteLists白名单数组错误 | 参数名拼写错误、参数漏传 |
| | LAN\_EXP\-3011 | syncFlag 白名单同步标识错误 | syncFlag 必须为1或2 |
| | LAN\_EXP\-3012 | userType 人员类型参数错误 | userType 必须为100，101，103，202，303，404 |
| | LAN\_EXP\-3013 | userId 人员ID参数错误 | userId 必须为6位数字 |
| | LAN\_EXP\-3014 | syncType 同步类型参数错误 | syncType 必须为1，2，3 |
| 操作正确 | LAN_SUS-0000 | 白名单添加成功 | 白名单成功写入数据库 |

## 3.10 用户权限查询

该接口用于查询设备上用户的权限配置信息，支持按用户ID筛选，可获取用户的通行时间段、有效期限、门禁点权限等详细信息。适用于权限核查和审计场景。

**3.10.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/whiteListFind** |
| --- | --- |

消息参数说明

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 人员信息 | Object | Y | 详见下表 |

data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| userType | 用户类型 | Int | N | 100，101，103\-二维码码制，202\-卡，303\-人脸，404\-密码 |
| userId | 用户ID | String | N | 指定用户ID的权限 |
| userData | 权限数据 | String | N | 指定权限数据 |
| beginTime | 开始时间 | Int | N | 若存在且大于0，则只查找 \>\= beginTime |
| endTime | 结束时间 | Int | N | 若存在且大于0，则只查找 \<\= endTime |
| length | 每页最大数量 | Int | Y | (0,1000] |
| index | 页码 | Int | Y | 页码，从 0 开始。 index 的传入值必须小于总页码数，如：总页码数为 1， index 只能传入 0 |

发送示例：
```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"userType": 202,
		"userId": "000002",
		"userData": "cdb332be",
		"beginTime": 1640917147,
		"endTime": 1672453147,
		"length": 100,
		"index": 0
	}
}
```

**3.10.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/whiteListFind\_reply** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |
| data | 配置数据 | Object | Y | 详见下表 |

人员查询data参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| pageInfo | 查询页数据 | Object | Y | 详见\<pageInfo数据\>表 |
| whiteLists | 白名单数组 | Array | Y/N | 详见\< whiteLists数据\>表 |

pageInfo数据

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| index | 当前页 | Int | Y | 当前页 |
| length | 每页大小 | Int | Y | 当前页大小 |
| total | 总数 | Int | Y | 白名单总数 |
| totalPage | 总页数 | Int | Y | 总页数 |
| size | 当前页大小 | Int | Y | 当前页实际白名单数 |

whiteLists数据

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| permissionId | 权限ID | Int | Y |  |
| userId | 用户ID | String | Y |  |
| userType | 用户类型 | Int | Y |  |
| userData | 用户数据 | String | Y | 校验的数据 |
| userName | 用户姓名 | String | N |  |
| beginTime | 开始时间 | Int | Y |  |
| endTime | 结束时间 | Int | Y |  |
| repeatType | 重复类型 | Int | Y |  |
| weekPeriodTime | 周重复规则 | Object | N/Y | repeatType\=4时为必填 |
| repeatBeginTime | 重复开始时间 | Int | Y |  |
| repeatEndTime | 重复结束时间 | Int | Y |  |

返回示例
```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功",
	"data": {
		"pageInfo": {
			"index": 0,
			"length": 20,
			"total": 1,
			"totalPage": 1,
			"size": 1
		},
		"whiteLists": [
			{
				"userType": 202,
				"userId": "cdb332be",
				"beginTime": 1640917147,
				"endTime": 1672453147,
				"repeatType": 0,
				"repeatBeginTime": 0,
				"repeatEndTime": 0
			}
		]
	}
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN\_EXP\-1000 | 未知错误 | 未知错误 |
| | LAN\_EXP\-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| | LAN\_EXP\-1006 | The XX method is not supported. | Method 与 url 不匹配 |
| 参数异常 | LAN\_EXP\-3016 | length 参数异常 | 参数名拼写错误、参数漏传、参数在请求中的位置不正确、参数名带有空格或回车、参数值异常 |
| | LAN\_EXP\-3017 | index 参数异常 | |
| 操作正确 | LAN_SUS-0000 | 查询成功 | 查询操作成功 |

## 3.11 在线认证

该接口用于实现设备的在线权限校验。当设备开启在线认证模式时，对于本地无权限记录的人员，设备会实时向服务器请求权限验证。服务器根据业务逻辑返回认证结果，实现动态权限控制。适用于访客管理、临时授权等场景。

**3.11.1 设备到后台或应用**

| **消息topic** | **topic: 20211214/event/onlineCheck** |
| --- | --- |

消息参数说明

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 标定参数 | Object | Y | 详见下表 |

data参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| userType | 人员类型 | Int | Y | 101\-二维码，202\-卡，303\-人脸，404\-密码 |
| userId | 用户ID | String | Y | 通过凭证内容，找到用户，提取出用户ID |
| orgCode | 原始数据 | String | Y | 二维码内容，卡号，人脸ID，密码内容 |
| passTime | 结束时间 | Int | Y | 时间戳，单位秒 |

发送示例：
```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"userType": 202,
		"userId": "cdb332be",
		"orgCode": "cdb332be",
		"passTime": 1640917147
	}
}
```
**3.11.2 后台或应用回馈到设备**

| **消息topic** | **topic: 20211214/event/{\#deviceSn}/onlineCheck\_reply** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |

返回示例 
```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功"
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN\_EXP\-1000 | 未知错误 | 未知错误 |
| 参数异常 | LAN\_EXP\-3000 | 参数异常 | 参数名拼写错误、参数漏传、参数在请求中的位置不正确、参数名带有空格或回车、参数值异常 |
| 操作正确 | LAN_SUS-0000 | 认证成功 | 认证成功 |

## 3.12 人员注册（feature）

该接口用于通过人脸特征值直接注册用户，适用于已有特征值提取方案的场景。无需传输完整图片，只需下发特征值数据即可完成人脸凭证的添加，可节省网络带宽和注册时间。
如果有相应的方案获取到人脸图片的特征值，也可以通过这个Topic直接将特征值下发给指定用户，相当于给该用户添加人脸凭证。

**3.12.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/registerFeats** |
| --- | --- |

消息参数说明

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 人员信息 | Array | Y | 详见下表 |

data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| employeeNumber | 人员 Id | String | Y | 员工号，E.g SW200 |
| name | 人员名称 | String | Y | 人脸识别显示的名字，必传且有内容。长度128以内。 |
| feature | 人脸特征值 | String | Y | 人脸特征值为2048长度的16进制字符串。 |
| remarks | 备注 | String | N | 用于填写说明信息 |
| replace | 替换标志 | Int | N | 1：若人员ID已注册则替换 |

发送示例：
```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": [
		{
			"employeeNumber": "1",
			"name": "刘德华",
			"feature": "f403370f0afe30fe48eadfff2b03fce8fae01de2f01bf1091321251a4c10fafee504f215fa4435eaca27bc22fe17c206131e370de515f2efe5f2120afc1003e828d107dbfa2219fd0213ff242309f0d222dfecd206fee4f50d1104380eefd4bd4313132c26e9fbf302fec4f9ff1a14ff26ce09d2131ce01d0229081812160f03f90c0d020813eb2c2bf82c0af6c50308fb340d08f9f6131b0ce2010b0be2fb1cc0f014cbfee5d1deefe9e3e32c082b01f6eae4f5dfcc22c51d29f322f5fe12f4e0c205f80b1eedcef0ecaad32329fe1306eced0b06d30f070a054bd1f9f5fd1309e5ec1b1cedcffb1daf1c151701f301062011240fe7f90407e52c07010109ed2234b8de1d0b24fc18161a0bcf1500ef0ce7f2010ff3f9f622ecf7380cf3f9fefad61e0600d52d2cda16f801103437f809de0ddd020afb02edfdfe031d090000171d05d70f132bfd27eb1f2ff607e2e40008c81dcf1c1409f60501fb1acf010a1d1fe2f3e705f311b63b3d04fe1cd6ede101e223390800370d0a25f3eefee81011f1f32c1fe035cef7d1effbd119e90e14fb11fadffdf12432030af3152a1017f6490be004f7ecfe3e3ecb0d1ef3ebf6360ce9e8e9f1e80f033216090f041507fb2b03fdf814240fbbcbf223f313c9ee0cbc1603000707ed21e6e428030519f6fae51ded4d161cdf0efb03ed0113d53cc809f9cbf7102b040105fbeffe102bfa0eaf231a2a0ef607f7fb11feefd5f012c913d1fbef340cb60c010718114b2af81fc6ce3f30dadfedace514fc3ae5db300e05d8c9fe3520e6db62e7f933f8ea0df32137defbeb062ca32d280cb4fcc4ecf729df0111e1e0d801fe14b05fc000d6cf2c18e0eec43408251301c3cd250acb0ebef805010a4d54eaeef0f7110429ff2226fbedd523e7d61319f9288e0dfe530fb4d909ee34d51dfc11ead405de230bd023d82aecd104e8c9ecf2d9dc1f18014fae00fddc265f1fe10cda250bec37fcddf6061ee81217c22c2f4306d22fe1f40724f604b8f4e3c116abf6d422f419f910e51c0a20212a44e1b1460221d33928cde8ee801317fa1d1629e0c2f5053344fd3609dee4562646cd46f91ad9f9ac1374c5d40b1c1fab2e47f9c726c1ec0a1b1b3b23fcfd2dc4f762d9344835f2456041181d0ae93e01d825360225e3ecf9e8e50c2a0017f40b0c07ec0174ff0fe0ea02182f0c2feb07eb1856f2f841d903ffb9db11330f20d0ca530115d9d8b513fdb2c62211083ec314040a23f8ddfdfdd52f22c73122a7e5ead5eeeef3f1bf110aba3e030bd440d3f208080d153c0410f9db0619f80618d4f1ce47bc0f42f2121fe910e5e162facaf0e9c5fa1833361fd623164bfe040afcecd322cad0e70a0afd1ff5012beb4fdc1414ebe0e8fffb15b1c50a223af0c329f6dc32191dbece2a051129fa20fbf5ecd204e8a30eeafbfe2a"
		},
		{
			"id": "2",
			"name": "黎明",
			"feature": "0001020304……"
		}
	]
}
```
**3.12.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/registerFeats\_reply** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |

返回示例:
```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功"
}
```
返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN\_EXP\-1000 | 未知错误 | 未知错误 |
| | LAN\_EXP\-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| 参数异常 | LAN\_EXP\-3000 | employeeNumber 参数异常 | 参数名拼写错误、参数漏传、参数在请求中的位置不正确、参数名带有空格或回车、参数值异常 |
| | LAN\_EXP\-3001 | name 参数异常 | |
| | LAN\_EXP\-3003 | employeeNumber 已被占用 | 人员ID已经注册 |
| | LAN\_EXP\-3007 | 注册数量已达最大值 |  |
| | LAN\_EXP\-3018 | data 数组大小为0 |  |
| | LAN\_EXP\-3019 | Feature参数异常 |  |
| | LAN\_EXP\-3020 | Feature相似度过高 |  |
| 操作正确 | LAN_SUS-0000 | 人员信息添加成功 | 人员信息成功写入数据库确认 |

## 3.13 同步密钥（VG103动态码）

该接口用于下发VG103动态码的加密密钥，实现动态二维码认证功能。动态码具有时效性，每次生成的二维码都不同，可有效防止复制和盗用。适用于高安全性要求的通行场景。

**3.13.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/secretSync** |
| --- | --- |

消息参数说明

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 人员信息 | Array | Y | 详见下表 |

data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| syncFlag | 同步标识 | Int | Y | 1\-全量，2\-增量 |
| secretKeys | 密钥数组 | Array | Y | 详见下表 |

secretKeys参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| secretKeyType | 密钥类型 | String | Y | 密钥类型，如RSA, AES等 |
| secretKeyCode | 密钥编码 | String | Y | 密钥编码，对应密钥编码，如123456 |
| secretKeyValue | 密钥值 | String | Y | |
| secretKeyStartTime | 开始时间 | Int | Y | 密钥开始时间，时间戳（秒） |
| secretKeyExpirytime | 过期时间 | Int | Y | 密钥过期时间，时间戳（秒） |
| syncType | 同步类型 | Int | Y | 同步类型，当SyncFlag\=2时，1\-增加，2\-修改，3\-删除，删除时SecretKeyValue、SecretKeyStartTime、SecretKeyExpirytime为可选，SecretKeyStartTime存在删除\>\=SecretKeyStartTime，SecretKeyExpirytime存在删除\<\=SecretKeyExpirytime |

发送示例：
```json
{
  "serialNo": "00000000f7",
  "deviceAddr": "4E66008FC126",
  "data": {
    "syncFlag": 1,
    "secretKeys": [
    {
      "secretKeyType": "RSA",
      "secretKeyCode": "vguang",
      "secretKeyValue": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAIhGA5XLhPR22MRf7ms4R3NeUyV4UvnUiu2YIrxB4RMojK8QY90760Otx6fWZsEi0gY5ysLWPZSZdu92vA4s1BsCAwEAAQ\=\=",
      "secretKeyStartTime": 1563456783,
      "secretKeyExpirytime": 1963456783,
      "syncType": 1
    }
    ]
  }
}
```
**3.13.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/secretSync\_reply** |
| --- | --- |

消息参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |

返回示例：
```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"message": "成功"
}
```
返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN\_EXP\-1000 | 未知错误 | 未知错误 |
| | LAN\_EXP\-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| 参数异常 | LAN\_EXP\-3000 | employeeNumber 参数异常 | 参数名拼写错误、参数漏传、参数在请求中的位置不正确、参数名带有空格或回车、参数值异常 |
| | LAN\_EXP\-3001 | name 参数异常 | |
| 注册异常 | LAN\_EXP\-3003 | employeeNumber 已被占用 | 人员ID已经注册 |
| | LAN\_EXP\-3007 | 注册数量已达最大值 |  |
| | LAN\_EXP\-3018 | data 数组大小为0 |  |
| | LAN\_EXP\-3019 | Feature参数异常 |  |
| | LAN\_EXP\-3020 | Feature相似度过高 |  |
| 操作正确 | LAN_SUS-0000 | 人员信息添加成功 | 人员信息成功写入数据库确 |

# 四、识别记录

## 4.0 接口概述

识别记录类接口提供对设备识别数据和通行记录的全面管理能力。通过这些接口，可以实现识别记录的查询、删除以及通行记录的实时上报功能，为考勤统计、安全审计和数据分析提供数据支撑。

### 功能分类

| 分类 | 接口 | 功能说明 |
|------|------|----------|
| **记录管理** | 4.1 识别记录删除 4.2 识别记录查询 | 按条件删除或查询历史识别记录 |
| **实时上报** | 4.3 通行记录上报 | 设备主动上报人员通行事件 |

### 核心能力

**识别记录管理**：支持按人员ID、姓名、时间范围等多维度条件查询和删除识别记录，便于数据维护和存储空间管理。

**通行记录上报**：设备实时上报人员通行事件，包括通行时间、人员信息、认证方式、通行结果等关键数据，支持后台实时处理和存储。

**数据完整性**：通行记录包含丰富的上下文信息（如抓拍照片、体温数据等），为安全审计和数据分析提供完整依据。

### 使用建议

1. **定期清理**：建议定期调用 `4.1 识别记录删除` 清理过期数据，避免存储空间不足影响设备正常运行
2. **实时处理**：对于 `4.3 通行记录上报`，建议后台系统实时处理并持久化存储，避免数据丢失
3. **数据同步**：可通过 `4.2 识别记录查询` 定期同步设备上的历史记录到后台数据库，确保数据一致性

## 4.1 识别记录删除

该接口用于删除设备中存储的历史识别记录，支持按人员ID、姓名、时间范围等多维度条件进行精确删除。适用于定期清理过期数据、释放存储空间或满足数据合规要求等场景。删除操作不可逆，请谨慎使用。

**4.1.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/deleteRecords** |
| --- | --- |

消息参数说明

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 删除参数 | Object | Y | 详见下表 |

data参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| employeeNumber | 人员 ID | String | N | 若删除多个人员，用英文逗号拼接。只允许 -1， 数字和英文字母，最大长度为 255，传入 -1 则删除所有人员记录。 |
| startTime | 开始时间 | Int | N | 传入大于0的数删除startTime之后的记录传入小于等于0或不传删除所有 |
| endTime | 结束时间 | Int | N | 传入大于0的数删除endTime之前的记录传入小于等于0或不传删除所有 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"employeeNumber": "-1"
	}
}
```

**4.1.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/deleteRecords\_reply** |
| --- | --- |

消息参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |
| data | 删除数目 | Int | Y | 删除的记录数目 |

返回示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "删除成功",
	"data": 100
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN_EXP-1000 | 未知错误 | 未知错误 |
| | LAN_EXP-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| 操作正确 | LAN_SUS-0000 | 删除成功 | 成功删除识别记录和现场照 |

## 4.2 识别记录查询

该接口用于查询设备中存储的历史识别记录，支持按人员ID、姓名、时间范围、认证方式等多维度条件进行筛选查询。采用分页机制返回结果，适用于数据核对、记录追溯、考勤统计等场景。可获取识别时间、人员信息、认证结果及抓拍照片等完整数据。

**4.2.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/findRecords** |
| --- | --- |

消息参数说明

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 查询参数 | Object | Y | 详见下表 |

data参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| employeeNumber | 人员 ID | String | N | 查询指定 id 的人员识别记录 |
| picLarge | 识别时的照片 | Int | N | 是否返回抓拍照片，0或者不传不返回，1返回 |
| name | 人员姓名 | String | N | 当name不存在时表示不局限于name 查询 |
| startTime | 记录开始时间 | Int | N | 若不按时间查询，不传此项若需要按时间查询，传入时间戳 |
| endTime | 记录结束时间 | Int | N | 若不按时间查询，不传此项若需要按时间查询，传入时间戳 |
| length | 页大小 | Int | Y | 返回图片范围(0, 10],不返回图片(0,1000] |
| index | 页码 | Int | Y | 从 0 开始 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"employeeNumber": "",
		"name": "",
		"picLarge": 1,
		"startTime": -1,
		"endTime": -1,
		"length": 100,
		"index": 0
	}
}
```

**4.2.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/findRecords\_reply** |
| --- | --- |

消息参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |
| data | 配置数据 | Object | Y | 详见下表 |

data参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| pageInfo | 查询页数据 | Object | Y | 详见<pageInfo数据>表 |
| records | 识别记录数组 | Array | Y/N | 详见<records数据>表 |

pageInfo数据

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| index | 当前页 | Int | Y |  |
| length | 每页大小 | Int | Y |  |
| total | 总数 | Int | Y |  |
| totalPage | 总页数 | Int | Y |  |
| size | 当前页大小 | Int | Y |  |

records 数据

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| employeeNumber | 人员ID | String | Y |  |
| name | 人员姓名 | String | Y |  |
| timeStamp | 通行时间戳 | Int | Y |  |
| picBase64 | 通行照片 | String | Y | Base64照片数据 |

返回示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功",
	"data": {
		"pageInfo": {
			"index": 0,
			"length": 100,
			"total": 3,
			"totalPage": 1,
			"size": 3
		},
		"records": [
			{
				"employeeNumber": "100002",
				"name": "刘德华",
				"timeStamp": 1639475284,
				"picBase64": "/9j/4AAQSkZJRgABAQAAAQABAAD…"
			},
			{
				"employeeNumber": "100002",
				"name": "刘德华",
				"timeStamp": 1639475288,
				"picBase64": "/9j/4AAQSkZJRgABAQAAAQABAAD…"
			},
			{
				"employeeNumber": "100002",
				"name": "刘德华",
				"timeStamp": 1639475291,
				"picBase64": "/9j/4AAQSkZJRgABAQAAAQABAAD…"
			}
		]
	}
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN_EXP-1000 | 未知错误 | 未知错误 |
| | LAN_EXP-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| 参数异常 | LAN_EXP-3016 | length 参数异常 | 参数名拼写错误、参数漏传、参数在请求中的位置不正确、参数名带有空格或回车、参数值异常 |
| | LAN_EXP-3017 | index 参数异常 | |
| 操作正确 | LAN_SUS-0000 | 查询成功 | 查询操作成功 |

## 4.3 通行记录上报

该接口用于设备主动实时上报人员通行事件给后台系统。当人员通过设备认证并触发开门时，设备会立即将通行信息（包括时间、人员ID、姓名、认证方式、通行结果、抓拍照片等）推送到后台。支持后台实时处理通行事件，实现考勤统计、安全监控和数据持久化存储。

**4.3.1 设备到后台或应用**

| **消息topic** | **topic: 20211214/event/reportRecords** |
| --- | --- |

消息参数说明

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 上报数据 | Object | Y | 详见下表 |

data参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| records | 通行记录数组 | Array | Y | 详见< records数据>表 |

records数据

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| userId | 用户ID | String | Y | - |
| userType | 用户类型 | Int | Y | 101-二维码，202-卡，303-人脸，404-密码 |
| baseData | 基础数据 | String | Y | 二维码内容，卡内容，密码值 |
| timeStamp | 通行时间戳 | Int | Y | 秒级时间戳 |
| temperature | 体温 | Float | Y | - |
| result | 通行结果 | Int | Y | 0-成功，非0失败 |
| message | 描述信息 | String | Y | - |
| name | 人员姓名 | String | Y/N | 人脸时一定存在。 |
| picBase64 | 通行照片 | String | Y/N | 人脸时一定存在，Base64照片数据 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"records": [
			{
				"userId": "0001",
				"userType": 101,
				"baseData": "&llgyAQASADQxMjcyNTIwMjEwMTAxMTIzNA==@3Fa",
				"timeStamp": 1639475284,
				"result": 0,
				"message": "成功",
				"name": "刘德华",
				"picBase64": "/9j/4AAQSkZJRgABAQEAYABgAAD…"
			}
		]
	}
}
```

**4.3.2 后台或应用回馈到设备**

| **消息topic** | **topic: 20211214/event/{\#deviceSn}/reportRecords\_reply** |
| --- | --- |

消息参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |

返回示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功"
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN_EXP-1000 | 未知错误 | 未知错误 |
| 参数异常 | LAN_EXP-3000 | 参数异常 | 参数名拼写错误、参数漏传、参数在请求中的位置不正确、参数名带有空格或回车、参数值异常 |
| 操作正确 | LAN_SUS-0000 | 认证成功 | 认证成功 |

# 五、信息传递

## 5.0 接口概述

信息传递类接口是设备与后台系统之间保持通信和状态同步的重要机制。通过这些接口，设备可以主动上报自身状态、异常情况和事件信息，后台系统也可以远程获取设备日志和进行故障诊断。

### 功能分类

| 分类 | 接口 | 功能说明 |
|------|------|----------|
| **状态维护** | 5.1 心跳 5.2 遗嘱 5.5 连接上报 | 维护设备在线状态，检测设备异常离线 |
| **事件上报** | 5.4 报警 5.6 门磁状态上报 | 实时上报设备异常和门磁状态变化 |
| **远程诊断** | 5.3 日志 | 远程获取设备日志，辅助故障排查 |

### 核心能力

**在线状态感知**：通过心跳机制和遗嘱消息，后台系统可以实时掌握设备的在线/离线状态，及时发现设备异常。

**实时事件通知**：设备可主动上报报警信息（如拆机报警、门磁异常等），确保后台系统第一时间获知现场情况。

**远程故障诊断**：支持远程提取设备运行日志，便于技术人员进行故障分析和问题定位，降低现场维护成本。

**连接状态同步**：设备连接MQTT成功后主动上报连接信息，便于后台系统统计设备在线率和进行连接管理。

### 使用建议

1. **心跳监控**：建议后台系统监控设备心跳频率，及时发现离线或通信异常设备
2. **报警处理**：对于 `5.4 报警` 上报的异常信息，建议及时通知相关人员处理
3. **日志管理**：定期通过 `5.3 日志` 获取并清理设备日志，避免存储空间不足
4. **门磁联动**：结合 `5.6 门磁状态上报` 实现门禁状态监控和异常开门告警

## 5.1 心跳

该接口用于设备定期向后台系统发送心跳消息，以维持在线状态并上报设备运行状态。心跳消息支持携带自定义数据（如设备温度、存储空间等），并自动附带时间戳。后台系统可通过心跳频率监控设备在线情况，及时发现离线或通信异常。

**5.1.1 设备到后台**

| **消息topic** | **topic: 20211214/event/heartbeat** |
| --- | --- |

消息参数说明

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 心跳数据 | Object | Y | 详见下表 |

data参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| timeStamp | 时间 | Int | Y | 时间戳，单位秒 |
| message | 自定义内容 | String | N |  |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"timeStamp": 1640917147
	}
}
```

**5.1.2 后台回馈到设备**

| **消息topic** | **topic: 20211214/event/{\#deviceSn}/heartbeat\_reply** |
| --- | --- |

消息参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |

返回示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功"
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN_EXP-1000 | 未知错误 | 未知错误 |
| 参数异常 | LAN_EXP-3000 | 参数异常 | 参数名拼写错误、参数漏传、参数在请求中的位置不正确、参数名带有空格或回车、参数值异常 |
| 操作正确 | LAN_SUS-0000 | 认证成功 | 认证成功 |

## 5.2 遗嘱

该接口用于设备异常离线时向后台系统发送遗嘱消息（Last Will and Testament）。当设备与MQTT服务器断开连接且未正常关闭时，服务器会自动发布遗嘱消息通知后台。适用于检测设备掉线、网络故障或设备异常断电等情况，便于后台及时感知设备离线状态。

**5.2.1 设备到后台**

| **消息topic** | **topic: 20211214/event/lwt** |
| --- | --- |

消息参数说明

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 遗嘱数据 | Object | Y | 详见下表 |

data参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| status | 状态 | Int | Y | 1：MQTT离线 |
| message | 提示 | String | N | 提示信息 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"status": 1,
		"message": "异常离线"
	}
}
```

**5.2.2 后台回馈到设备（无需回复）**

| **消息topic** | **topic: 20211214/event/{\#deviceSn}/lwt\_reply** |
| --- | --- |

## 5.3 日志

该接口用于远程提取设备运行日志或清除过期日志数据。设备日志记录了系统运行状态、接口调用记录、异常信息等关键数据。通过远程提取日志，技术人员可进行故障诊断和问题分析，无需现场操作。定期清理日志可释放存储空间，确保设备正常运行。

**5.3.1 后台或应用到设备**

| **消息topic** | **topic: 20211214/cmd/{\#deviceSn}/extractLog** |
| --- | --- |

消息参数说明

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 日志参数 | Object | Y | 详见下表 |

data参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| logTag | 命令 | String | N | 当logTag为："rm /data/log/" 时会清除设备所有日志，清除后需重启设备才可以重新记录 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"logTag": "vbar_log"
	}
}
```

**5.3.2 设备回馈到后台或应用**

| **消息topic** | **topic: 20211214/cmd/extractLog\_reply** |
| --- | --- |

消息参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |
| data | 日志 | String | Y | 日志详情 |

返回示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功",
	"data": "日志详细信息"
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN_EXP-1000 | 未知错误 | 未知错误 |
| | LAN_EXP-1004 | 设备已被禁用，请先启用再做其它操作 | 设备禁用中，拒绝此接口 |
| | LAN_EXP-1005 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进行中 |
| 操作正确 | LAN_SUS-0000 | 成功 | 成功 |

## 5.4 报警

该接口用于设备实时向后台系统上报各类报警事件，包括拆机报警、门磁异常、非法闯入、设备故障等安全相关事件。报警信息包含报警类型、发生时间、现场照片等详细信息。后台系统可基于报警信息及时通知管理人员，实现安全事件的快速响应和处理。

**5.4.1 设备到后台**

| **消息topic** | **topic: 20211214/event/alarm** |
| --- | --- |

消息参数说明

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 报警数据 | Object | Y | 详见下表 |

data参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| alarmType | 报警类型 | Int | Y | 1：表示门磁状态2：火警状态3：异常开门4：开门超时 |
| alarmStatus | 报警状态 | String | Y/N | alarmType=1：必传，0-门磁关，1-门磁开。alarmType=2：必传，0-无火警，1-有火警。alarmType=3：非必传，无。alarmType=4：非必传，无。 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"alarmType": 1,
		"alarmStatus": "1"
	}
}
```
**5.4.2 后台回馈到设备**

| **消息topic** | **topic: 20211214/event/{\#deviceSn}/alarm\_reply** |
| --- | --- |

消息参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| result | 结果 | Int | Y | 0表示成功，非0表示失败 |
| code | 错误码 | String | Y |  |
| message | 错误提示 | String | N | 出错的原因信息或成功的提示信息 |

返回示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"result": 0,
	"code": "LAN_SUS-0000",
	"message": "成功"
}
```

返回说明

| 类型 | Code | msg | 触发原因 |
| --- | --- | --- | --- |
| 通用报错 | LAN_EXP-1000 | 未知错误 | 未知错误 |
| 参数异常 | LAN_EXP-3000 | 参数异常 | 参数名拼写错误、参数漏传、参数在请求中的位置不正确、参数名带有空格或回车、参数值异常 |
| 操作正确 | LAN_SUS-0000 | 认证成功 | 认证成功 |

## 5.5 连接上报

该接口用于设备成功连接MQTT服务器后，主动向后台系统上报连接信息。上报内容包括设备SN、连接时间、IP地址等关键信息。后台系统可基于连接上报统计设备在线率、监控设备接入情况，并进行连接日志记录和审计追溯。

**5.5.1 设备到后台**

| **消息topic** | **topic: 20211214/event/connect** |
| --- | --- |

消息参数说明

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 上报数据 | Object | Y | 详见下表 |

data参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| version | 系统版本号 | String | Y | 系统版本号 |
| subVersion | 应用版本号 | String | Y | 应用版本号 |
| netType | 网络类型 | Int | Y | 网络类型（0:以太网 1:WIFI 2:4G） |
| releaseData | 应用发布日期 | String | Y | 应用发布日期 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"version": "v2.0.4rc_r1",
		"subVersion": "VF203-v1.1.34",
		"releaseData": "2024/05/17 18:00",
		"netType": 0
	}
}
```

**5.5.2 后台回馈到设备（无需回复）**

| **消息topic** | **topic: 20211214/event/connect\_reply** |
| --- | --- |

## 5.6 门磁状态上报

该接口用于设备实时向后台系统上报门磁传感器的状态变化，包括门打开、门关闭、门长时间未关等事件。适用于门禁状态监控、异常开门告警、门未关提醒等场景。后台系统可基于门磁状态实现安全策略联动，如异常开门时触发报警通知。

**5.6.1 设备到后台**

| **消息topic** | ** topic: 20211214/event/dcs** |
| --- | --- |

消息参数说明

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| serialNo | 序列号 | String | Y |  |
| deviceSn | 设备SN | String | Y |  |
| data | 上报数据 | Object | Y | 详见下表 |

data参数

| **参数名** | **描述** | **类型** | **必传** | **附加说明** |
| --- | --- | --- | --- | --- |
| timeStamp | 上报时间戳 | Int | Y |  |
| status | 上报状态 | String | Y | 开门成功；关门成功；开门超时；关门超时；非法闯入 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"deviceSn": "vguangTest",
	"data": {
		"timeStamp": 1640917147,
		"status": "开门成功"
	}
}
```

**5.6.2 后台回馈到设备（无需回复）**

| **消息topic** | **topic: 20211214/event/{\#deviceSn}/dcs\_reply** |
| --- | --- |

# 附表 1 Code 码总览

| Code码 | msg |
| --- | --- |
| 通用错误码 | |
| LAN_SUS-0000 | 接口调用成功， msg 随接口不同而不同 |
| LAN\_EXP\-1000 | 未知异常 |
| LAN\_EXP\-1001 | 密码参数异常 |
| LAN\_EXP\-1002 | 密码错误 |
| LAN\_EXP\-1003 | 接口服务未设置密码，请先设置密码 |
| LAN\_EXP\-1004 | 设备已被禁用，请先启用再做其它操作 |
| LAN\_EXP\-1005 | 设备正忙，请稍后再试 |
| LAN\_EXP\-1006 | The XX method is not supported. |
| LAN\_EXP\-1007 | 请求body错误 |
| LAN\_EXP\-1008 | json格式错误 |
| LAN\_EXP\-1009 | 保存数据出错 |
| LAN\_EXP\-1010 | 设备升级中 |
| LAN\_EXP\-1011 | 设备SN不匹配 |
| 设置密码 | |
| LAN\_EXP\-2000 | oldPass不合法 |
| LAN\_EXP\-2001 | newPass不合法 |
| LAN\_EXP\-2002 | oldPass !\= newPass |
| LAN\_EXP\-2003 | oldPass错误 |
| 禁用设备 | |
| LAN\_EXP\-2100 | isDisable参数不合法 |
| 远程控制 | |
| LAN\_EXP\-2150 | Command 错误 |
| LAN\_EXP\-2151 | 重启失败 |
| 隐藏 IP、设备序列号 | |
| LAN\_EXP\-2200 | ipShow 参数异常 |
| LAN\_EXP\-2201 | snShow 参数异常 |
| 设备序列号获取 | |
| LAN\_EXP\-2300 | 读取SN失败 |
| 网络配置 | |
| LAN\_EXP\-2400 | en 参数异常 |
| ~~LAN\_EXP\-2401~~ | ~~wifiMsg 参数异常~~ |
| LAN\_EXP\-2402 | ssid 参数异常 |
| LAN\_EXP\-2403 | pwd 参数异常 |
| LAN\_EXP\-2405 | ip 参数异常 |
| LAN\_EXP\-2406 | gateway 参数异常 |
| LAN\_EXP\-2407 | dns 参数异常 |
| LAN\_EXP\-2408 | subnetMask 参数异常 |
| 设置设备时间 | |
| LAN\_EXP\-2500 | timestamp 参数异常 |
| 屏幕显示设置 | |
| LAN\_EXP\-2600 | autoScreenOff 参数异常 |
| LAN\_EXP\-2601 | autoScreenOffTime 参数异常 |
| LAN\_EXP\-2602 | autoScreenSaverOff 参数异常 |
| LAN\_EXP\-2603 | autoScreenSaverTime 参数异常 |
| LAN\_EXP\-2604 | autoDisplayBrightness 参数异常 |
| LAN\_EXP\-2605 | displayBrightness 参数异常 |
| 设备升级 | |
| LAN\_EXP\-2700 | url 参数异常 |
| LAN\_EXP\-2701 | md5 参数异常 |
| 设备配置 | |
| LAN\_EXP\-2800 | data 参数异常 |
| 照片注册 | |
| LAN\_EXP\-3000 | employeeNumber 参数异常 |
| LAN\_EXP\-3001 | name 参数异常 |
| LAN\_EXP\-3002 | registerBase64 参数异常 |
| LAN\_EXP\-3003 | employeeNumber 已被占用 |
| LAN\_EXP\-3004 | registerBase64 非base64编码数据 |
| LAN\_EXP\-3005 | registerBase64 图片注册失败,常见错误有：图片脸部特征过低，人脸库存在相似度过高的图片等 |
| LAN\_EXP\-3006 | 拍照注册，上次拍照注册未完成 |
| 白名单 | |
| LAN\_EXP\-3010 | whiteLists白名单数组错误 |
| LAN\_EXP\-3011 | syncFlag 白名单同步标识错误 |
| LAN\_EXP\-3012 | userType 人员类型参数错误 |
| LAN\_EXP\-3013 | userId 人员ID参数错误 |
| LAN\_EXP\-3014 | syncType 同步类型参数错误 |
| LAN\_EXP\-3015 | 全量更新，清空白名单失败 |
| LAN\_EXP\-3016 | length 参数异常,有效范围(0,1000] |
| LAN\_EXP\-3017 | index 参数异常,范围[0, \~] |
| 摄像头标定 | |
| LAN\_EXP\-3100 | timeout 参数异常 |
| 提取日志 |  |
| LAN\_EXP\-3200 | logTag参数异常 |
| 设备密码 | |
| LAN\_EXP\-3300 | 密码错误或参数异常 |
| LAN\_EXP\-3301 | 密码修改失败 |
| LAN\_EXP\-3302 | 接口密码不一致 |
| LAN\_EXP\-3303 | 密码初始化失败 |
| LAN\_EXP\-3304 | 接口密码错误 |
| LAN\_EXP\-3305 | 接口密码修改失败 |

# 附表 2 可用时区列表

| 时区 | |
| --- | --- |
| Asia/Shanghai | 北京时间 |
| Asia/Tokyo | 亚洲/东京 |
| Europe/London | 欧洲/伦敦 |
| Europe/Paris | 欧洲/巴黎 |
| Europe/Berlin | 欧洲/柏林 |
| America/New\_York | 美洲/纽约 |
| Australia/Sydney | 澳洲/悉尼 |
| America/Toronto | 美洲/多伦多 |
| Asia/Hong\_Kong | 香港 |
| Asia/Macau | 亚洲/澳门 |
| Europe/Malta | 欧洲/马耳他 |
| Asia/Singapore | 亚洲/新加坡 |
| Asia/Seoul | 亚洲/首尔 |
| Asia/Taipei | 台北 |
| America/Sao\_Paulo | 美洲/圣保罗 |
| America/Mexico\_City | 美洲/墨西哥城 |
| Europe/Madrid | 欧洲/马德里 |
| Asia/Dubai | 亚洲/迪拜 |
| Asia/Riyadh | 亚洲/利雅得 |
| Asia/Qatar | 亚洲/卡塔尔 |
| Europe/Zurich | 欧洲/苏黎世 |
| Europe/Moscow | 欧洲/莫斯科 |

# 附表 3 配置说明

目前在用的配置，部分已经弃用，可以通过MQTT或HTTP相关协议进行配置。注：绿色代表所有设备均可以使用，蓝色代表特定设备可以使用，红色代表已弃用。

| **字段名称** | | **含义及取值** |
| --- | --- | --- |
| Channel相关配置 | | |
| tcpEn | Int | TCP开关：0：关（默认） 1：开 |
| tcpServerIp | String | TCP服务器IP |
| tcpServerPort | Int | TCP服务器端口号 |
| rsBaudrate | String | RS485波特率，默认："115200\-8\-N\-1" |
| wgDataSize | Int | 26：韦根26， 34：韦根34， 默认；34 |
| relayDelay | Int | 继电器延时时间，单位：毫秒，分度：50ms，默认：2000 |
| relayType | Int | 继电器选择1：SA100模块（占用485通道） 0：设备自身继电器 |
| 扫码相关配置 | | |
| qrEn | Int | 扫码开关：0：关闭， 1：打开（默认） |
| qrAffixesFt | Int | 二维码前后缀格式1：字符串格式，2：十六进制格式 |
| qrPrefix | String | 前缀，默认：""（空） |
| qrPostfix | String | 后缀，默认：""（空） |
| qrCr | Int | 1：末尾加回车，0：不加回车 |
| qrNl | Int | 1：末尾加换行，0：不加换行 |
| qrFt | Int | 韦根输出格式转换0：原始二进制字符 不做转换以下bit位 为1有效bit0：数字字符转hex ："1234" \-\-\> 0x04D2bit1：数字字符转hex反序 ："1234" \-\-\> 0xD204bit2：hex字符转hex ："abcd" \-\-\> 0xabcdbit3：hex字符转hex反序 ："abcd" \-\-\> 0xcdabbit4：数字字符转pid vidbit5：数字字符转pid vid 反序bit6：韦根26输出低3字节（当bit4 or bit5为1时有效） |
| qrCheckInterval | Int | 扫码间隔，单位毫秒（ms） |
| 刷卡相关配置 | | |
| nfcEn | Int | 刷卡开关：0：关闭， 1：打开（默认） |
| nfcFt | Int | 格式转换，0：不转换，1：转成16进制字符格式输出，2：转成10进制字符输出 |
| nfcOrd | Int | 1：反序，0：正序 |
| nfcAffixesFt | Int | 刷卡前后缀格式，1：字符串格式，2：十六进制格式 |
| nfcPrefix | String | 前缀，默认：""（空） |
| nfcPostfix | String | 后缀，默认：""（空） |
| nfcCr | Int | 1：末尾加回车，0：不加回车 |
| nfcNl | Int | 1：末尾加换行，0：不加换行 |
| nfcIdPic | Int | 身份证人脸图片使能 |
| nfcReadIdNum | Int | 1：读取身份证号（云证），0：读取身份证物理卡号 |
| nfcReadIdNumLen | Int | 身份证获取长度 |
| idDetailed | Int | 身份详细信息，多选累加1：姓名；2：性别；4：民族；8：出生日期；16：地址；32：证件号码；64：签发；128：生效日期； 256：失效日期；512：证件图片； |
| nfcType | Int | 刷卡加密方案：0：不加密；1：一卡一密方案；2：固定块方案 |
| nfcPublic | String | 一卡一密公钥 |
| nfcPiece | Int | 加密识别块 |
| nfcKey | String | 固定块：密钥 |
| 人脸相关配置 | | |
| maxTrackFaces | Int | 人脸识别数配置[1,5]注：VF105/VF205生效 |
| recgThreshold | Int | 人脸相似度阀值， 识别分数，越大越自习（0\~100）默认：54 |
| registerThreshold | Float | 注册阈值（0\~100），越大越容易注册成功。 |
| living | Int | 1： 开启活检（默认）， 0： 关闭活检 |
| alarmTemperature | Float | 报警温度：默认37\.3 |
| bodyTemperatureDetect | Int | 1： 打开测温服务模块开关，0： 关闭（默认） |
| exposureValues | Int | 曝光补偿，默认：0 |
| faceRecgEnable | Int | 人脸识别：1：开启（默认），0：关闭 |
| infraredEnable | Int | 红外图像：1：开启，0：关闭（默认） |
| livingDetectThresholdScore | Int | 活体检测阈值（0\~100）默认（10）， 活检算法每次判断人脸视频帧是否活体， 并给出一个分数， 当这个分数累计大于阈值后， 就认为当前是活体， 活体检测阈值越大需要活检的分数越高， 非活体攻击难度越大， 同时可能会影响活体通过率。 |
| maskDetectEnable | Int | 口罩检测，1：打开，0：关闭（默认）注：如果检测到未佩戴口罩，会禁止进入 |
| maskEnable | Int | 口罩识别，1：打开，0：关闭（默认）注：仅识别是否配置口罩 |
| maskThresholdValue | Int | 口罩阈值（0\~100），默认：53 |
| recgDistance | Int | 识别距离（50\~150cm），默认：150根据人脸的像素计算，会有误差 |
| recgInterval | Int | 重复识别的时间间隔单位毫秒ms，默认：1500，注：需大于recgTimeout |
| recgTimeout | Int | 识别超时单位毫秒ms，默认：1000注：最低1000 |
| repeatRecgEnable | Int | 重复识别开关1：打开（默认），0：关闭 |
| strangerVoice | Int | 陌生人语音：对应比特位为1有效bit0：播放请先注册，bit1：播陌生人你好 |
| temperatureCompensation | Int | 温度补偿，默认：0 |
| voiceMode | Int | 语音模式：对应比特位为1有效bit0播报名字，bit1播放问候语 |
| grettings | Int | 问候语：对应比特位为1有效bit0：播放打卡成功，bit1：播放请通行，bit2：播放欢迎光临，bit3：播放时间问候语 |
| registerQualityScore | Int | 注册质量分数，默认30注：识别注册图片的人脸质量，越大越难注册。 |
| 认证模式相关配置 | | |
| recMode | Int | 识别模式1：组合校验，2：任一校验，3：人证核验 |
| faceCardThreshold | Int | 人证核验相似度阀值，仅recMode\=3生效用于判断这个人是否和身份证照片识别通过（0\~100）默认：30 |
| faceCardMode | Int | 仅recMode\=3生效0：仅陌生人仅进行人证核验1：所有人进行人证核验 |
| scannerWorkMode | Int | 工作模式（针对刷卡/扫码/密码）1：协议模式，2：本地白名单模式 |
| faceWorkMode | Int | 工作模式（针对刷脸）1：协议模式，2：本地白名单模式 |
| onlineCheck | Int | 当scannerWorkMode\=4或faceWorkMode\=4时有效1：优先离线。0：只离线 |
| onlineCheckTimeout | Int | 在线验证超时时间，单位毫秒（ms） |
| protocolChannel | Int | 协议通道0：不启动，1：HTTP，2：485，3：TCP |
| httpAddr | String | 协议模式下：HTTP协议回调地址 |
| httpTimeout | Int | HTTP请求超时时间 单位毫秒（ms） |
| 补光灯相关设置 | | |
| infraredLightSet | Int | 补灯光模式，0：长闭，1：长开，2：自动模式 |
| lightSensitive | Int | 光敏控制，1：打开（默认），0：关闭 |
| lightHighBrightness | Int | 环境光高于此值关闭红外检测人脸是否进入识读区域 |
| lightLowBrightness | Int | 环境光低于此值且有人脸进入识读区域打开补光 |
| lightDetInterval | Int | 环境光检测间隔，单位秒，默认：1s |
| lightDelayTime | Int | 自动模式下补光灯亮起延时时间，单位秒，默认：15s |
| lightBrightness | Int | 补光灯亮度 |
| 设备放拆除设置 | | |
| tamperSwitch | Int | 防拆开关，1：打开，0：关闭 |
| 报警相关配置 | | |
| alarmSwitch | Int | 报警服务开关，1：打开，0：关闭 |
| doorSensorDelay | Int | 报警延时，报警信号出发多久后执行，单位秒，默认：30s |
| doorSensor | Int | 报警信号触发类型：0：与地断开触发，1：与地短接触发，2：不触发（默认） |
| alarmOutputSwitch | Int | 报警触发输出开关，1：打开（默认），0：关闭 |
| alarmRelay | Int | alarmOutputSwitch\=1有效1：输出继电器，0：不输出继电器 |
| alarmWgData | Int | alarmOutputSwitch\=1有效0：不输出韦根，n：韦根输出n |
| alarm485Data | String | alarmOutputSwitch\=1有效""（空）：不输出485，"abcd"：485输出"abcd" |
| alarmVoiceData | String | alarmOutputSwitch\=1有效""（空）：播放默认语音，"警报"：播放 "警报" |
| 语音、输出相关配置 | | |
| faceCheckSucRelay | Int | 人脸核验结果成功继电器，0：无动作，1：输出继电器 |
| faceCheckSuc485 | Int | 人脸核验结果成功485输出，0：无输出，1：输出自定义数据，2：输出人员ID |
| faceCheckSuc485Data | String | 人脸核验结果成功485输出数据 |
| faceCheckSucWg | Int | 人脸核验结果成功韦根输出 0: 无输出，1：输出自定义数据，2：输出人员ID |
| faceCheckSucWgData | Int | 人脸核验结果成功韦根输出数据。韦根 26 范围为 1\-65535，有效范围为 5 位；韦根 34 范围为 1\-4294967295，有效范围为 10位。若超出范围，则输出的信号会进行转换，输出无效信号。 |
| faceCheckSucVoice | Int | 人脸核验结果成功语音：0：无语音，1：播放默认语音，2：播放自定义语音 |
| faceCheckSucVoiceData | String | 人脸核验结果成功自定义语音内容 |
| faceCheckFailedVoice | Int | 人脸核验结果失败语音，0：无语音，1：播放默认语音，2：播放自定义语音 |
| faceCheckFailedVoiceData | String | 人脸核验结果失败自定义语音内容 |
| faceCheckSucTip | Int | 人脸核验结果成功弹窗提示：0：无提示，1：默认提示，2：自定义弹窗内容 |
| faceCheckSucTipData | String | 人脸核验结果成功弹窗提示内容 |
| faceCheckFailedTip | Int | 人脸核验结果失败弹窗提示：0：无提示，1：默认提示，2：自定义弹窗内容 |
| faceCheckFailedTipData | String | 人脸核验结果失败弹窗提示内容 |
| cardCheckSucRelay | Int | 刷卡核验结果成功继电器，0：无动作，1：输出继电器 |
| cardCheckSuc485 | Int | 刷卡核验结果成功485输出，0：无输出，1：输出自定义数据，2：输出卡号 |
| cardCheckSuc485Data | String | 刷卡核验结果成功485自定义输出数据 |
| cardCheckSucWg | Int | 刷卡核验结果成功韦根输出，0：无输出，1：输出自定义数据，2：输出卡号 |
| cardCheckSucWgData | Int | 刷卡核验结果成功韦根输出数据。韦根 26 范围为 1\-65535，有效范围为 5 位；韦根 34 范围为 1\-4294967295，有效范围为 10位。若超出范围，则输出的信号会进行转换，输出无效信号。 |
| cardCheckSucVoice | Int | 刷卡核验结果成功语音：0：无语音，1：播放默认语音，2：播放自定义语音 |
| cardCheckSucVoiceData | String | 刷卡核验结果成功自定义语音内容 |
| cardCheckFailedVoice | Int | 刷卡核验结果失败语音，0：无语音，1：播放默认语音，2：播放自定义语音 |
| cardCheckFailedVoiceData | String | 刷卡核验结果失败语音自定义语音内容 |
| cardCheckSucTip | Int | 刷卡核验结果成功弹窗：0：无提示，1：默认提示，2：自定义弹窗内容 |
| cardCheckSucTipData | String | 刷卡核验结果成功弹窗内容： |
| cardCheckFailedTip | Int | 刷卡核验结果失败弹窗：0：无提示，1：默认提示，2：自定义弹窗内容 |
| cardCheckFailedTipData | String | 刷卡核验结果失败弹窗内容： |
| qrCheckSucRelay | Int | 扫码核验结果成功继电器，0：无动作，1：输出继电器 |
| qrCheckSuc485 | Int | 扫码核验结果成功485输出，0：无输出，1：输出自定义数据，2：输出卡号 |
| qrCheckSuc485Data | String | 人脸核验结果成功485输出数据 |
| qrCheckSucWg | Int | 扫码核验结果成功韦根输出，0：无输出，1：输出自定义数据，2：输出卡号，3：输出原始数据 |
| qrCheckSucWgData | Int | 扫码核验结果成功韦根输出数据。韦根 26 范围为 1\-65535，有效范围为 5 位；韦根 34 范围为 1\-4294967295，有效范围为 10位。若超出范围，则输出的信号会进行转换，输出无效信号。 |
| qrCheckSucVoice | Int | 扫码核验结果成功语音：0：无语音，1：播放默认语音，2：播放自定义语音 |
| qrCheckSucVoiceData | String | 扫码核验结果成功语音自定义语音内容 |
| qrCheckFailedVoice | Int | 扫码核验结果失败语音，0：无语音，1：播放默认语音，2：播放自定义语音 |
| qrCheckFailedVoiceData | String | 扫码核验结果失败语音自定义语音内容 |
| qrCheckSucTip | Int | 扫码核验结果成功弹窗：0：无提示，1：默认提示，2：自定义弹窗内容 |
| qrCheckSucTipData | String | 扫码核验结果成功弹窗内容： |
| qrCheckFailedTip | Int | 扫码核验结果失败弹窗：0：无提示，1：默认提示，2：自定义弹窗内容 |
| qrCheckFailedTipData | String | 扫码核验结果失败弹窗内容： |
| pwdCheckSucRelay | Int | 密码核验结果成功继电器，0：无动作，1：输出继电器 |
| pwdCheckSuc485 | Int | 密码核验结果成功485输出，0：无输出，1：输出自定义数据，2：输出卡号 |
| pwdCheckSuc485Data | String | 密码核验结果成功485输出数据 |
| pwdCheckSucWg | Int | 密码核验结果成功韦根输出，0：无输出，1：输出自定义数据，2：输出卡号，3：输出原始数据 |
| pwdCheckSucWgData | Int | 密码核验结果成功韦根输出数据。韦根 26 范围为 1\-65535，有效范围为 5 位；韦根 34 范围为 1\-4294967295，有效范围为 10位。若超出范围，则输出的信号会进行转换，输出无效信号。 |
| pwdCheckSucVoice | Int | 密码核验结果成功语音0：无语音，1：播放默认语音，2：播放自定义语音 |
| pwdCheckSucVoiceData | String | 密码核验结果成功语音自定义语音内容 |
| pwdCheckFailedVoice | Int | 密码核验结果失败语音0：无语音，1：播放默认语音，2：播放自定义语音 |
| pwdCheckFailedVoiceData | String | 密码核验结果失败语音自定义语音内容 |
| pwdCheckSucTip | Int | 密码核验结果成功弹窗：0：无提示，1：默认提示，2：自定义弹窗内容 |
| pwdCheckSucTipData | String | 密码核验结果成功弹窗自定义内容： |
| pwdCheckFailedTip | Int | 密码核验结果失败弹窗：0：无提示，1：默认提示，2：自定义弹窗内容 |
| pwdCheckFailedTipData | String | 密码核验结果失败弹窗自定义内容： |
| 通行记录相关配置 | | |
| saveLargePic | Int | 全景图片：1：保存（默认），0 ：不保存注：全景图片和人脸图片不能同时保存 |
| saveSmallPic | Int | 人脸图片：1：保存，0 ：不保存（默认）注：全景图片和人脸图片不能同时保存 |
| saveStrangerRecord | Int | 陌生人记录：1：保存，0 ：不保存（默认） |
| 预留标签 | | |
| cusTag0\~19 | String | 预留的标签 |
| UI相关配置 | | |
| autoDisplayBrightness | Int | 自动调节屏幕亮度，0：关闭（默认），1：打开 |
| displayBrightness | Int | 屏幕亮度（0\-100）默认：80 |
| autoScreenOff | Int | 自动息屏，0：关闭，1：打开（默认） |
| autoScreenOffTime | Int | 自动息屏时间，默认：300秒 |
| autoScreenSaverOff | Int | 自动屏保 |
| autoScreenSaverTime | Int | 自动屏保时间，默认：30秒 |
| TimeShow | Int | 显示主界面时间 |
| ScreenTimeShow | Int | 显示屏保时间 |
| TimeFormat | Int | 时间格式 |
| DateFormat | Int | 日期格式 |
| ipShow | Int | 显示IP，0：不显示，1：显示 |
| snShow | Int | 显示SN，0：不显示，1：显示 |
| nameShow | Int | 显示识别人脸姓名，0：不显示，1：显示 |
| logoShow | Int | 显示logo |
| logoBase64 | String | Logo图片的base64值 |
| bgBase64 | String | 屏保图片的base64值 |
| opendoorShow | Int | 显示密码开门 |
| volume | Int | 音量（0\-100），默认：50 |
| autoSetTime | Int | 自动更新时间：0：关闭，1：打开（默认） |
| ntpAddress | String | NTP服务器地址 格式：182\.92\.12\.11:123 |
| ntpInterval | Int | NTP更新间隔，单位秒（s） |
| timezone | String | 时区，默认："Asia/Shanghai"，可用时区参见《附表 2 可用时区列表》 |
| deviceName | String | 默认：大门，任意字符串长度小于128 |
| language | Int | 语言，0：中文， 1：英文，2：日语，3：西班牙语，4：法语，5：俄语，6：阿拉伯语 |
| MQTT相关配置 | | |
| mqttAddr | String | 123\.207\.152\.144:61613 |
| mqttClientId | String | MQTT客户端ID：默认设备SN |
| mqttUserName | String | MQTT用户名：默认admin |
| mqttUserPassword | String | MQTT密码：默认password |
| mqttTopicPrefix | String | MQTT订阅主题的前缀 |
| mqttMessageQos | Int | QoS0，At most once，至多一次QoS1，At least once，至少一次QoS2，Exactly once，确保只有一次 |
| mqttHeartEnable | Int | 心跳使能 |
| mqttHeartData | String | 心跳内容 |
| mqttHeartInterval | Int | 心跳间隔 |
| 门磁相关配置（VF203） | | |
| dcEn | Int | 门磁状态持续检测开关1:打开持续检测 0:关闭持续检测 |
| dcOpenTimeout | Int | 门磁打开超时时间，超时未打开发出提示 |
| dcCloseTimeout | Int | 门磁关闭超时时间，超时未关闭发出提示 |
| SA100模块配置| | |
| SA100EncryptionType | Int | 认证密钥类型 |
| SA100Delay | Int | 延时时间 |
| SA100EncryptionAesKey | String | AES密钥 |
| SA100EncryptionAesIv | String | AES向量 |
| SA100EncryptionSm4Key | String | SM4密钥 |
| SA100EncryptionSm4Iv | String | SM4向量 |
| SA100EncryptionSm2Key | String | SM2公钥 |
| SA100EncryptionSm2Public | String | SM2私钥 |
| 网络配置 | | |
| netType | Int | 网络方式（1：无线网络；2：4G网络：其他：以太网） |
| isDHCPMod | Bool | true：动态分配；false：静态分配 |
| ssid | String | 无线网络：名称 |
| pwd | String | 无线网络：密码 |
| ip | String | 静态分配时 ：IP |
| gateway | String | 静态分配时：网关 |
| subnetMask | String | 静态分配时：掩码 |
| dns | String | 静态分配时：DNS |
| eth0Mac | String | 以太网MAC地址 |
| wlan0Mac | String | 无线MAC地址 |
| ppp0Mac | String | 4G模块MAC地址 |

修订记录

| 版本 | 修改日期 | 修改人/审批 | 修改内容 |
| --- | --- | --- | --- |
| v1\.1\.37\-1 | 2025/04/15 | 唯义/唯义 | 1\. 添加配置字段2\. 修改权限接口 |
| v1\.1\.37\-2 | 2025/05/28 | 赵旭龙/赵旭龙 | 1\. 更新 |
| v1\.1\.37\-3 | 2025/06/06 | 赵旭龙/赵旭龙 | 1\. 添加人脸凭证相关接口遗漏的字段2\. 远程控制增加 95 指令 3\. 添加 《三、用户管理类接口》 4\. 添加 ntp 相关配置 |
| v1\.1\.37\-4 | 2025/07/01 | 赵旭龙/赵旭龙 | 1\. 添加企业微信上报 2 .远程控制增加指令 94，下发企业二维码 3\. 添加企业微信配置字段：isWeChat 4\. 添加 VF205 刷卡区域显示开关：nfcTipShow |
| v1\.1\.37\-5 | 2025/07/15 | 赵旭龙/赵旭龙 | 1\. 更新一部分模糊字段的的解释 |
| v1\.1\.37\-6 | 2025/08/15 | 赵旭龙/赵旭龙 | 1\. 补充用户同步缺失参数解释 2\. 更新人脸凭证添加 userFlag 注释 |
| v1\.1\.37\-7 | 2025/08/15 | 赵旭龙/赵旭龙 | 1\. 企业微信模式下，人员注册、人员删除增加返回 employeeNumber 2\. 添加密码语音、输出相关配置 |
| v1\.1\.37\-8 | 2025/08/15 | 赵旭龙/赵旭龙 | 1\. 更新识别模式：recMode，工作模式：scannerWorkMode 和 faceWorkMode，删除成功动作：protocolActionSuc 和失败动作：protocolActionFailed |
| v1\.1\.37\-9 | 2025/10/15 | 赵旭龙/赵旭龙 | 1\. 更新 用户同步接口 2\. 更新人脸凭证添加和人脸凭证删除在企业微信下回复employeeNumber |
| v1\.1\.37\-10 | 2025/10/15 | 赵旭龙/赵旭龙 | 1\. 增加用户同步和用户权限同步在企业微信下回复成功失败数组 2 .更新用户权限同步的描述 |
| v1\.1\.37\-11 | 2025/10/15 | 赵旭龙/赵旭龙 | 1\. 企业微信相关内容迁移到补充文档 |
| v1\.1\.37\-12 | 2026/01/05 | 唯义/唯义 | 1\. 修改格式 |
| v1\.1\.37\-13 | 2026/03/17 | 唯义/唯义 | 1\. 校验 |