门禁标品MQTT协议文档（DejaOS版本）

# MQTT协议文档

## 一. 概述

本文档提供一套适用于人脸设备的标准接口，用于推送获取设备信息，使用者购买设备后，就可以直接根据接口说明进行自定义开发整套门禁或相关应用系统。接口使用MQTT通信协议，可以对接各种通用的MQTT代理，也可使用我们推荐的MQTT代理

**文档版本：V2**

#### 应用场景

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

![](/media/202412/f4b42d80a0bf8947f2360e958fb5811e_20241211161737996824.png)

#### 接口规范

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

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

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

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

1.  消息topic

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

- 下行：access_device/v2/cmd/{#device_sn}/xxxx，对应的返回指令（上行）：access_device/v2/cmd/xxxx_reply
- 上行：access_device/v2/event/yyyy，对应的返回指令（下行）：access_device/v2/event/{#device_sn}/yyyy_reply

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

2. 消息内容

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

a)发送消息

```c
{   
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "time":1647580466, 
    "sign":"e0k4jrir85tje8ru4jrur499r99ii4ur",
       "data": {
        ...
    }
}
```

b) 返回消息

```c
{   
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "time":1647580466, 
    "sign":"e0k4jrir85tje8ru4jrur499r99ii4ur",
       "data": {
        ...
    }
}

```

| 参数名   | 说明         | 类型   | 必须 | 备注                                                         |
| -------- | ------------ | ------ | ---- | ------------------------------------------------------------ |
| serialNo | 序列号       | string | 是   | 后台或应用给设备发送消息必须传递唯一的序列号，不超过32位，设备收到消息后反馈结果的时候会使用同样序列号。反之亦然。 |
| uuid     | 设备唯一标识 | string | 是   | 大于8位的字符串.                                             |
| data     | 消息数据正文 | object | 是   | 为json格式，不同类型的消息正文格式不一样，接口列表中主要是详细列出这部分数据格式 |
| time     | 时间戳       | long   | 是   | 10位长度时间戳，单位秒                                       |
| sign     | 消息签名     | string | 否   | 如果签名启动，这个值必须有，验证数据的合法性。签名的规则请参考：附录-[签名算法] |
| code     | 结果码       | string | 否   | 返回的数据必须包含 code ，不同的 code 表示不同的结果标识。结果码的基本规则请参考：[附表 1](#附表 1 Code 码总览) |

**注：**消息内容中的每一项内容命名，都用小写字母开头，后面可以大小写结合；

## 二. 设备管理和事件接口

#### 2.1 配置查询

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/getConfig |
| --------- | ---------------------------------------------- |

发送data消息参数说明

| 参数名 | 类型  | 必传 | 附加说明                                                |
| :----- | ----- | ---- | ------------------------------------------------------- |
| data   | array | Y    | 查询配置相关信息，详见[配置参数说明](#config)的对象名称 |

消息发送示例：

```c
//获取所有配置
{
    "serialNo": "6w8keif5g6",
    "uuid": "1b89e112c70940f0",
    "time": 1647580466,
    "data": "",
    "sign": ""
}

//获取单个配置
{
	"serialNo": "6w8keif5g6",
	"uuid": "1b89e112c70940f0",
	"time": 1647580466,
	"data":"sysinfo",
	"sign": ""
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/getConfig\_reply |
| --------- | -------------------------------------------- |

data消息参数

| 参数名 | 描述     | 类型   | 必传 | 附加说明 |
| ------ | -------- | ------ | ---- | -------- |
| data   | 配置数据 | Object | Y    | 详见示例 |

返回示例：

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"code": "000000",
    "time": 1701061767,
    "sign": "",
	"message": "成功",
	"data": {
		"nfc": {
			"nfcEn": 1,
			"nfcFt": 0,
			"nfcOrd": 0,
			"nfcAffixesFt": 1,
			"nfcPrefix": "",
			"nfcPostfix": "",
			"nfcCr": 0,
			"nfcNl": 0,
			"nfcReadIdNum": 0
		}
	}
}
```

#### 2.2 配置修改

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

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/setConfig |
| --------- | ---------------------------------------------- |

data消息参数说

| 参数名 | 描述     | 类型   | 必传 | 附加说明                                                     |
| ------ | -------- | ------ | ---- | ------------------------------------------------------------ |
| data   | 配置数据 | Object | N    | 配置集合，可以为空，或者不传这个部分，这个时候设备不会做任何配置修改 |

<a id="config">设备配置data域可选参数</a>

| 对象名称 | 字段名称           | 类型   | 含义及取值                                                   |
| :------- | ------------------ | ------ | ------------------------------------------------------------ |
|          |                    |        | 所有配置参数为非必传，需要配置什么只需传对应对象和字段即可   |
 face  |                    |        |                                                              |
|          | similarity             | Int    | 人脸识别相似度 （默认 0.6，范围0-1）                               |
|          | livenessOff             | Int    | 活体检测 1 开 0 关 默认开                            |
|          | livenessVal             | Int    | 活体检测阈值 （默认 0，范围0-100）                               |
|          | showNir             | Int    | 红外框 1 开 0 关                |
|          | detectMask             | Int    | 口罩检测开关 1 开 0 关                               |
|          | stranger             | Int    | 未注册人脸提示 0:"无语音", 1:"播放请先注册", 2:"播放陌生人你好"       默认 0                        |
|          | voiceMode             | Int    |   识别成功后播放语音    0:"无语音",1:"播放名字", 2:"播放欢迎光临"                        |
 mqtt  |                    |        |                                                              |
|          | addr             | String    | mqtt地址 (格式为192.168.1.1:1883)                               |
|          | username             | String    |  mqtt 账号                             |
|          | password             | String    |  mqtt 密码                              |
|          | qos             | Int    | QoS0，At most once，至多一次 QoS1，At least once，至少一次 QoS2，Exactly once，确保只有一次                |
|          | prefix             | Int    | MQTT 订阅主题的前缀                               |
|          | onlinecheck             | Int    |在线验证开关 1 先走离线失败走在线验证 0 只走离线                               |
|          | willTopic             | Int    | 遗嘱 设备断开连接自动个发送默认access_device/v2/event/offline                               |
| net  |                    |        |                                                              |
|          | type               | Int    | 1：以太网，2：WiFi      3：4G                                     |
|          | ssid               | String | type传入2：设备使用WiFi连接，ssid、pwd参数必须传入且不可为空 |
|          | psk                | String | type传入2：设备使用WiFi连接，ssid、password参数必须传入且不可为空 |
|          | dhcp               | int   | dhcp传入2：设备配置为 DHCP 模式，自动获取动态 IP，无须传入其余参<br />dhcp传入1：自定义网络配置，即手动设置静态IP，ip、gateway、subnetMask、DNS必须传入且不可为空 |
|          | ip                 | String | 例：192.168.1.123                                            |
|          | gateway            | String | 例：192.168.1.1                                              |
|          | mask         | String | 例：255.255.255.0                                            |
|          | dns                | String | 例：114.114.114.114                                          |
 ntp  |                    |        |                                                              |
|          | server             | Int    |  ntp对时服务器ip                            |
|          | interval             | Int    |  对时间隔     单位分钟                       |
|          | gmt             | Int    |时区 中国为 8                |
 access  |                    |        |                                                              |
|          | offlineAccessNum             | Int    |  通行记录存储最大数量                            |
|          | relayTime             | Int    |  继电器打开时长  （默认 2000）                    |
 base  |                    |        |                                                              |
|          | screenOff             | Int    |  熄屏时间，单位分钟，0从不                            |
|          | screensaver             | Int    |  屏幕保护，单位分钟，0从不                    |
|          | brightness             | Int    |  白色补光灯亮度          0-100                  |
|          | volume             | Int    |  喇叭音量默认 50                    |
|          | showIp             | Int    |  是否显示 ip 1显示 0 隐藏                            |
|          | showSn             | Int    |  是否显示  sn 1显示 0 隐藏                        |
|          | language             | String    |   语言  EN英文CN中文                          |
|          | password             | String    |  进入后台密码(默认 123)          |
sys  |                    |        |                                                              |
|          | nfc             | Int    |  刷卡开关 1开 0 关                            |
|          | pwd           | Int    |  密码开门开关  1开 0 关                   |
|          | strangerImage             | Int    |  陌生人保存图片开关 1开 0 关                    |
|          | nfc_identity_card_enable             | Int    |  云证开关 3:云证获取 1:物理卡号

消息发送示例：

```c
{
    "serialNo": "6w8keif5g6",
    "uuid": "e45a00005bc17400",
    "sign": "",
    "code": "000000",
    "data": {
        "net": {
            "gateway": "192.168.60.1",
            "mac": "ee:ed:00:00:5b:c1",
            "password": "",
            "ip": "192.168.63.171",
            "type": 1,
            "mask": "255.255.252.0",
            "dns": "218.4.4.4,218.2.2.2",
            "dhcp": 2,
            "ssid": ""
        },
        "base": {
            "showSn": 1,
            "screenOff": 0,
            "brightness": 100,
            "language": "CN",
            "showIp": 1,
            "screensaver": 0,
            "password": "123",
            "volume": 50,
            "brightnessAuto": 1
        },
        "sys": {
            "uuid": "e45a00005bc17400",
            "model": "vf205",
            "sn": "e45a00005bc17400",
            "status": 1,
            "appVersion": "",
            "version": "vf105_v11_access_2.0.0",
            "releaseTime": "2024-09-13 09:52:00"
        },
        "face": {
            "showNir": 1,
            "livenessVal": 0.6,
            "similarity": 0.6,
            "voiceMode": 1,
            "stranger": 1,
            "livenessOff": 1,
            "detectMask": 0
        },
        "ntp": {
            "interval": 1440,
            "server": "182.92.12.11",
            "gmt": 8,
            "ntp": 1
        },
        "mqtt": {
            "qos": 1,
            "onlinecheck": 0,
            "clientId": "e45a00005bc17400",
            "prefix": "",
            "username": "",
            "willTopic": "access_device/v2/event/offline",
            "addr": "192.168.62.110:1883",
            "password": ""
        },
        "passwordAccess": {
            "passwordAccess": 1
        },
        "access": {
            "offlineAccessNum": 2000,
            "relayTime": 2000,
            "tamperAlarm": 1
        }
    },
    "time": 1736755758
}
```

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

| 消息topic | topic: access_device/v2/cmd/setConfig_reply |
| --------- | ------------------------------------------- |

消息参数说明

| 参数名 | 描述     | 类型   | 必传 | 附加说明           |
| ------ | -------- | ------ | ---- | ------------------ |
| data   | 配置数据 | Object | Y    | 返回配置结果的集合 |

返回示例

```c
{

"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
	"code": "000000",
	"message": "配置成功",
    "sign": "",
	"data": {
		"channel": {
			"enable": 1,
			"tcpAddr": "10.200.52.151",
			"tcpPort": 8060,
			"rs485Bps": "115200-8-N-1",
			"wg": 34
		},
		"qr": {
			"enable": 1,
			"preSufFt": 1,
			"prefix": "",
			"suffix": "",
			"qrCr": 0,
			"qrNl": 0,
			"qrFt": 0
		},
		"nfc": {
			"enable": 1,
			"nfcFt": 0,
			"nfcOrd": 0,
			"preSufFt": 1,
			"prefix": "",
			"suffix": "",
			"nfcCr": 0,
			"nfcNl": 0,
			"IdCard": 0
		},
		"customer": {
			"cusTag0": "1",
			"cusTag1": "0",
			"cusTag2": "cus_tag2",
			"cusTag3": "cus_tag3",
			"cusTag4": "cus_tag4"
		}
	}
}
```

#### 2.3 设备升级（？）

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/upgradeFirmware |
| --------- | ---------------------------------------------------- |

data参数

| 参数名 | 描述                | 类型   | 必传 | 附加说明                                                     |
| ------ | ------------------- | ------ | ---- | ------------------------------------------------------------ |
| type   | 升级包类型          | Int    | 是   | type值强校验 0：本机升级 10：资源升级(当前版本不支持)                        |
| url    | 下载 包地址OTA 升级 | String | Y    | 调用接口时访问该 url，若 url 能访问到，则设备开始执行下载文件；若 url 访问失败，则接口 返回提示“url 访问失败，设备无法下载”设备开始下载，但文件不一定正确，是否安装成功需要查看设备具体界面 |
| md5    | 升级包MD5值         | string | Y    | 升级包进行MD5验证                                            |
| extra  | 扩展字段            | Object | Y    |                                                              |

当`type=10`时 `extra`字段必填 json 支持字段如下表

|    参数名     | 说 明  | 类 型  | 必 须 | 备 注    |
| :-----------: | :----: | :----: | :---: | :------- |
| 背景图 、音频 | 文件名 | String |  否   | 文件名称 |

发送示例：

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
    "time": 0,
    "sign": "",
	"data": {
        "type": 0,
		"url": "http://10.102.106.165/aio.tar.xz",
		"md5": "521c2bdc835d4f13b5f9d6db164f0881"
	}
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/upgradeFirmware\_reply |
| --------- | -------------------------------------------------- |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "设备即将开始下载"
}
```

#### 2.4 远程控制

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/control |
| --------- | -------------------------------------------- |

网络配置data参数

| 参数名  | 描述     | 类型   | 必传 | 附加说明                                                     |
| ------- | -------- | ------ | ---- | ------------------------------------------------------------ |
| command | 命令     | Int    | Y    | 0：重启 1：远程开门 2：设备启用 3：设备禁用 4：设备重置<br/>5:播放语音 6：屏幕展示图片 7：屏幕展示文字<br /> 9：删除日志<br /> 10：上传小程序码 (目前只支持 0 1 4 5 10)|
| extra   | 扩展字段 | String | Y    | 见extra扩展表                                                |

extra扩展表

| 参数名  | 说 明        | 类 型  | 必 须 | 备 注                                                        |
| ------- | ------------ | ------ | ----- | ------------------------------------------------------------ |
| wav     | 音频文件名   | String | 否    | command=5时传入，具备喇叭的设备会播报指定音频，音频文件可通过升级固件接口上传 |
| image   | 图片文件名   | String | 否    | command=6时传入，具备屏幕的设备会弹出指定图片，图片文件可通过升级固件接口上传 |
| timeout | 展示时间     | Int    | 否    | command=6时传入，单位:`ms`，UI显示图片的时间 此项不存在默认显示时间:`1500ms` |
| msg     | 提示信息     | String | 否    | command=7时传入，具备屏幕的设备会弹出指定提示信息            |
| timeout | 提示时间     | Int    | 否    | command=7时传入，单位:`ms`，UI显示`msg`的时间 此项不存在默认显示时间:`1500ms` |
| cmd     | 删除日志命令 | String | 否    | command=9时传入，传"rm /data/log/" 会清除设备所有日志，清除后需重启设备才可以重新记录 |
| qrCodeBase64     | 上传小程序码 | String | 否    | command=10时传入 |

发送示例：

```c
{
    
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
    "time": 0,
    "sign": "",
	"data": {
		"command": 1
	}
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/control\_reply |
| --------- | ------------------------------------------ |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "成功"
}
```

#### 2.5 报警(暂不支持)

- 设备到后台或应用

| 消息topic | topic: access_device/v2/event/alarm |
| --------- | ----------------------------------- |

data参数

| 参数名 | 描述     | 类型   | 必传 | 附加说明                                                   |
| ------ | -------- | ------ | ---- | ---------------------------------------------------------- |
| type   | 上报类型 | Int    | Y    | 参考[附表 3 设备告警类型表](#附表 3 设备告警类型表)-type值 |
| value  | 上报状态 | String | N    |                                                            |

发送示例：

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
    "time": 0,
    "sign": "",
	"data": {
		"type": 1,
		"status": 1,
        "timeStamp":1785963258
	}
}
```

- 后台或应用回馈到设备

| 消息topic | topic: access_device/v2/event/{\#uuid}/alarm\_reply |
| --------- | --------------------------------------------------- |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "成功"
}
```

#### 2.6 心跳（未启用）

- 设备到后台或应用

| 消息topic | topic: access_device/v2/event/heartbeat |
| --------- | --------------------------------------- |

发送示例：

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
    "time": 0,
    "sign": ""
}
```

- 后台或应用回馈到设备(无需返回)

| 消息topic | topic: access_device/v2/event/{\#uuid}/heartbeat\_reply |
| --------- | ------------------------------------------------------- |

#### 2.7 遗嘱

- 设备到后台或应用

| 消息topic | topic: access_device/v2/event/offline |
| --------- | ------------------------------------- |

发送示例：

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
    "time": 0,
    "sign": ""
}
```

- 后台或应用回馈到设备（无需回复）

| 消息topic | topic: access_device/v2/event/{\#uuid}/offline\_reply |
| --------- | ----------------------------------------------------- |

#### 2.8 连接上报

- 设备到后台或应用

| 消息topic | topic: access_device/v2/event/connect |
| --------- | ------------------------------------- |

网络配置data参数

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

发送示例：

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
    "time": 0,
    "sign": "",
	"data": {
		"version": "v2.0.4rc_r1",
		"appVersion": "VF105-v2.1.34",
		"releaseTime": "2024/05/17 18:00",
		"netType": 0
	}
}
```

- 后台或应用回馈到设备（无需回复）

| 消息topic | topic: access_device/v2/event/connect\_reply |
| --------- | ----------------------------------------- |

#### 2.9 在线验证

- 设备到后台或应用

| 消息topic | topic: access_device/v2/event/access_online |
| --------- | ------------------------------------------- |

data参数

| 参数名  | 说明     | 类型   | 必须 | 备注                                                         |
| :------ | :------- | :----- | ---- | ------------------------------------------------------------ |
| code    | 权限凭证 | String | 是   | 如果是人脸则为空                                             |
| type    | 权限类型 | Int    | 是   | 参考[附录-设备状态码表](http://wiki.dxiot.com:90/zh/duoxian/设备协议文档/微光/门禁人脸机MQTT协议文档#typeDetails)-type列 |
| index   | 门控编号 | String | 否   | 比如设备是一控四，index可能就是1，2，3，4 ,可以为空          |
| time    | 通行时间 | Long   | 是   | 时间戳单位秒                                                 |
| extra   | 额外参数 | Object | 否   | 可扩展，通常是记录原始数据，比如扫二维码的原文               |
| srcData | 数据原文 | String | 否   | 原始数据                                                     |

发送示例：

```c
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "code":"s345463434gg",
        "type": 103,
        "time": 1640917147,
        "extra":{
          "srcData" : "vg://v203AQAGAHZndWFuZwIAQAAlcOsQMXN9TJGCK5Afs14p4orxE+QnmI4gb2F85pvrvbQW1/+CyPEE1Bi3X4T3SYFZRoheykjICfdwWU+kw/Vf2965"
        }
    },
    "time": 1647580466,
    "sign": ""
}
```

- 后台或应用回馈到设备

| 消息topic | topic: access_device/v2/event/{\#uuid}access_online\_reply |
| --------- | ---------------------------------------------------------- |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "成功"
}
```

## 三. 人员管理类接口

#### 3.1 添加人员

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/insertUser |
| --------- | ----------------------------------------------- |

data参数（一次限制100以内）

| 参数名 | 描述     | 类型   | 必传 | 附加说明                                               |
| ------ | -------- | ------ | ---- | ------------------------------------------------------ |
| userId | 人员 Id  | String | Y    | 唯一不可重复，只可输入字母数字，长度128字节，E.g SW200 |
| name   | 人员名称 | String | Y    | name 参数必传且内容不可为空。长度128字节。             |
| extra  | 额外参数 | Object | 否   | 其他额外人员属性                                       |

发送示例：

```c
{
	"serialNo": "6w8keif5g6",
	"uuid": "0a1b2c3d",
	"data": [{
			"userId": "20190101120101",
			"name": "张三",
			"extra": {
				"xxxx": xxxx
			}
		},
		{
			"userId": "20190101120102",
			"name": "李四",
			"extra": {
				"xxxx": "xxxx"
			}
		}
	],
	"time": 1647580466,
	"sign": ""
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/insertUser\_reply |
| --------- | --------------------------------------------- |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "成功"
}
```

#### 3.2 删除人员

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/delUser |
| --------- | -------------------------------------------- |

data参数

| 参数名 | 描述    | 类型  | 必传 | 附加说明           |
| ------ | ------- | ----- | ---- | ------------------ |
| data   | 人员 ID | array | Y    | 每个成员都是人员Id |

发送示例：

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
	"sign": "",
	"data": ["001","002","003"]
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/delUser\_reply |
| --------- | ------------------------------------------ |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "成功"
}
```

#### 3.3 清空人员

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/clearUser |
| --------- | ---------------------------------------------- |

发送示例：

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
	"sign": ""
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/clearUser_reply |
| --------- | ------------------------------------------- |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "成功"
}
```

#### 3.4 查询人员

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/getUser |
| --------- | -------------------------------------------- |

data参数

| 参数名 | 描述         | 类型   | 必传 | 附加说明                                                     |
| ------ | ------------ | ------ | ---- | ------------------------------------------------------------ |
| userId | 人员 ID      | String | N    | • 查询指定 id 的人员信息 • id                                |
| name   | 人员姓名     | String | N    | 当name不存在时表示不局限于name 查询人员                      |
| page   | 每页最大数量 | int    | Y    | 返回范围(0,100]                                              |
| size   | 页码         | int    | Y    | 页码，从 0 开始。 index 的传入值必须小于总页码数，如：总页码数为 1， index 只能传入 0 |

发送示例：

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
	"sign": "",
	"data": {
		"id": "",
		"name": "",
		"page": 0,
		"size": 10
	}
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/getUser\_reply |
| --------- | ------------------------------------------ |

人员查询data参数

| 参数名    | 描述       | 类型  | 必传 | 附加说明               |
| --------- | ---------- | ----- | ---- | ---------------------- |
| page      | 当前页     | Int   | Y    | 当前页                 |
| size      | 每页大小   | Int   | Y    | 当前页大小             |
| total     | 总数       | Int   | Y    | 总数                   |
| totalPage | 总页数     | Int   | Y    | 总页数                 |
| count     | 当前页大小 | Int   | Y    | 当前页实际数           |
| content   | 权限数组   | Array | Y    | 详见\< content数据\>表 |

content数据

| 参数名 | 描述     | 类型   | 必传 | 附加说明 |
| ------ | -------- | ------ | ---- | -------- |
| id     | 人员ID   | String | Y    |          |
| name   | 人员姓名 | String | Y    |          |
| extra  | 扩展字段 | Object | N    | extra表  |

extra表

| 参数名   | 描述     | 类型 | 必传 | 附加说明 |
| -------- | -------- | ---- | ---- | -------- |
| userType | 人员类型 | Int  | N    |          |
| addSrc   | 注册来源 | Int  | N    |          |
| addTime  | 注册时间 | Int  | N    |          |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"result": 0,
	"code": "000000",
	"message": "成功",
	"data": {
		"page": 0,
		"size": 20,
		"total": 2,
		"totalPage": 1,
		"count": 2,
		"content": [{
				"id": "100001",
				"name": "张三",
            	"extra": {
                    "userType": 0,
					"addSource": 2,
					"addTime": 0,
                }
			},
			{
				"id": "100002",
				"name": "李四",
            	"extra": {
                    "userType": 0,
					"addSource": 2,
					"addTime": 0,
                }
			}
		]
	}
}
```

## 四. 凭证管理接口

#### 4.1 添加凭证

- 后台或应用到设备

| 消息topic | topic:access_device/v2/cmd/{\#uuid}/insertKey |
| --------- | --------------------------------------------- |

data参数（一次限制100以内）

| 参数名 | 必填     | 类型   | 说明 | 备注                                                         |
| ------ | -------- | ------ | ---- | ------------------------------------------------------------ |
| keyId  | 凭证id   | String | 是   | 凭证唯一id标识                                               |
| userId | 人员id   | String | 是   | 人员的唯一id标识                                             |
| type   | 凭证类型 | String | 是   | 参考[附录-凭证类型](#附表 4 权限类型说明)-num列              |
| code   | 凭证数据 | String | 是   | 人脸类型传base64(是否支持其他类注册)，人脸类型仅支持单个下发，并且不能和其他类型凭证同一个包下发 |
| extra  | 额外参数 | Object | 否   | 其他额外凭证属性                                             |

extra表

| 参数名   | 描述         | 类型   | 必传 | 附加说明                                   |
| -------- | ------------ | ------ | ---- | ------------------------------------------ |
| faceType | 注册人脸类型 | String | Y    | 0：base64，1：特征值，2：Url下载，3：zip包 |
|          |              |        |      |                                            |

发送示例：

```c
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": [{
            "keyId": "20190101120101",
            "userId": "20190101120101",
            "type": "300",
            "code": "ZnNmZHNmYXNkZmFzZGY=........",
        	"extra":{
                "faceType":"301"
            }
        },
        {
            "keyId": "20190101120101",
            "userId": "20190101120102",
            "type": "103",
            "code": "1233456"
        }
    ],
    "time": 1647580466,
    "sign": ""
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/insertKey_reply |
| --------- | ------------------------------------------- |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "成功"
}
```

#### 4.2 查询凭证

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/getKey |
| --------- | ------------------------------------------- |

data参数

| 参数名 | 描述               | 类型   | 必传 | 附加说明                                                     |
| ------ | ------------------ | ------ | ---- | ------------------------------------------------------------ |
| keyId  | 凭证id             | String | N    | 人员的唯一id标识                                             |
| userId | 人员 ID            | String | N    | 凭证的唯一id标识                                             |
| type   | 查询该id下某一类型 | int    | N    | 参考[附录-凭证类型](#附表 4 权限类型说明)-num列              |
| size   | 每页最大数量       | int    | Y    | 返回范围(0,100]                                              |
| page   | 页码               | int    | Y    | 页码，从 0 开始。 index 的传入值必须小于总页码数，如：总页码数为 1， index 只能传入 0 |

发送示例：

```c
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data":{
      "keyId": "20190101120101",
      "userId": "20190101120101",
      "type":300,
      "page": 0,
      "size": 10
    },
    "time": 1647580466,
    "sign": ""
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/getKey\_reply |
| --------- | ----------------------------------------- |

人员查询data参数

| 参数名    | 描述       | 类型  | 必传 | 附加说明               |
| --------- | ---------- | ----- | ---- | ---------------------- |
| page      | 当前页     | Int   | Y    | 当前页                 |
| size      | 每页大小   | Int   | Y    | 当前页大小             |
| total     | 总数       | Int   | Y    | 总数                   |
| totalPage | 总页数     | Int   | Y    | 总页数                 |
| count     | 当前页大小 | Int   | Y    | 当前页实际数           |
| content   | 凭证数组   | Array | Y    | 详见\< content数据\>表 |

content数据

| 参数名 | 必填     | 类型   | 说明 | 备注                                                         |
| :----- | :------- | :----- | ---- | ------------------------------------------------------------ |
| keyId  | 凭证id   | String | Y    | 凭证唯一id标识                                               |
| userId | 人员id   | String | Y    | 人员的唯一id标识                                             |
| type   | 凭证类型 | String | Y    | 参考[附录-凭证类型](http://wiki.dxiot.com:90/zh/duoxian/设备协议文档/微光/门禁人脸机MQTT协议文档#typeDetails)-num列 |
| code   | 凭证数据 | String | Y    | 人脸类型传base64                                             |
| extra  | 额外参数 | Object | N    | 其他额外凭证属性                                             |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"result": 0,
	"code": "000000",
	"message": "成功",
	"data": {
		"page": 0,
		"size": 20,
		"total": 2,
		"totalPage": 1,
		"count": 2,
		"content": [{
				"keyId": "100001",
            	"userId": "13",
				"type": "",
				"code": "卡凭证值",
            	"extra": {
					"xxxx":xxx
                }
			},
			{
				"keyId": "100002",
                "userId": "12",
				"type": "",
				"code": "码凭证值"
			}
		]
	}
}
```

#### 4.3 删除凭证

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/delKey |
| --------- | ------------------------------------------- |

data参数

| 参数名  | 必填   | 类型  | 说明 | 备注             |
| :------ | :----- | :---- | ---- | ---------------- |
| keyIds  | 凭证id | array |  否   | 凭证唯一id标识 （传入删除单个凭证，传此项后不传userIds）  |
| userIds | 人员id | array | 否  | 人员的唯一id标识 （传入删除人员下所有凭证，传此项后不传keyIds）|

发送示例：

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
	"sign": "",
	"data": {
        "keyIds":["20190101120101","20190101120102"],
        "userIds":["20190101120101","20190101120102"]
    }
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/delKey\_reply |
| --------- | ----------------------------------------- |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "成功"
}
```

#### 4.4 清空凭证

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/clearKey |
| --------- | --------------------------------------------- |

发送示例：

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
	"sign": ""
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/clearKey\_reply |
| --------- | ------------------------------------------- |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "成功"
}
```

## 五. 权限管理接口

#### 5.1 添加权限

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/insertPermission |
| --------- | ----------------------------------------------------- |

data参数（一次限制100以内）

| 参数名       | 说明     | 类型   | 必须 | 备注                                                         |
| :----------- | :------- | :----- | ---- | ------------------------------------------------------------ |
| permissionId | 权限Id   | String | 是   | 权限的唯一标识，添加和删除时根据这个标识来判定，建议传32位随机值 |
| userId       | 人员Id   | String | 是   | 人员唯一标识                                                 |
| time         | 时间区间 | Int    | 是   | [查看时间区间](#附表 5 时间区间说明)                         |
| extra        | 额外参数 | Object | 否   | 其他额外凭证属性                                             |

发送示例：

```c
{
	"scerialNo": "123456",
	"sign": "",
	"time": 1704866881,
	"uuid": "deb3637225b41faf",
	"data": [{
		"permissionId": "6584132",
		"userId": "6584132",
		"extra": {
			"xxx": 1
		},
		"time": {
			"type": 3,
			"weekPeriodTime": {
				"1": "9:00-14:05",
				"2": "12:00-13:30|15:00-16:30"
			},
			"range": {
				"beginTime": 1640917147,
				"endTime": 1790917147
			}
		}
	}]

}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/insertPermission\_reply |
| --------- | --------------------------------------------------- |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "成功"
}
```

#### 5.2 查询权限

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/getPermission |
| --------- | -------------------------------------------------- |

data参数

| 参数名       | 描述         | 类型   | 必传 | 附加说明                                                     |
| ------------ | ------------ | ------ | ---- | ------------------------------------------------------------ |
| permissionId | 唯一凭证     | String | N    |                                                              |
| userId       | 人员id       | String | N    |                                                              |
| page         | 每页最大数量 | Int    | Y    | 返回范围(0,100]                                              |
| size         | 页码         | Int    | Y    | 页码，从 0 开始。 index 的传入值必须小于总页码数，如：总页码数为 1， index 只能传入 0 |

发送示例：

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
	"sign": "",
	"data": {
        "page": 0,
		"size": 100
	}
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/getPermission\_reply |
| --------- | ------------------------------------------------ |

人员查询data参数

| 参数名    | 描述       | 类型  | 必传 | 附加说明               |
| --------- | ---------- | ----- | ---- | ---------------------- |
| page      | 当前页     | Int   | Y    | 当前页                 |
| size      | 每页大小   | Int   | Y    | 当前页大小             |
| total     | 总数       | Int   | Y    | 总数                   |
| totalPage | 总页数     | Int   | Y    | 总页数                 |
| count     | 当前页大小 | Int   | Y    | 当前页实际数           |
| content   | 权限数组   | Array | Y    | 详见\< content数据\>表 |

content数据

| 参数名       | 描述     | 类型   | 必传 | 附加说明                             |
| ------------ | -------- | ------ | ---- | ------------------------------------ |
| permissionId | 唯一凭证 | String | Y    |                                      |
| time         | 时间区间 | String | Y    | [查看时间区间](#附表 5 时间区间说明) |
| extra        | 扩展字段 | Object | N    |                                      |

返回示例

```c
{
	"serialNo": "6w8keif5g6",
	"uuid": "4eb393143b1eaee1",
	"sign": "",
	"code": "000000",
	"data": {
		"content": [{
			"id": "6584132",
			"userId": "12345",
			"time": {
				"type": 3,
				"range": {
					"beginTime": 1640917147,
					"endTime": 1790917147
				},
				"weekPeriodTime": {
					"1": "9:00-14:05",
					"2": "12:00-13:30|15:00-16:30"
				}
			},
			"extra": {
				"xxx": "xxx",
				"xxxx": "xxxx"
			}
		}],
		"page": 0,
		"size": 200,
		"total": 1,
		"totalPage": 1,
		"count": 1
	},
	"time": 1711595116
}
```

#### 5.3 删除权限

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/delPermission |
| --------- | -------------------------------------------------- |

data参数

| 参数名        | 说明   | 类型  | 必须 | 备注                                                         |
| :------------ | :----- | :---- | ---- | ------------------------------------------------------------ |
| userIds       | 人员Id | array | 是   | 人员唯一标识                                                 |
| permissionIds | 权限Id | array | 是   | 权限的唯一标识，添加和删除时根据这个标识来判定，建议传32位随机值 |

发送示例：

```c
{
	"serialNo": "6w8keif5g6",
	"uuid": "0a1b2c3d",
	"data": {
		"permissionIds": ["20190101120101", "20190101120102"],
		"userIds": ["20190101120101", "20190101120102"]
	},
	"time": 1647580466,
	"sign": ""
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/delPermission\_reply |
| --------- | ------------------------------------------------ |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "成功"
}
```

#### 5.4 清空权限

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/clearPermission |
| --------- | ---------------------------------------------------- |

发送示例：

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
	"sign": ""
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/clearPermission\_reply |
| --------- | -------------------------------------------------- |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "成功"
}
```

## 六. 密钥管理接口

#### 6.1 添加密钥

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/insertSecurity |
| --------- | --------------------------------------------------- |

data参数（一次限制100以内）

| 参数名     | 描述      | 类型   | 必传 | 附加说明                         |
| ---------- | --------- | ------ | ---- | -------------------------------- |
| securityId | 权限id    | String | Y    | 密钥的唯一标识                   |
| type       | 密钥类型  | String | Y    | 密钥类型，如RSA, AES等           |
| key        | 密钥编码  | String | Y    | 密钥编码，对应密钥编码，如vguang |
| value      | 密钥key值 | String | Y    |                                  |
| startTime  | 开始时间  | Int    | Y    | 密钥开始时间，时间戳（秒）       |
| endTime    | 过期时间  | Int    | Y    | 密钥过期时间，时间戳（秒）       |

发送示例：

```c
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": [{
            "type": "RSA",
            "securityId": "213v",
            "key": "vguang",
            "value": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAIhGA5XLhPR22MRf7ms4R3NeUyV4UvnUiu2YIrxB4RMojK8QY90760Otx6fWZsEi0gY5ysLWPZSZdu92vA4s1BsCAwEAAQ==",
            "startTime": 1560303425,
            "endTime": 1683918932
        },
        {
            "type": "RSA",
            "securityId": "213t",
            "key": "test",
            "value": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAIhGA5XLhPR22MRf7ms4R3NeUyV4UvnUiu2YIrxB4RMojK8QY90760Otx6fWZsEi0gY5ysLWPZSZdu92vA4s1BsCAwEAAQ==",
            "startTime": 1560303425,
            "endTime": 1683918932
        }
    ],
    "time": 1647580466,
    "sign": ""
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/insertSecurity\_reply |
| --------- | ------------------------------------------------- |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "成功"
}
```

#### 6.2 查询密钥

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/getSecurity |
| --------- | ------------------------------------------------ |

data参数

| 参数名     | 描述         | 类型   | 必传 | 附加说明                                                     |
| ---------- | ------------ | ------ | ---- | ------------------------------------------------------------ |
| securityId | 权限id       | String | Y    | 密钥的唯一标识                                               |
| type       | 密钥类型     | String | Y    | 密钥类型，如RSA, AES等                                       |
| code       | 密钥编码     | String | Y    | 密钥编码，对应密钥编码，如vguang                             |
| page       | 每页最大数量 | Int    | Y    | 返回范围(0,100]                                              |
| size       | 页码         | Int    | Y    | 页码，从 0 开始。 index 的传入值必须小于总页码数，如：总页码数为 1， index 只能传入 0 |

发送示例：

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
	"sign": "",
	"data": {
        "securityId": "001",
		"type": "RSA",
		"code": "vguang",
		"startTime": 1640917147,
		"endTime": 1672453147
	}
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/getSecurity\_reply |
| --------- | ---------------------------------------------- |

data参数

| 参数名    | 描述       | 类型  | 必传 | 附加说明               |
| --------- | ---------- | ----- | ---- | ---------------------- |
| page      | 当前页     | Int   | Y    | 当前页                 |
| size      | 每页大小   | Int   | Y    | 当前页大小             |
| total     | 总数       | Int   | Y    | 总数                   |
| totalPage | 总页数     | Int   | Y    | 总页数                 |
| count     | 当前页大小 | Int   | Y    | 当前页实际数           |
| content   | 动态码数组 | Array | Y    | 详见\< content数据\>表 |

content数据

| 参数名    | 描述     | 类型   | 必传 | 附加说明                         |
| --------- | -------- | ------ | ---- | -------------------------------- |
| type      | 密钥类型 | String | Y    | 密钥类型，如RSA, AES等           |
| code      | 密钥编码 | String | Y    | 密钥编码，对应密钥编码，如vguang |
| key       | 密钥值   | String | Y    |                                  |
| startTime | 开始时间 | Int    | Y    | 密钥开始时间，时间戳（秒）       |
| endTime   | 过期时间 | Int    | Y    | 密钥过期时间，时间戳（秒）       |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
	"sign": "",
	"code": "000000",
	"message": "成功",
	"data": {
		"page": 0,
		"size": 20,
		"total": 1,
		"totalPage": 1,
		"count": 1,
		"content": [{
            "securityId": "001",
			"type": "RSA",
			"code": "vguang",
			"key": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAIhGA5XLhPR22MRf7ms4R3NeUyV4UvnUiu2YIrxB4RMojK8QY90760Otx6fWZsEi0gY5ysLWPZSZdu92vA4s1BsCAwEAAQ==",
			"startTime": 1563456783,
			"endTime": 1963456783
		}， {
            "securityId": "002",
			"type": "RSA",
			"code": "vguang",
			"key": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAIhGA5XLhPR22MRf7ms4R3NeUyV4UvnUiu2YIrxB4RMojK8QY90760Otx6fWZsEi0gY5ysLWPZSZdu92vA4s1BsCAwEAAQ==",
			"startTime": 1563456783,
			"endTime": 1963456783
		}]
	}
}
```

#### 6.3 删除密钥

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/delSecurity |
| --------- | ------------------------------------------------ |

data参数

| 参数名 | 描述    | 类型  | 必传 | 附加说明       |
| ------ | ------- | ----- | ---- | -------------- |
| data   | 权限 ID | array | Y    | 每个成员都是id |

发送示例：

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
	"sign": "",
	"data": ["001","002","003"]
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/delSecurity_reply |
| --------- | --------------------------------------------- |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "成功"
}
```

#### 6.4 清空密钥

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/clearSecurity |
| --------- | -------------------------------------------------- |

发送示例：

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
	"sign": ""
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/clearSecurity_reply |
| --------- | ----------------------------------------------- |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "成功"
}
```

## 七. 识别记录

#### 7.1 识别记录查询

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/getRecords |
| --------- | ----------------------------------------------- |

data参数

| 参数名    | 描述         | 类型   | 必传 | 附加说明                                                     |
| --------- | ------------ | ------ | ---- | ------------------------------------------------------------ |
| userId    | 唯一凭证     | array  | N    | 查询指定 凭证 的人员识别记录 ，传入-1 可查询所有人员的识别记录 |
| name      | 人员姓名     | String | N    | 当name不存在时表示不局限于name 查询                          |
| startTime | 记录开始时间 | Int    | N    | 若不按时间查询，不传此项 若需要按时间查询，传入时间戳        |
| endTime   | 记录结束时间 | Int    | N    | 若不按时间查询，不传此项 若需要按时间查询，传入时间戳        |
| page      | 页大小       | Int    | Y    | 返回图片范围(0, 50],不返回图片(0,1000]                       |
| size      | 页码         | Int    | Y    | 从 0 开始                                                    |

发送示例：

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
	"sign": "",
	"data": {
		"userId": ["001","002"],
		"name": "",
		"startTime": -1,
		"endTime": -1,
		"page": 0,
		"size": 100
	}
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/getRecords\_reply |
| --------- | ---------------------------------------------- |

data 数据

人员查询data参数

| 参数名    | 描述       | 类型  | 必传 | 附加说明               |
| --------- | ---------- | ----- | ---- | ---------------------- |
| page      | 当前页     | Int   | Y    | 当前页                 |
| size      | 每页大小   | Int   | Y    | 当前页大小             |
| total     | 总数       | Int   | Y    | 总数                   |
| totalPage | 总页数     | Int   | Y    | 总页数                 |
| count     | 当前页大小 | Int   | Y    | 当前页实际数           |
| content   | 记录数组   | Array | Y    | 详见\< content数据\>表 |

content数据

| 参数名    | 描述                         | 类型   | 必传 | 附加说明                                                     |
| --------- | ---------------------------- | ------ | ---- | ------------------------------------------------------------ |
| userId    | 用户ID                       | String | Y    |                                                              |
| type      | 用户类型                     | Int    | Y    | 当人卡码任一时参考[附表 3 权限类型说明](#附表 3 权限类型说明)-num，，若人卡\人码合一时，填写人卡301，人码302 |
| timeStamp | 通行时间戳                   | Int    | Y    |                                                              |
| result    | 通行结果                     | Int    | Y    | 0-成功，非0失败                                              |
| name      | 人员姓名                     | String | N    |                                                              |
| code      | 通行照片/卡号/码值/密码/蓝牙 | String | Y/N  | type=300/301/302，其他填写Base64照片数据，其他类型填写对应凭证值 |
| extra     | 其他数据                     | Object | N    | 当人卡\人码合一时，填写卡号或码值；可填写体温信息            |
| error     | 错误信息                     | String | N    |                                                              |

extra表

| 参数名      | 描述                         | 类型   | 必传 | 附加说明                        |
| ----------- | ---------------------------- | ------ | ---- | ------------------------------- |
| temperature | 体温                         | Float  | N    |                                 |
| code        | 通行照片/卡号/码值/密码/蓝牙 | String | N    | 人卡/人码核验时，填写卡值或码值 |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"result": 0,
	"code": "000000",
	"message": "成功",
	"data": {
		"index": 0,
		"length": 100,
		"total": 3,
		"totalPage": 1,
		"size": 3,
		"content": [{
				"userId": "100002",
				"name": "常永彬",
				"timeStamp": 1639475284,
				"code": "/9j/4AAQSkZJRgABAQAAAQABAAD…"
			},
			{
				"userId": "100002",
				"name": "常永彬",
				"timeStamp": 1639475288,
				"code": "/9j/4AAQSkZJRgABAQAAAQABAAD…"
			},
			{
				"userId": "100002",
				"name": "常永彬",
				"timeStamp": 1639475291,
				"code": "/9j/4AAQSkZJRgABAQAAAQABAAD…"
			}
		]
	}
}
```

#### 7.2 识别记录删除

- 后台或应用到设备

| 消息topic | topic: access_device/v2/cmd/{\#uuid}/delRecords |
| --------- | ----------------------------------------------- |

data参数

| 参数名    | 描述     | 类型  | 必传 | 附加说明                                                     |
| --------- | -------- | ----- | ---- | ------------------------------------------------------------ |
| userId    | 唯一凭证 | array | N    |                                                              |
| startTime | 开始时间 | Int   | N    | 传入大于0的数删除startTime之后的记录 传入小于等于0或不传删除所有 |
| endTime   | 结束时间 | Int   | N    | 传入大于0的数删除endTime之前的记录 传入小于等于0或不传删除所有 |

发送示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
	"sign": "",
	"data": {
		"userId": ["123"]
	}
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/delRecords\_reply |
| --------- | --------------------------------------------- |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "成功"
}
```

####

#### 7.3 通行记录上报

- 设备到后台或应用

| 消息topic | topic: access_device/v2/event/access |
| --------- | ------------------------------------ |

消息参数说明

data参数

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

content数据

| 参数名    | 描述                         | 类型   | 必传 | 附加说明                                                     |
| --------- | ---------------------------- | ------ | ---- | ------------------------------------------------------------ |
| userId    | 用户ID                       | String | Y    |                                                              |
| type      | 用户类型                     | Int    | Y    | 当人卡码任一时参考[附表 3 权限类型说明](#附表 3 权限类型说明)-num，，若人卡\人码合一时，填写人卡301，人码302 |
| timeStamp | 通行时间戳                   | Int    | Y    |                                                              |
| result    | 通行结果                     | Int    | Y    | 0-成功，非0失败                                              |
| name      | 人员姓名                     | String | N    |                                                              |
| code      | 通行照片/卡号/码值/密码/蓝牙 | String | Y/N  | type=300/301/302，其他填写Base64照片数据，其他类型填写对应凭证值 |
| extra     | 其他数据                     | Object | N    | 当人卡\人码合一时，填写卡号或码值；可填写体温信息            |
| error     | 错误信息                     | String | N    |                                                              |

extra表

| 参数名      | 描述                         | 类型   | 必传 | 附加说明                        |
| ----------- | ---------------------------- | ------ | ---- | ------------------------------- |
| temperature | 体温                         | Float  | N    |                                 |
| code        | 通行照片/卡号/码值/密码/蓝牙 | String | N    | 人卡/人码核验时，填写卡值或码值 |

发送示例：

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"time": 0,
	"sign": "",
	"data": {
		"content": [
			{
				"userId": "412725202101011234",
				"type": 302,
				"timeStamp": 1639475284,
				"result": 0,
				"error": "成功",
				"name": "张三",
				"code": "/9j/4AAQSkZJRgABAQEAYABgAAD…",
                "extra":{
                    "code":"&llgyAQASADQxMjcyNTIwMjEwMTAxMTIzNA==\@3Fa"
                }
			},
			…
		]
	}
}
```

- 后台或应用回馈到设备

| 消息topic | topic: access_device/v2/event/{\#uuid}/access\_reply |
| --------- | ----------------------------------------------------------- |

返回示例

```c
{
	"serialNo": "0000000001",
	"uuid": "p0Lx8TI3mpOr",
	"result": 0,
	"code": "000000",
	"message": "成功"
}
```

附表 1 Code 码总览
------------------

| 类型     | code          | 信息                   | 说明                                                       |
| -------- | ------------- | ---------------------- | ---------------------------------------------------------- |
| 成功     | 000000        | 成功执行指令           | 无                                                         |
| 通用报错 | 100000        | 未知错误               | 无                                                         |
| 通用报错 | 100001        | 设备已被禁用           | 设备禁用后很多指令不允许执行                               |
| 通用报错 | 100002        | 设备正忙，请稍后再试   | 设备正在升级、设置网络或其他任务进程中                     |
| 通用报错 | 100003        | 签名检验失败           | 无                                                         |
| 通用报错 | 100004        | 超时错误               | 无                                                         |
| 通用报错 | 100005        | 设备离线               | 无                                                         |
| 参数异常 | 200000-299999 | 参数异常               | 不同的指令对应不同的参数规范，参考每个接口后的参数异常描述 |
| 其它异常 | 300000-399999 | 其它已知原因导致的异常 | 不同的指令对应不同的异常，参考每个接口后的参数异常描述     |

## 附表 2 设备告警类型表

| 类型     | type | value                        | door         |
| -------- | ---- | ---------------------------- | ------------ |
| 门磁状态 | 0    | 0：门磁关、1：门磁开         | 对应门的序号 |
| 火警状态 | 1    | 0：火警关、1：火警开         | 无           |
| 非法开门 | 2    | 无                           | 无           |
| 开门超时 | 3    | 无                           | 无           |
| 关门超时 | 4    | 无                           | 无           |
| 升级汇报 | 5    | 0：升级失败、1：升级成功完成 | 无           |
| 防拆报警 | 6    | 0：正常 1：拆除报警          | 无           |

## 附表 3 权限类型说明

| type        | num           | 说明                                          |
| ----------- | ------------- | --------------------------------------------- |
| face        | 300           | 300:人脸数据                                  |
| qrcode      | 100、101、103 | 100：透传码,101：静态码 ,103：动态码          |
| password    | 400           | 400：密码数据 ，密码长度：6位                 |
| card        | 200           | 200:普通卡号，201：cpu加密卡，202：扇区加密卡 |
| fingerprint | 500           | 500：指纹数据                                 |
| bluetooth   | 600           | 600:蓝牙开门凭证                              |
| openButton  | 800           | 800:开门按钮                                  |

## 附表 4 时间区间说明

支持下面四种时间区域设置：

- 1.缺省模式，不限时间，一直有效

```c
{
    "type": 0
}
```

- 2.通常模式，从开始到结束时间内有效

```c
{
    "type": 1,
    "range": {
      "beginTime": 1640917147,
      "endTime": 1690917147
    }
}
```

- 3.每日模式，每日特定时间到特定时间内有效(时间戳为当日零点到该时间的秒数)

```c
{
    "type": 2,
    "beginTime": 30600,
    "endTime": 66600,
    "range": {
      "beginTime": 1640917147,
      "endTime": 1690917147
    }
}
```

- 4.周重复模式，周一到周日特定时间到特定时间内有效，其它时间无效(每天的多组时间段不重叠，最多支持五组)。weekPeriodTime参数如下，每天的时间格式为："HH:MM-HH:MM"，24小时制时分，Eg："08:00-09:30|10:00-11:30"最多5个时间段。1~7至少有一天为必传,无此项代表无权限，"00:00-24:00"：代表全天有效，多个时间段用 | 分割中间不要有空格，每天最多5个时间段Eg:"08:00-09:30|10:00-11:30|12:00-13:30|15:00-16:30|17:00-18:30"

```c
{
    "type": 3,
    "weekPeriodTime":{
      "1":"9:00-10:00",
      "2":"12:00-13:30|15:00-16:30"
    },
    "range": {
      "beginTime": 1640917147,
      "endTime": 1690917147
    }
}
```