DW200_V2.1.0双协议门禁MQTT协议文档（DejaOS版本）

# 概述
#### 应用场景
   本文档提供二套直接访问门禁设备的接口，分为 V1/V2两种协议使用者购买设备后，就可以直接根据接口说明进行自定义开发整套门禁或相关应用系统。接口使用 MQTT 通信协议，可以对接各种通用的 MQTT 代理，但是我们推荐使用门禁网关来统一管理设备。==此协议只适配 V2.1.0以上版本==

#### 接口规范
接口使用 MQTT 协议，按方向分为上行与下行：
- **上行**：是指设备上发消息给后台或应用。
- **下行**：是指后台或应用下发消息给设备。

按发起方分为：指令类、事件类
- **指令类**：是由应用平台发起，先**下行**，给设备发送指令，再**上行**，设备返回给应用平台
- **事件类**：是由设备主动发起，先**上行**，设备上报到平台应用一些数据，再**下行**，平台应用返回给设备一个回复

消息格式是标准的 MQTT 报文结构，包含消息 Topic 与消息内容，格式如下：

1) 消息 Topic：消息标题，不管是上行还是下行，发送指令和返回指令的 Topic 基本规则是 **指令** 和 **指令_reply**。格式如下：

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

v2：
    - 下行：`access_device/v2/cmd/{#uuid}/xxxx` ，对应的返回指令（上行）：`access_device/v2/cmd/xxxx_reply`
    - 上行：`access_device/v2/event/yyyy` ，对应的返回指令（下行）：`access_device/v2/event/{#uuid}/yyyy_reply`
>注：其中access是门禁的特定标识，cmd 表示由后台或应用先主动给设备发送指令，event 表示设备主动给后台或应用发送消息或触发事件，{#uuid} 表示设备的唯一标识

2) 消息内容:文本格式的消息内容，内容为Json格式
发送消息内容的示例如下：

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

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

# V1 协议
## 1.1 配置查询
- 说明： 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/cmd/{#uuid}/getConfig  `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：
    - data 可以为空，或者不传这个部分，这个时候设备将返回所有配置数据
    - data 可以为string，因为配置数据是 kye/value 对应的 json 格式的对象，所以如果传入一个指定的 key，就可以返回设备里这个 key 对应的 value。

- 请求示例
```json
//获取所有数据
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "time": 1647580466,
    "sign": ""
}
//获取网络相关数据
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "time": 1647580466,
    "data": "netInfo"
    "sign": ""
}
```

- 说明: 
- 流向：设备 -> 平台
- Topic：**`access_device/v1/cmd/getConfig_reply`**
- 内容：[标准格式](#content)
- data 部分：json 格式，key/value 对应很多属性。详情参考[DW200 门禁系统配置项文档](http://wiki.koodle.cn:10086/doc/631/)
  主要分以下几个大类：
    - `sysInfo`: 设备系统资源信息，包括设备CPU、存储,设备基础信息，包括设备类型、版本、uuid 等等
    - `netInfo`: 设备网络相关信息，包括设备ip、wifi用户密码等等
    - `mqttInfo`: mqtt 服务端相关信息，包括服务的ip、端口等等
    - `scanInfo`: 设备扫码相关配置信息
    - `doorInfo`:设备控制门相关的信息，包括开门时长等等
    - `uiInfo`:UI相关配置信息
    - `nfcInfo`:刷卡相关配置信息
- 返回示例：
```json
// 比如应用平台发送查询 netInfo.ip，返回示例
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "time": 1647580466, 
    "code": "000000",
    "data": {
        "netInfo": {
            "ip": "192.168.32.23 "
        }
    },
    "sign": ""
}
```
- 特殊结果码

| 类型     | code   | 信息             | 说明                             |
| -------- | ------ | ---------------- | -------------------------------- |
| 参数异常 | 200000 | 未找到对应的数据 | 传递的参数可能写错了，注意大小写 |

[回到顶部](#category)

## 1.2 配置修改
- 说明: 
- 流向：平台 -> 设备
- Topic：**`access_device/v1/cmd/{#uuid}/setConfig`**
- 内容：[标准格式](#content)
- 内容里的 data 部分：
    - data 为空或者不传这个部分，这个时候设备不会做任何配置修改
    - data 可以为 json 格式对象，传入一个指定的 key 和 value，就可以修改设备里这个 key 对应的 value。支持最多2级，比如 `key1.key2`, 表示设置 `key1` 对应的数据对象，再在这个对象里找到 `key2`对应的value。详情参考[附件:配置数据详情](#configs)，里面有部分数据不允许修改

- 请求示例
```json
//修改网络相关数据下的 ip 地址
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "time": 1647580466,
    "data": {
        "netInfo": {
            "ip": "192.168.32.23"
        }
    },
    "sign": ""
}
```

- 流向：设备 -> 平台
- 说明: 
- Topic：**` access_device/v1/cmd/setConfig_reply  `**
- 内容：[标准格式](#content)
- data 部分：为空

- 返回示例：
```
//比如应用平台发送修改 netInfo.ip，返回示例
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "time": 1647580466,
    "code": "000000",
    "sign": ""
}
```
- 特殊结果码

| 类型     | code   | 信息                   | 说明                                                         |
| -------- | ------ | ---------------------- | ------------------------------------------------------------ |
| 参数异常 | 200000  | 未找到对应的数据       | 传递的参数可能写错了，注意大小写                             |
| 参数异常 | 200001 | 数据格式未通过校验 | 如要求String类型，但传递了int 类型；只能是0/1二种值，但是传递了2 |                           |
| 其他异常 | 300000 | 这个值不允许修改       | -                                                            |

[回到顶部](#category)

## 1.3 查询权限
- 说明: 
- 流向：平台 -> 设备
- Topic：**`access_device/v1/cmd/{#uuid}/getPermission`**
- 内容：[标准格式](#content)
- 内容里的 data 部分：

| 参数名 | 说明     | 类型   | 必须 | 备注                                |
| :----- | :------- | :----- | ---- | ----------------------------------- |
| size   | 每页数量 | Int    | 是   | 每页数量，最大 200 |
| page   | 页码     | Int    | 是   | 第几页，从1开始                     |
| code   | 凭证号   | String | 否   | 凭证号                              |
| type   | 凭证类型 | Int    | 否   | 参考[附录-设备状态码表](#typeDetails)-type列 |
| id     | 权限id   | String | 否   | -                                   |

- 请求示例
```json
//查询权限
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "page": 1,
        "size": 200
    },
    "time": 1647580466,
    "sign": ""
}
//按code和type查询
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "page": 1,
        "size": 200,
        "code": "2kifk39k40",
        "type": 0
    },
    "time": 1647580466,
    "sign": ""
}
//按id查询，虽然最多只有一条记录，为了统一，size和page也加上
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "page": 1,
        "size": 200,
        "id": "2kifk39k40"
    },
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 
- 流向：设备 -> 平台
- Topic：**` access_device/v1/cmd/getPermission_reply  `**
- 内容：[标准格式](#content)
- data 部分：json 对象格式

| 参数名    | 说明               | 类型   | 必须 | 备注                                                         |
| --------- | ------------------ | ------ | ---- | ------------------------------------------------------------ |
| page      | 当前页             | Int    | 是   | 当前页（1开始）                                              |
| size      | 每页大小           | Int    | 是   | 当前页大小                                                   |
| total     | 总数               | Int    | 是   | 白名单总数                                                   |
| totalPage | 总页数             | Int    | 是   | 总页数                                                       |
| count     | 当前页实际白名单数 | Int    | 是   | 当前页实际白名单数                                           |
| content   | 权限列表           | Array  | 是   | 权限列表  |
| -- id     | 权限Id             | String | 是   | 权限的唯一标识，添加和删除时根据这个标识来判定，建议传32位随机值 |
| -- type   | 权限类型           | Int | 是   | 参考[附录-设备状态码表](#typeDetails)-type列 |
| --code    | 权限值             | String | 是   | 通行权限值   |
| --index    | 门控编号             | String | 否   | 比如设备是一控四，index可能就是1，2，3，4 ,可以为空  |
| --extra   | 额外参数           | Object | 否   | 其他额外属性，比如人员名称等 |
| --time    | 时间区间           | Object | 是   | [查看时间区间](#timeInterval)                                |

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "data": {
        "content": [{
            "id": "20190101120101",
            "type": 101,
          	"index": 1,
            "code": "001002",
            "extra": {
            	"door" : "08"
            },
            "time": {
                "type": 0
            }
        }],
        "page": 1,
        "size": 20,
        "total": 100,
        "totalPage": 5,
        "count": 20
    },
    "time": 1647580466,
    "sign": ""
}

```
- 特殊结果码

| 类型     | code   | 信息                | 说明                             |
| -------- | ------ | ------------------- | -------------------------------- |
| 参数异常 | 200000 | 未找到对应的数据    | 传递的参数可能写错了，注意大小写 |

[回到顶部](#category)

## 1.4 添加权限
- 流向：平台 -> 设备
- 说明: 
- Topic：**`access_device/v1/cmd/{#uuid}/insertPermission`**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json array 数组对象，每个元素的参数如下：

| 参数名 | 必填       | 类型   | 说明 | 备注                                                         |
| :----- | :--------- | :----- | ---- | ------------------------------------------------------------ |
| id     |      是     | String |  权限Id  | 权限的唯一标识，添加和删除时根据这个标识来判定，建议传32位随机值 |
|type   |      是      | Int    | 权限类型   | 参考[附录-设备状态码表](#typeDetails)-type列 |
|code  |      是     | String | 权限值   | 通行权限值   |
|index    |  否        | String |  门控编号  | 比如设备是一控四，index可能就是1，2，3，4 ,可以为空  |
|extra   |      否      | Object | 额外参数   | 其他额外属性，比如人员名称等 |
|time    |     是       | Object | 时间区间   | [查看时间区间](#timeInterval)                                |

- 请求示例
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": [{
            "id": "20190101120101",
            "type": 101,
            "code": "001002",
            "index": 1,
            "extra": {
            	"door": "08"
            },
            "time": {
                "type": 0
            }
        },
        {
            "id": "20190101120102",
            "type": 103,
            "code": "003004",
            "extra": {
            	"door": "08"
            },
            "time": {
                "type": 0
            }
        }
    ],
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 要么都成功，要么全部失败，不会部分成功，如果插入的权限在设备里已经存在（id一样），则会忽略，但是还是返回成功
- 流向：设备 -> 平台
- Topic：**`access_device/v1/cmd/insertPermission_reply`**
- 内容：[标准格式](#content)
- data 部分：json array 数组对象，每个元素都是成功插入的权限id

- 返回示例：
```
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "data": ["20190101120101","20190101120102"],
    "time": 1647580466,
    "sign": ""
}
```
- 特殊结果码

| 类型                  | code   | 信息                   | 说明                   |
| --------------------- | ------ | ---------------------- | ---------------------- |
| 参数异常              | 20000  | 缺少必须要有的参数     | 缺少必须要有的参数     |

[回到顶部](#category)

## 1.5 删除权限
- 说明: 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/cmd/{#uuid}/delPermission  `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json array 数组对象，每个元素都是权限id：

- 请求示例
```json
//删除权限
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": ["20190101120101","20190101120102"],
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 要么都成功，要么全部失败，不会部分成功,如果删除的权限在设备里没有存在，则会忽略，但是还是返回成功
- 流向：设备 -> 平台
- Topic：**` access_device/v1/cmd/delPermission_reply  `**
- 内容：[标准格式](#content)
- data 部分：json array 数组对象，每个元素都是成功删除的权限id

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "data": ["20190101120101","20190101120102"],
    "time": 1647580466,
    "sign": ""
}
```
- 特殊结果码

| 类型     | code  | 信息               | 说明               |
| -------- | ----- | ------------------ | ------------------ |
| 参数异常 | 20000 | 缺少必须要有的参数 | 缺少必须要有的参数 |

[回到顶部](#category)

## 1.6 清空权限
- 说明: 
- 流向：平台 -> 设备
- Topic：**`access_device/v1/cmd/{#uuid}/clearPermission `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：无

- 请求示例
```json
//清空权限
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 不会返回失败
- 流向：设备 -> 平台
- Topic：**` access_device/v1/cmd/clearPermission_reply  `**
- 内容：[标准格式](#content)
- data 部分：无

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "time": 1647580466,
    "sign": ""
}
```

[回到顶部](#category)

## 1.7 查询密钥
- 说明: 
- 流向：平台 -> 设备
- Topic：**`access_device/v1/cmd/{#uuid}/getSecurity`**
- 内容：[标准格式](#content)
- 内容里的 data 部分：

| 参数名 | 说明     | 类型   | 必须 | 备注                                |
| :----- | :------- | :----- | ---- | ----------------------------------- |
| size   | 每页数量 | Int    | 是   | 每页数量，最大 20 |
| page   | 页码     | Int    | 是   | 第几页，从1开始                     |
| key   | 密钥key值   | String | 否   | 凭证号                              |
| type   | 密钥类型 | String    | 否   | RSA之类的 |
| id     | 密钥id   | String | 否   | -                                   |

- 请求示例
```json
//查询所有密钥
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "page": 1,
        "size": 20
    },
    "time": 1647580466,
    "sign": ""
}
//按key和type查询
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "page": 1,
        "size": 20,
        "key": "vguang",
        "type": "RSA"
    },
    "time": 1647580466,
    "sign": ""
}
//按id查询，虽然最多只有一条记录，为了统一，size和page也加上
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "page": 1,
        "size": 20,
        "id": "2kifk39k40"
    },
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 
- 流向：设备 -> 平台
- Topic：**`access_device/v1/cmd/getSecurity_reply `**
- 内容：[标准格式](#content)
- data 部分：json 对象格式

| 参数名    | 说明               | 类型   | 必须 | 备注                                                         |
| --------- | ------------------ | ------ | ---- | ------------------------------------------------------------ |
| page      | 当前页             | Int    | 是   | 当前页（1开始）                                              |
| size      | 每页大小           | Int    | 是   | 当前页大小                                                   |
| total     | 总数               | Int    | 是   | 密钥总数                                                   |
| totalPage | 总页数             | Int    | 是   | 总页数                                                       |
| count     | 当前页实际密钥数 | Int    | 是   | 当前页实际密钥数                                           |
| content   | 密钥列表           | Array  | 是   | 密钥列表  |
| -- id     | 密钥Id             | String | 是   | 密钥的唯一标识|
| -- type   | 密钥类型           | String | 是   | RSA之类的 |
| --key    | 密钥key值            | String | 是   |  -  |
| --value    | 密钥值             | String | 否   | 安全性考虑，密钥值不允许直接查出原始值 |
| --startTime   | 开始时间           | Long | 否   | 时间戳（秒） |
| --endTime    | 过期时间           | Long | 否   |时间戳（秒）|

- 返回示例：
```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "0a1b2c3d",
	"code": "000000",
	"data": {
		"content": [{
			"type": "RSA",
			"id": "213v",
			"key": "vguang",
			"value": "",
			"startTime": 1560303425,
			"endTime": 1683918932
		}],
		"page": 1,
		"size": 20,
		"total": 100,
		"totalPage": 5,
		"count": 20
	},
	"time": 1647580466,
	"sign": ""
}

```
- 特殊结果码

| 类型     | code   | 信息                | 说明                             |
| -------- | ------ | ------------------- | -------------------------------- |
| 参数异常 | 200000 | 未找到对应的数据    | 传递的参数可能写错了，注意大小写 |

[回到顶部](#category)

## 1.8 添加密钥
- 流向：平台 -> 设备
- 说明: 不支持更新密钥，可以删除密钥后再添加来实现更新
- Topic：**`access_device/v1/cmd/{#uuid}/insertSecurity`**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json array 数组对象，每个元素的参数如下：

| 参数名 | 必填       | 类型   | 说明 | 备注                                                         |
| :----- | :--------- | :----- | ---- | ------------------------------------------------------------ |
|id     | 权限Id             | String | 是   | 密钥的唯一标识|
| type   | 密钥类型           | String | 是   | RSA之类的 |
|key    | 密钥key值            | String | 是   |  -  |
| value    | 密钥值             | String | 否   | - |
| startTime   | 开始时间           | Long | 否   | 时间戳（秒） |
| endTime    | 过期时间           | Long | 否   |时间戳（秒）  |

- 请求示例
```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "0a1b2c3d",
	"data": [{
			"type": "RSA",
			"id": "213v",
			"key": "vguang",
			"value": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAIhGA5XLhPR22MRf7ms4R3NeUyV4UvnUiu2YIrxB4RMojK8QY90760Otx6fWZsEi0gY5ysLWPZSZdu92vA4s1BsCAwEAAQ==",
			"startTime": 1560303425,
			"endTime": 1683918932
		},
		{
			"type": "RSA",
			"id": "213t",
			"key": "test",
			"value": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAIhGA5XLhPR22MRf7ms4R3NeUyV4UvnUiu2YIrxB4RMojK8QY90760Otx6fWZsEi0gY5ysLWPZSZdu92vA4s1BsCAwEAAQ==",
			"startTime": 1560303425,
			"endTime": 1683918932
		}
	],
	"time": 1647580466,
	"sign": ""
}
```

- 说明: 要么都成功，要么全部失败，不会部分成功,如果插入的密钥在设备里已经存在（id一样），则会忽略，但是还是返回成功
- 流向：设备 -> 平台
- Topic：**`access_device/v1/cmd/insertSecurity_reply`**
- 内容：[标准格式](#content)
- data 部分：json array 数组对象，每个元素都是成功插入的密钥id

- 返回示例：
``` json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "data": ["213v","213t"],
    "time": 1647580466,
    "sign": ""
}
```
- 特殊结果码

| 类型                  | code   | 信息                   | 说明                   |
| --------------------- | ------ | ---------------------- | ---------------------- |
| 参数异常              | 20000  | 缺少必须要有的参数     | 缺少必须要有的参数     |

[回到顶部](#category)

## 1.9 删除密钥
- 说明: 
- 流向：平台 -> 设备
- Topic：**`access_device/v1/cmd/{#uuid}/delSecurity`**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json array 数组对象，每个元素都是权限id：

- 请求示例
```json
//删除权限
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": ["213v","213t"],
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 要么都成功，要么全部失败，不会部分成功,如果删除的权限在设备里没有存在，则会忽略，但是还是返回成功
- 流向：设备 -> 平台
- Topic：**`access_device/v1/cmd/delSecurity_reply`**
- 内容：[标准格式](#content)
- data 部分：json array 数组对象，每个元素都是成功删除的权限id

- 返回示例：
```json
{,
    "uuid": "0a1b2c3d",
    "code": "000000",
    "data": ["213v","213t"],
    "time": 1647580466,
    "sign": ""
}
```
- 特殊结果码

| 类型     | code  | 信息               | 说明               |
| -------- | ----- | ------------------ | ------------------ |
| 参数异常 | 20000 | 缺少必须要有的参数 | 缺少必须要有的参数 |

[回到顶部](#category)

## 1.10 清空密钥
- 说明: 
- 流向：平台 -> 设备
- Topic：**`access_device/v1/cmd/{#uuid}/clearSecurity`**
- 内容：[标准格式](#content)
- 内容里的 data 部分：无

- 请求示例
```json
//清空权限
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 不会返回失败
- 流向：设备 -> 平台
- Topic：**`access_device/v1/cmd/clearSecurity_reply`**
- 内容：[标准格式](#content)
- data 部分：无

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "time": 1647580466,
    "sign": ""
}
```

[回到顶部](#category)

## 1.11 远程控制
- 说明: 
- 流向：平台 -> 设备
- Topic：**`access_device/v1/cmd/{#uuid}/control`**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json object 对象，参数如下：

| 参数名 | 说明 | 类型 | 必须 | 备注 |
| :------ | :--- | :--- | ---- | ------------------------------------------------------- |
| command | 命令 | Int | 是 | 0：重启 1：远程开门 4：设备重置 5:设备提示（UI/语音）|

当`command=1`or`command=5`时 `extra`字段必填 json 支持字段如下表
| 参数名 | 说 明 | 类 型 | 必 须 | 备 注 |
| :----------: | :-----------: | :------: | :----: | :---------------------------|
| msg | 提示信息 | String | 否 | 当设备支持UI时将弹窗显示此信息 |
| index | 提示信息 | obj | 否 |门号 （目前只针对超体健身房）|
| msgTimeout | 提示时间 | Int | 否 | 单位:`ms`，当设备支持UI时，UI显示`msg`的时间 此项不存在默认显示时间:`1500ms` |
| wavFileName | 音频文件名 | String | 否 | 此项不存在播放默认语音 此项存在则播放对应名称的语音 如`"wavFileName":"9"`则播放`9.wav` 注：若此项存在需关闭网络传输行为中的`播报语音` |
- 请求示例
```json
//远程重启
{
 "serialNo": "6w8keif5g6",
 "uuid": "0a1b2c3d",
 "data": {
 "command": 0,
 "extra": {},
 "time": 1647580466,
 "sign": ""
 }
}
//远程开门
{
 "serialNo": "6w8keif5g6",
 "uuid": "0a1b2c3d",
 "data": {
 	"command": 1,
 	"extra":{ "index": 1 }
 },
 "time": 1647580466,
 "sign": ""
}
//UI 提示："请通行"两秒后关闭，并且播放语音文件：9.wav
{
 "serialNo": "6w8keif5g6",
 "uuid": "0a1b2c3d",
 "data": {
 	"command": 5,
 	"extra":{
 		"msg":"请通行",
 "msgTimeout":2000,
 "wavFileName":"9"
 }
 },
 "time": 1647580466,
 "sign": ""
}
```

- 说明: 
- 流向：设备 -> 平台
- Topic：**`access_device/v1/cmd/control_reply`**
- 内容：[标准格式](#content)
- data 部分：无

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "time": 1647580466,
    "sign": ""
}
```
- 特殊结果码

| 类型     | code   | 信息                | 说明               |
| -------- | ------ | ------------------- | ------------------ |
| 参数异常 | 200000 | 缺少必须要有的参数  | 缺少必须要有的参数 |
| 参数异常 | 200001 | 不支持的 command 值 | command 值错误     |

[回到顶部](#category)

## 1.12升级固件
- 说明: 设备收到升级固件后，先下载固件文件，下载成功后返回结果给应用平台，然后重启
- 流向：平台 -> 设备
- Topic：**`access_device/v1/cmd/{#uuid}/upgradeFirmware`**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json object 对象，参数如下：

| 参数名 | 说明                     | 类型   | 必须 | 备注                                                         |
| :----- | :----------------------- | :----- | ---- | ------------------------------------------------------------ |
| type   | 升级包类型               | Int    | 是   | type值强校验  0：本机升级                                    |
| url    | 升级包下载地址，http地址 | String | 是   | 调用接口时访问该url，对应的文件目录结构是/app/code/开头 |
| md5    | 升级包MD5值              | String | 是   | 升级包进行MD5验证                                            |

>i **信息提示**
>
> 升级文件中的字体文件名跟背景图片名必须固定
>字体文件名：PangMenZhengDaoBiaoTiTi-1.ttf，完整路径（/app/code/resource/font/PangMenZhengDaoBiaoTiTi-1.ttf）
>背景图片名：水平方向：background.png；垂直方向：background_90.png，完整路径（/app/code/resource/image/background.png）

- 请求示例
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "type": 0,
        "url": "http://host/aio.tar.xz",
        "md5": "521c2bdc835d4f13b5f9d6db164f0881"
    },
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 这里只是下载升级包成功或失败，通常下载升级包后会重启，重启后才能知道是否升级真正成功
- 流向：设备 -> 平台
- Topic：**`access_device/v1/cmd/upgradeFirmware_reply`**
- 内容：[标准格式](#content)
- data 部分：无

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "time": 1647580466,
    "sign": ""
}
```
- 特殊结果码

| 类型     | code   | 信息                              | 说明                       |
| -------- | ------ | --------------------------------- | -------------------------- |
| 参数异常 | 200000 | 缺少必须要有的参数                | 缺少必须要有的参数         |
| 参数异常 | 200001 | 对应的固件下载地址下载不了        | 网络异常或md5校验失败 |

[回到顶部](#category)

## 1.13 连接上报

- 说明: 只上报一次
- 流向：设备 -> 平台
- Topic：**` access_device/v1/event/connect`**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json object 对象，参数如下：

| 参数名     | 说明               | 类型   | 必须 | 备注              |
| :--------- | :----------------- | :----- | ---- | ----------------- |
| sysVersion | 系统版本号         | String | 否   | 系统版本号        |
| appVersion | 应用版本号         | String | 否   | 应用版本号        |
| createTime | 应用发布日期       | Long   | 否   | 应用发布日期      |
| btMac       | 蓝牙MAC地址     | String | 是   | 蓝牙MAC地址   |
| mac       | 设备硬件唯一标识    | String | 否   | 设备硬件唯一标识   |
| clientId     | 客户端id，与设备地址一致 | String | 是     | 客户端id |
| name       | 设备名称          | String | 是   | 设备名称          |
| type        | 网络类型         | Int    | 是     | 网络类型(1:以太网 2:wifi) |
| ssid        | wifi名           | String | 是     | wifi名                    |
| psk         | wifi密码         | String | 是     | wifi密码                  |
| dhcp        | 是否为DHCP模式   | Int    | 是     | 是否为DHCP(1:动态,0:静态) |
| ip          | ip地址           | String | 是     | ip地址                    |
| gateway     | 网关             | String | 是     | 网关                      |
| dns         | DNS服务器        | String | 是     | DNS服务器                 |
| subnetMask  | 子网掩码         | String | 是     | 子网掩码                  |
| netMac  		| 网卡mac         | String | 是     | 网卡mac                  |

- 请求示例
```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "0a1b2c3d",
	"data": {
		"sysVersion": "v1.0.3.4050",
		"appVersion": "v3.204.234.5",
		"createTime": 1647550466,
		"uuid": "0a1b2c3d",
		"name": "#12-B01",
		"model":"dx_cc101"
	},
	"time": 1647580466,
	"sign": ""
}
```

- 说明: 
- 流向：平台 -> 设备
- Topic：**`access_device/v1/event/{#uuid}/connect_reply`**
- 内容：[标准格式](#content)
- data 部分：无

- 返回示例：
```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "0a1b2c3d",
	"code": "000000",
	"time": 1647580466,
	"sign": ""
}
```

[回到顶部](#category)

## 1.14 告警上报

- 说明: 告警有很多类型，并不是所有设备都支持所有类型
- 流向：设备 -> 平台
- Topic：**`access_device/v1/event/alarm`**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json object 对象，参数如下：

| 参数名 | 说明     | 类型   | 必须 | 备注                                                         |
| :----- | :------- | :----- | ---- | ------------------------------------------------------------ |
| type   | 状态类型 | Int    | 是   | 参考[附录-设备状态码表](#alarmDetails)-type列                |
| value  | 状态值   | String | 否   | 参考[附录-设备状态码表](#alarmDetails)，如果是"无"，就不需要传值 |

- 请求示例
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "type": 1,
        "value": "1"
    },
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 
- 流向：平台 -> 设备
- Topic：**`access_device/v1/event/{#uuid}/alarm_reply`**
- 内容：[标准格式](#content)
- data 部分：无

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "time": 1647580466,
    "sign": ""
}
```

[回到顶部](#category)

## 1.15 通行上报

- 说明: 
- 流向：设备 -> 平台
- Topic：**` access_device/v1/event/access`**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json array 数组对象，参数如下：

| 参数名 | 说明     | 类型   | 必须 | 备注                                                         |
| :----- | :------- | :----- | ---- | ------------------------------------------------------------ |
| id     | 权限id   | String | 是   | 如果权限存在设备的白名单就返回对应的权限id，不存在就返回"-1" |
| code   | 权限凭证 | String | 是   | 如果是人脸则为人脸唯一id|
| type   | 权限类型           | Int | 是   | 参考[附录-设备状态码表](#typeDetails)-type列 |
| time   | 通行时间 | Long   | 是   | 时间戳单位秒   |
| result | 通行结果 | Int    | 是   | 1表示通过 0表示未通过  |
| error | 失败原因 | String    | 否   | 失败原因码或具体原因  |
| extra  | 额外参数 | Object | 否   | 其他额外属性，比如人员名称等，如果通行失败，记录原始数据，比如二维码的原始值:```{"srcData":"1234567890"}```  |
| index    | 门控编号             | obj | 否   | 比如设备是一控四，index可能就是1，2，3，4 ,可以为空  |

- 请求示例
```json
{
    "serialNo": "serialNo7",
    "uuid": "0a1b2c3d",
    "sign": "",
    "code": "000000",
    "data": [
        {
            "id": "-1",
            "type": 400,
            "code": "55",
            "time": 1757916831,
            "result": 0,
            "extra": {
                "srcData": "55"
            },
            "error": "无权限"
        }
    ],
    "time": 1757916831
}
```

- 说明: 
- 流向：平台 -> 设备
- Topic：**`access_device/v1/event/{#uuid}/access_reply`**
- 内容：[标准格式](#content)
- data 部分：无

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "time": 1647580466,
    "sign": ""
}
```

[回到顶部](#category)

## 1.16 在线验证

- 说明: 
- 流向：设备 -> 平台
- Topic：**`access_device/v1/event/access_online`**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json 对象，参数如下：

| 参数名 | 说明     | 类型   | 必须 | 备注                                   |
| :----- | :------- | :----- | ---- | -------------------------------------- |
| code   | 权限凭证 | String | 是   | 如果是人脸则为空                       |
| type   | 权限类型           | Int | 是   | 参考[附录-设备状态码表](#typeDetails)-type列 |
| index    | 门控编号             | String | 否   | 比如设备是一控四，index可能就是1，2，3，4 ,可以为空  |
| time   | 通行时间 | Long   | 是   | 时间戳单位秒                           |
| extra  | 额外参数 | Object | 否   | 可扩展，通常是记录原始数据，比如扫二维码的原文|
| srcData  | 数据原文 | String | 否   | 原始数据|
- 请求示例
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "code":"s345463434gg",
        "type": 103,
        "time": 1640917147,
      	"extra":{
          "srcData" : "vg://v103AQAGAHZndWFuZwIAQAAlcOsQMXN9TJGCK5Afs14p4orxE+QnmI4gb2F85pvrvbQW1/+CyPEE1Bi3X4T3SYFZRoheykjICfdwWU+kw/Vf2965"
        }	
    },
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/event/{#uuid}/access_online_reply  `**
- 内容：[标准格式](#content)
- data 部分：无

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",//验证通过返回成功，否则返回300000
    "time": 1647580466,
    "sign": ""
}
```

[回到顶部](#category)

## 1.17 遗嘱上报

- 说明: 
- 流向：设备 -> 平台
- Topic：**`access_device/v1/event/offline`**
- 内容：[标准格式](#content)

- 请求示例
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "sign": ""
}
```

- 说明: 遗嘱无需返回

[回到顶部](#category)

## 1.18 心跳上报（默认关闭）

- 说明: 
- 流向：设备 -> 平台
- Topic：**`access_device/v1/event/heartbeat`**
- 内容：[标准格式](#content)

- 请求示例
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 心跳无需返回

[回到顶部](#category)

# V2 协议

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

####  2.1 配置查询

- 后台或应用到设备

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

发送data消息参数说明

| 参数名 | 类型  | 必传 | 附加说明                                                |
| :----- | ----- | ---- | ------------------------------------------------------- |
| data   | string | Y    |  |

消息发送示例：

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

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

- 设备回馈到后台或应用

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

data消息参数

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

返回示例：

```json
//比如应用平台发送查询 netInfo.ip,返回示例
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "time": 1647580466, 
    "code": "000000",
    "data": {
        "netInfo": {
            "ip": "192.168 .32 .23 "
        }
    },
    "sign": ""
}
```

#### 2.2 配置修改

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

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

data消息参数说明

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

data 部分：json 格式，key/value 对应很多属性。详情参考[DW200 门禁系统配置项文档](http://wiki.koodle.cn:10086/doc/631/)

消息发送示例：

```json
//修改网络相关数据下的 ip 地址
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "time": 1647580466,
    "data": {
        "netInfo": {
            "ip": "192.168 .32 .23"
        }
    },
    "sign": ""
}
```

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

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

消息参数说明

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

返回示例

```json
//比如应用平台发送查询 netInfo.ip,返回示例
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "time": 1647580466,
    "code": "000000",
    "sign": ""
}
```

#### 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 |  否   | 文件名称 |

发送示例：

```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
    "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 |
| --------- | ------------------------------------------------- |

返回示例

```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

#### 2.4 远程控制

- 后台或应用到设备

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

网络配置data参数

| 参数名 | 描述 | 类型 | 必传 | 附加说明 |
| ------- | -------- | ------ | ---- | ------------------------------------------------------------ |
| command | 命令 | Int | Y | 0：重启 1：远程开门 2：设备启用 3：设备禁用 4：设备重置 5:播放语音 6：屏幕展示图片 7：屏幕展示文字 8：远程抓拍人脸 9：日志 10：下发小程序码 11：企微（仅内部企微接口可用） 12：指纹采集 13：屏保壁纸 (目前只支持 0 1 4 5 10 11 12 13) |
| 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` |
| log             | 日志命令         | Int    | 否    | command=9时传入，0：获取设备端日志（最大10K明文？） 1：清空日志 |
| qrCodeBase64    | 下发小程序码     | String | 否    | command=10时传入                                             |
| keyId           | 远程抓拍时凭证id | String | 否    | command=8时传入                                              |
| weComStatus     | 企微状态         | Int    | 否    | command=11时传入,0：未绑定 1：已绑定（仅内部企微接口可用）   |
| WeComBindQr     | 企微绑定码       | Int    | 否    | command=11且weComStatus=0时传入，供企微绑定界面使用（仅内部企微接口可用） |
| name            | 姓名             | String | 否    | command=12时传入，用于展示采集指纹的人员名称                 |
| wallpaperBase64 | 屏保壁纸         | String | 否    | command=13时传入，用于替换屏保壁纸，壁纸分辨率需要等于设备分辨率，建议使用PNG格式 |

发送示例：

```json
{
    
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
    "time": 0,
    "sign": "",
	"data": {
		"command": 1
	}
}

//人脸抓拍
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "time": 0,
    "sign": "",
    "data": {
        "command": 8,
        "extra": {
            "keyId": "12345678"
        }
    }
}

//企微
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "time": 0,
    "sign": "",
    "data": {
        "command": 11,
        "extra": {
            "weComStatus": 0,
            "WeComBindQr": "https://open.work.weixin.qq.com/connect/hardware?hw_code=ZxjdiTaAJ6tX702PJg1z1e_iAdM_WH7r-qYUWMBIJJY"
        }
    }
}
```

- 设备回馈到后台或应用

| 消息topic | topic: access_device/v2/cmd/control_reply |
| --------- | ----------------------------------------- |
| data参数  |                                           |

| 参数名        | 描述                          | 类型   | 必传 | 附加说明                             |
| ------------- | ----------------------------- | ------ | ---- | ------------------------------------ |
| faceBase64    | 远程抓拍时人脸jpg照片的base64 | String | 否   | command=8时返回                      |
| keyId         | 远程抓拍时凭证id              | String | 否   | command=8时返回,和传入值保持一致     |
| fingerFeature | 指纹特征值                    | String | 否   | command=12时返回，采集到的指纹特征值 |

返回示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}

//人脸抓拍
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "time": 0,
    "sign": "",
    "code": "000000",
    "data": {
        "faceBase64": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQEBA/......2Q==",
        "keyId": "12345678"
    },
    "message": "success"
}
```

#### 2.5 报警

- 设备到后台或应用

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

data参数

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

发送示例：

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

- 后台或应用回馈到设备

| 消息topic | topic: access_device/v2/event/{#uuid}/alarm_reply |
| --------- | ------------------------------------------------- |

返回示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

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

- 设备到后台或应用

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

发送示例：

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
    "time": 0,
    "sign": ""
}
```

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

| 消息topic | topic: access_device/v2/event/{#uuid}/heartbeat_reply |
| --------- | ----------------------------------------------------- |

#### 2.7 遗嘱

- 设备到后台或应用

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

发送示例：

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
    "time": 0,
    "sign": ""
}
```

#### 2.8 连接上报

- 设备到后台或应用

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

网络配置data参数

| 参数名     | 描述                         | 类型   | 必传 | 附加说明                        |
| ---------- | ---------------------------- | ------ | ---- | ------------------------------- |
| appVersion | 应用版本号                   | String | Y    | 应用版本号                      |
| btMac      | 蓝牙MAC地址                  | String | Y    | 蓝牙MAC地址                     |
| mac        | 设备硬件唯一标识             | String | N    | 设备硬件唯一标识                |
| clientId   | 客户端id，默认与设备地址一致 | String | Y    | 客户端id                        |
| name       | 设备名称                     | String | Y    | 设备名称                        |
| type       | 网络类型                     | Int    | Y    | 网络类型（0:以太网 1:WIFI 2:4G) |
| ssid       | Wifi名                       | String | Y    | wifi名                          |
| pwd        | Wifi密码                     | String | Y    | wifi密码                        |
| dhcp       | 是否为DHCP模式               | Int    | Y    | 是否为DHCP(1:动态,0:静态)       |
| ip         | ip地址                       | String | Y    | ip地址                          |
| gateway    | 网关                         | String | Y    | 网关                            |
| dns        | DNS服务器                    | String | Y    | DNS服务器                       |
| subnetMask | 子网掩码                     | String | Y    | 子网掩码                        |
| netMac     | 网卡mac                      | String | Y    | 网卡mac                         |

发送示例：

```json
{
  "serialNo": "0000000001",
  "uuid": "e4720000964b5c00",
  "time": 1737364204,
  "data": {
    "appVersion": "vf203_v11_reader_1.0.0",
    "btMac": "000000000000",
    "mac": "e4ff00009df1d100",
    "clientId": "e4720000964b5c00",
    "name": "TODO",
    "type": 1,
    "ssid": "",
    "pwd": "",
    "dhcp": 1,
    "ip": "10.102.106.24",
    "gateway": "10.102.106.124",
    "dns": "10.102.106.124",
    "netMac": "ee:28:00:00:9d:f1"
  }
}
```

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

| 消息topic | topic:face_device/v2/event/connect_reply |
| --------- | ---------------------------------------- |

#### 2.9 在线验证

- 设备到后台或应用

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

data参数

| 参数名  | 说明     | 类型   | 必须 | 备注                                                |
| :------ | :------- | :----- | ---- | --------------------------------------------------- |
| code    | 权限凭证 | String | 是   | 如果是人脸则为空                                    |
| type    | 权限类型 | Int    | 是   | 参考附表 3 权限类型说明-num列                       |
| index   | 门控编号 | String | 否   | 比如设备是一控四，index可能就是1，2，3，4 ,可以为空 |
| time    | 通行时间 | Long   | 是   | 时间戳单位秒                                        |
| extra   | 额外参数 | Object | 否   | 可扩展，通常是记录原始数据，比如扫二维码的原文      |
| srcData | 数据原文 | String | 否   | 原始数据                                            |

发送示例：

```json
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "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 |
| --------- | --------------------------------------------------------- |

返回示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 1640917147,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

## 三. 下发可通行人员流程

#### 3.1 流程示例

```mermaid
flowchart TD
 A([开始])
 B[准备人员数据]
 C[下发人员 insertUser]
 D{等待回复 insertUser_reply}
 E[人员已入库]
 F[记录失败批次]
 G[准备人脸凭证]
 H[下发人脸凭证 insertKey]
 I{等待回复 insertKey_reply}
 J[人脸已入库]
 K[记录失败批次]
 L[准备权限数据]
 M[下发权限 insertPermission]
 N{等待回复 insertPermission_reply}
 O[权限已下发]
 P[记录失败批次]
 Q([完成])

A --> B --> C --> D
    D -->|成功| E
    D -->|失败| F
    E --> G
    F --> G
    G --> H --> I
    I -->|成功| J
    I -->|失败| K
    J --> L
    K --> L
    L --> M --> N
    N -->|成功| O
    N -->|失败| P
    O --> Q
    P --> Q
```

#### 3.2 流程说明

* 添加人员 添加凭证两个接口通过userId字段关联 ，添加人员 添加权限通过permissionIds字段关联
* 注册一个人脸|二维码|刷卡、需要调用添加人员 添加凭证时userId字段传相同的值，添加权限时permissionIds字段和添加人员时传相同的值，且三个接口的调用缺一不可，
* 添加人员 添加凭证 添加权限三个接口调用顺序没有限制，设备也不会检查userId和permissionIds是否有问题，是否关联等情况，建议顺序还是添加人员->凭证->权限
* 添加人员中userId为主键，批量下发时要确保不重复，否则会将userId相同的人员数据更新，且下发中permissionIds要和添加权限中的permissionId一一对应
* 添加凭证中keyId为主键，批量下发时要确保不重复，否则会将keyId相同的人员数据更新，且下发中userId要和之前添加人员中的userId一一对应
* 添加权限中的permissionId为主键，批量下发时要确保不重复，否则会将permissionId相同的数据更新
* 不建议同一人下发时，userId、keyId、permissionId为同一值，这种情况下一个人存在多个二维码、卡号或多个权限时还需要对Id先做特殊处理，还是建议三个Id为不同值，然后各自映射关联

## 四. 人员管理类接口

#### 4.1 添加人员

- 后台或应用到设备

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

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

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

- 当向设备下发已存在 userId 的人员时，设备将按 userId 自动更新该人员的全部信息。

发送示例：

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"data": [{
			"userId": "20190101120101",
        	"permissionIds":["6584132"],
			"name": "张三",
			"extra": {
				"xxxx": xxxx
			}
		},
		{
			"userId": "20190101120102",
			"name": "李四",
            "permissionIds":["6584132"],
			"extra": {
				"xxxx": "xxxx"
			}
		}
	],
	"time": 1647580466,
	"sign": ""
}
```

- 设备回馈到后台或应用

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

- 通用 data 字段说明（仅失败时存在）：

| 参数名 | 描述     | 类型   | 附加说明                         |
| ------ | -------- | ------ | -------------------------------- |
| userId | 人员 Id  | String | 失败的人员 Id                    |
| errmsg | 错误描述 | String | 具体的错误原因描述，如解析失败等 |

返回成功示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

返回失败示例

```json
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "code": "C00001",
    "time": 1761275206,
    "sign": "",
    "message": "insertUser: Failed to insert user",
    "data": [
        {
            "userId": "20190101120101",
            "errmsg": "user array parse (0) failed"
        },
        {
            "userId": "20190101120102",
            "errmsg": "user array parse (1) failed"
        }
    ]
}
```

#### 4.2 删除人员

- 后台或应用到设备

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

data参数

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

发送示例：

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

- 设备回馈到后台或应用

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

- 通用 data 字段说明（仅失败时存在）：

| 参数名 | 描述     | 类型   | 附加说明                         |
| ------ | -------- | ------ | -------------------------------- |
| userId | 人员 Id  | String | 失败的人员 Id                    |
| errmsg | 错误描述 | String | 具体的错误原因描述，如解析失败等 |

返回成功示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

返回失败示例

```json
{
    "serialNo": "0000000001",
    "uuid": "f47b00008ee62a00",
    "code": "C00001",
    "time": 1761275616,
    "sign": "",
    "message": "delUser: Failed to delete user",
    "data": [
        {
            "userId": "001",
            "errmsg": "delete userId:001 failure"
        },
        {
            "userId": "002",
            "errmsg": "delete userId:002 failure"
        }
    ]
}
```

#### 4.3 清空人员

- 后台或应用到设备

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

发送示例：

```json
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "time": 1754032384,
    "sign": ""
}
```

- 设备回馈到后台或应用

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

返回示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"code": "000000",
	"time": 1754032640,
	"sign": "",
	"message": "success"
}
```

#### 4.4 查询人员

- 后台或应用到设备

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

data参数

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

发送示例：

```json
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "time": 1751538000,
    "sign": "",
    "data": {
        "userId": "",
        "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 | 查询结果数组长度，小于等于size，例如最后一页 |
| content | 权限数组 | Array | Y | 详见\< content数据\>表 |

content数据

| 参数名        | 描述     | 类型   | 必传 | 附加说明 |
| ------------- | -------- | ------ | ---- | -------- |
| userId        | 人员ID   | String | Y    |          |
| name          | 人员姓名 | String | Y    |          |
| permissionIds | 权限Id   | Array  | Y    |          |
| extra         | 扩展字段 | Object | Y    | extra表  |

extra表

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

返回示例

```json
人员查询成功时:
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"code": "000000",
	"time": 1754032390,
	"sign": "",
	"message": "Success",
	"data": {
		"page": 0,
		"size": 10,
		"total": 5,
		"totalPage": 0,
		"count": 5,
		"content": [{
			"userId": "1",
			"name": "James",
            "permissionIds":["6584132"],
			"extra": {
				"userType": 1,
				"addSrc": 0,
				"addTime": 1754027509921
			}
		}, {
			"userId": "2",
			"name": "Lily",
			"permissionIds":["6584132"],
			"extra": {
				"userType": 1,
				"addSrc": 1,
				"addTime": 1754027489423
			}
		}, {
			"userId": "3",
			"name": "Grace",
			"permissionIds":["6584132"],
			"extra": {
				"userType": 0,
				"addSrc": 1,
				"addTime": 1754027489433
			}
		}, {
			"userId": "4",
			"name": "Wendy",
            "permissionIds":["6584132"],
			"extra": {
				"userType": 0,
				"addSrc": 1,
				"addTime": 1754027489443
			}
		}, {
			"userId": "5",
			"name": "Emma",
            "permissionIds":["6584132"],
			"extra": {
				"userType": 0,
				"addSrc": 1,
				"addTime": 1754027489458
			}
		}]
	}
}
无注册人员时:
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"code": "C00001",
	"time": 1754032816,
	"sign": "",
	"message": "selectUser: no data as this select condition"
}
```

#### 4.5 修改人员

- 后台或应用到设备

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

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

| 参数名        | 描述     | 类型   | 必传 | 附加说明                                               |
| ------------- | -------- | ------ | ---- | ------------------------------------------------------ |
| userId        | 人员 Id  | String | Y    | 唯一不可重复，只可输入字母数字，长度128字节，E.g SW200 |
| name          | 人员名称 | String | N    | name 参数必传且内容不可为空。长度128字节。             |
| permissionIds | 权限Id   | Array  | N    | 人员和权限映射，对应下发权限时permissionId             |
| extra         | 额外参数 | Object | N    | 其他额外人员属性                                       |

- 只能对已下发 userId 的人员，修改其相应的信息。

发送示例：

```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
	"data": [{
			"userId": "20190101120101",
            "name":"李四"
        	"permissionIds":["6584133"],
		},
		{
			"userId": "20190101120102",
			"name": "王二麻",
			"extra": {
				"xxxx": "xxxx"
			}
		}
	],
	"time": 1647580466,
	"sign": ""
}
```

- 设备回馈到后台或应用

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

- 通用 data 字段说明（仅失败时存在）：

| 参数名 | 描述     | 类型   | 附加说明                         |
| ------ | -------- | ------ | -------------------------------- |
| userId | 人员 Id  | String | 失败的人员 Id                    |
| errmsg | 错误描述 | String | 具体的错误原因描述，如解析失败等 |

返回成功示例

```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

返回失败示例

```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "e4720000964b5c00",
    "code": "C00001",
    "time": 1761275206,
    "sign": "",
    "message": "modifyUser: Failed to modifyUser",
    "data": [
        {
            "userId": "20190101120101",
            "errmsg": "user array parse (0) failed"
        },
        {
            "userId": "20190101120102",
            "errmsg": "user array parse (1) failed"
        }
    ]
}
```

## 五. 凭证管理接口

#### 5.1 添加凭证

- 后台或应用到设备

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

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

| 参数名 | 必填     | 类型   | 说明 | 备注                             |
| ------ | -------- | ------ | ---- | -------------------------------- |
| keyId  | 凭证id   | String | 是   | 凭证唯一id标识                   |
| userId | 人员id   | String | 是   | 人员的唯一id标识                 |
| type   | 凭证类型 | int    | 是   | 参考 [附表 4 权限类型说明]-num列 |
| code   | 凭证数据 | String | 是   | 人脸类型传人脸JPG图片的base64    |
| extra  | 额外参数 | Object | 否   | 其他额外凭证属性                 |

extra表

| 参数名   | 描述         | 类型   | 必传 | 附加说明                                                     |
| -------- | ------------ | ------ | ---- | ------------------------------------------------------------ |
| faceType | 注册人脸类型 | String | Y    | 0：base64，1：特征值，2：Url下载，3：zip包（人脸类型仅支持同一类型下发，并且不能和其他类型凭证同一个包下发） |

- userId要和添加人员中的userId保持一致
- 当向设备下发已存在 keyId 的凭证时，设备将按 keyId 自动更新凭证信息
- 设备会逐个注册批量下发的凭证；若其中任一凭证失败，即实时记录失败信息，待全部凭证处理完毕后，一次性汇总并返回完整的失败记录

发送示例：

```json
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "data": [{
            "keyId": "20190101120101",
            "userId": "20190101120101",
            "type": "300",
            "code": "ZnNmZHNmYXNkZmFzZGY=........",
        	"extra":{
                "faceType":"0"
            }
        },
        {
            "keyId": "20190101120101",
            "userId": "20190101120102",
            "type": "103",
            "code": "1233456"
        }
    ],
    "time": 1647580466,
    "sign": ""
}
```

- 设备回馈到后台或应用

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

- 通用 data 字段说明（仅失败时存在）：

| 参数名 | 描述     | 类型   | 附加说明                         |
| ------ | -------- | ------ | -------------------------------- |
| keyId  | 凭证 Id  | String | 失败的凭证 Id                    |
| errmsg | 错误描述 | String | 具体的错误原因描述，如解析失败等 |

返回成功示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

返回失败示例

```json
{
    "serialNo": "0000000001",
    "uuid": "f47b00008ee62a00",
    "code": "C00001",
    "time": 1761275488,
    "sign": "",
    "message": "insertKey: Failed to insert credential",
    "data": [
        {
            "keyId": "20190101120101",
            "errmsg": "key array parse (0) failed"
        },
        {
            "keyId": "20190101120102",
            "errmsg": "key array parse (1) failed"
        }
    ]
}
```

#### 5.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 |

发送示例：

```json
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "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 | 查询结果数组长度，小于等于size，例如最后一页 |
| content | 凭证数组 | Array | Y | 详见\< content数据\>表 |

content数据

| 参数名 | 必填     | 类型   | 说明 | 备注                            |
| :----- | :------- | :----- | ---- | ------------------------------- |
| keyId  | 凭证id   | String | Y    | 凭证唯一id标识                  |
| userId | 人员id   | String | Y    | 人员的唯一id标识                |
| type   | 凭证类型 | int    | Y    | 参考[附表 4 权限类型说明]-num列 |
| code   | 凭证数据 | String | Y    | 人脸类型传base64                |
| extra  | 额外参数 | Object | N    | 其他额外凭证属性                |

返回示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"result": 0,
	"code": "000000",
	"message": "success",
	"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": "码凭证值"
			}
		]
	}
}
```

#### 5.3 删除凭证

- 后台或应用到设备

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

data参数

| 参数名  | 必填   | 类型  | 必须 | 备注             |
| :------ | :----- | :---- | ---- | ---------------- |
| keyIds  | 凭证id | array | 否   | 凭证唯一id标识   |
| userIds | 人员id | array | 否   | 人员的唯一id标识 |

- 允许同时传递 `keyIds` 和 `userIds`，如果重复删除，或者期望删除凭证不存在，不会报错

发送示例：

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

- 设备回馈到后台或应用

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

- 通用 data 字段说明（仅失败时存在）：

| 参数名 | 描述     | 类型   | 附加说明                         |
| ------ | -------- | ------ | -------------------------------- |
| keyId  | 凭证 Id  | String | 失败的凭证 Id                    |
| errmsg | 错误描述 | String | 具体的错误原因描述，如解析失败等 |

返回示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

返回失败示例

```json
{
    "serialNo": "0000000001",
    "uuid": "f47b00008ee62a00",
    "code": "C00001",
    "time": 1761275488,
    "sign": "",
    "message": "delKey: Failed to delete credential",
    "data": [
        {
            "keyId": "20190101120101",
            "errmsg": "delKey by userId: 20190101120101 error"
        },
        {
            "keyId": "invalid",
            "errmsg": "array item:1's userId is invalid"
        }
    ]
}
```

#### 5.4 清空凭证

- 后台或应用到设备

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

发送示例：

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": ""
}
```

- 设备回馈到后台或应用

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

返回示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

#### 5.5 修改凭证

- 后台或应用到设备

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

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

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

extra表

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

- 修改userId时，需要确保该userId最终在人员中一定存在，否则无法正常通行
- 只能对已下发 keyId  的凭证，修改其相应的信息

发送示例：

```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "e4720000964b5c00",
    "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/modifyKey_reply |
| --------- | ------------------------------------------- |

- 通用 data 字段说明（仅失败时存在）：

| 参数名 | 描述     | 类型   | 附加说明                         |
| ------ | -------- | ------ | -------------------------------- |
| keyId  | 凭证 Id  | String | 失败的凭证 Id                    |
| errmsg | 错误描述 | String | 具体的错误原因描述，如解析失败等 |

返回成功示例

```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

返回失败示例

```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "f47b00008ee62a00",
    "code": "C00001",
    "time": 1761275488,
    "sign": "",
    "message": "modifyKey: Failed to modifyKey",
    "data": [
        {
            "keyId": "20190101120101",
            "errmsg": "key array parse (0) failed"
        },
        {
            "keyId": "20190101120102",
            "errmsg": "key array parse (1) failed"
        }
    ]
}
```

## 六. 权限管理接口

#### 6.1 添加权限

- 后台或应用到设备

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

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

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

发送示例：

```json
{
	"scerialNo": "0000000001",
	"sign": "",
	"time": 1704866881,
	"uuid": "e4720000964b5c00",
	"data": [{
		"permissionId": "6584132",
		"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 |
| --------- | -------------------------------------------------- |

- 通用 data 字段说明（仅失败时存在）：

| 参数名       | 描述     | 类型   | 附加说明                         |
| ------------ | -------- | ------ | -------------------------------- |
| permissionId | 权限 Id  | String | 失败的权限 Id                    |
| errmsg       | 错误描述 | String | 具体的错误原因描述，如解析失败等 |

返回成功示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

返回失败示例

```json
{
    "serialNo": "0000000001",
    "uuid": "f47b00008ee62a00",
    "code": "C00001",
    "time": 1761275616,
    "sign": "",
    "message": "insertPermission: Failed to insert permission",
    "data": [
        {
            "permissionId": "6584132",
            "errmsg": "permission array parse (0) failed"
        },
        {
            "permissionId": "6584133",
            "errmsg": "permission array parse (1) failed"
        }
    ]
}
```

#### 6.2 查询权限

- 后台或应用到设备

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

data参数

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

发送示例：

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"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 | 查询结果数组长度，小于等于size，例如最后一页 |
| content | 权限数组 | Array | Y | 详见\< content数据\>表 |

content数据

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

返回示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"sign": "",
	"code": "000000",
	"data": {
		"content": [{
			"permissionId": "6584132",
			"time": {
				"type": 3,
				"range": {
					"beginTime": 1640917147,
					"endTime": 1790917147
				},
				"weekPeriodTime": {
					"1": "9:00-14:05",
					"2": "12:00-13:30|15:00-16:30"
				}
			}
		}],
		"page": 0,
		"size": 200,
		"total": 1,
		"totalPage": 1,
		"count": 1
	},
	"message": "success",
	"time": 1711595116
}
```

#### 6.3 删除权限

- 后台或应用到设备

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

data参数

| 参数名        | 说明   | 类型  | 必须 | 备注           |
| :------------ | :----- | :---- | ---- | -------------- |
| permissionIds | 权限Id | array | 否   | 权限的唯一标识 |
| 发送示例：    |        |       |      |                |

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"data": {
		"permissionIds": ["20190101120101", "20190101120102"]
	},
	"time": 1647580466,
	"sign": ""
}
```

- 设备回馈到后台或应用

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

- 通用 data 字段说明（仅失败时存在）：

| 参数名       | 描述     | 类型   | 附加说明                         |
| ------------ | -------- | ------ | -------------------------------- |
| permissionId | 权限 Id  | String | 失败的权限 Id                    |
| errmsg       | 错误描述 | String | 具体的错误原因描述，如解析失败等 |

返回成功示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

返回失败示例

```json
{
    "serialNo": "0000000001",
    "uuid": "f47b00008ee62a00",
    "code": "C00001",
    "time": 1761275488,
    "sign": "",
    "message": "delPermission: Failed to delete permission",
    "data": [
        {
            "permissionId": "20190101120101",
            "errmsg": "delete permission by userId:20190101120101 failed"
        },
        {
            "permissionId": "invalid",
            "errmsg": "get array item:1 failure"
        }
    ]
}
```

#### 6.4 清空权限

- 后台或应用到设备

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

发送示例：

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": ""
}
```

- 设备回馈到后台或应用

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

返回示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

#### 6.5 修改权限

- 后台或应用到设备

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

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

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

发送示例：

```json
{
	"scerialNo": "123456",
	"sign": "",
	"time": 1704866881,
	"uuid": "e4720000964b5c00",
	"data": [{
		"permissionId": "6584132",
		"time": {
			"type": 0,
		}
	}]
}
```

- 设备回馈到后台或应用

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

- 通用 data 字段说明（仅失败时存在）：

| 参数名       | 描述     | 类型   | 附加说明                         |
| ------------ | -------- | ------ | -------------------------------- |
| permissionId | 权限 Id  | String | 失败的权限 Id                    |
| errmsg       | 错误描述 | String | 具体的错误原因描述，如解析失败等 |

返回成功示例

```json
{
	"serialNo": "123456",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

返回失败示例

```json
{
    "serialNo": "123456",
    "uuid": "e4720000964b5c00",
    "code": "C00001",
    "time": 1761275616,
    "sign": "",
    "message": "insertPermission: Failed to modifyPermission",
    "data": [
        {
            "permissionId": "6584132",
            "errmsg": "permission array parse (0) failed"
        },
        {
            "permissionId": "6584133",
            "errmsg": "permission array parse (1) failed"
        }
    ]
}
```

## 七. 密钥管理接口

#### 7.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    | 密钥过期时间，时间戳（秒）       |

发送示例：

```json
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "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 |
| --------- | ------------------------------------------------ |

返回示例

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

#### 7.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 |

发送示例：

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"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 | 查询结果数组长度，小于等于size，例如最后一页 |
| content | 动态码数组 | Array | Y | 详见\< content数据\>表 |

content数据

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

返回示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"code": "000000",
	"message": "success",
	"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
		}]
	}
}
```

#### 7.3 删除密钥

- 后台或应用到设备

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

data参数

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

发送示例：

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

- 设备回馈到后台或应用

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

返回示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

#### 7.4 清空密钥

- 后台或应用到设备

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

发送示例：

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": ""
}
```

- 设备回馈到后台或应用

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

返回示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

## 八. 识别记录

#### 8.1 识别记录查询

- 后台或应用到设备

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

data参数

| 参数名    | 描述         | 类型   | 必传 | 附加说明                                                     |
| --------- | ------------ | ------ | ---- | ------------------------------------------------------------ |
| recordId  | 通行记录id   | String | N    | 通行记录唯一标识                                             |
| 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 开始                                                    |

发送示例：

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"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 | 查询结果数组长度，小于等于size，例如最后一页 |
| content | 记录数组 | Array | Y | 详见\< content数据\>表 |

content数据

| 参数名    | 描述                         | 类型   | 必传 | 附加说明                                                     |
| --------- | ---------------------------- | ------ | ---- | ------------------------------------------------------------ |
| recordId  | 通行记录id                   | String | Y    | 通行记录唯一标识                                             |
| 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    | 人卡/人码核验时，填写卡值或码值 |

返回示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"result": 0,
	"code": "000000",
	"message": "success",
	"data": {
		"index": 0,
		"length": 100,
		"total": 3,
		"totalPage": 1,
		"size": 3,
		"content": [{
			"recordId": "6w8keif5g6",
			"userId": "100002",
			"name": "常永彬",
			"timeStamp": 1639475284,
			"code": "/9j/4AAQSkZJRgABAQAAAQABAAD…"
		},
		{
			"recordId": "6w8keif5g7",
			"userId": "100002",
			"name": "常永彬",
			"timeStamp": 1639475288,
			"code": "/9j/4AAQSkZJRgABAQAAAQABAAD…"
		},
		{
			"recordId": "6w8keif5g8",
			"userId": "100002",
			"name": "常永彬",
			"timeStamp": 1639475291,
			"code": "/9j/4AAQSkZJRgABAQAAAQABAAD…"
		}]
	}
}
```

#### 8.2 识别记录删除

- 后台或应用到设备

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

data参数

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

发送示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"data": {
		"recordId": ["6w8keif5g8"]
	}
}
```

- 设备回馈到后台或应用

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

返回示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```
#### 8.3 通行记录上报

- 设备到后台或应用

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

消息参数说明

data参数

| 参数名    | 描述                         | 类型   | 必传 | 附加说明                                                     |
| --------- | ---------------------------- | ------ | ---- | ------------------------------------------------------------ |
| userId    | 用户ID                       | String | Y    |                                                              |
| type      | 用户类型                     | Int    | Y    | 当人卡码任一时参考- [凭证类型说明](#附表 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表

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

发送示例：

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

- 后台或应用回馈到设备

| 消息topic | topic: access_device/v2/event/{#uuid}/access_reply |
| --------- | -------------------------------------------------- |

返回示例

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"code": "000000",
	"message": "success"
}
```

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

[回到顶部](#category)

## 设备告警类型表
| 类型     | type | value                        | door         |
| -------- | ---- | ---------------------------- | ------------ |
| 门磁状态 | 0    | 0：门磁关、1：门磁开         | 对应门的序号 |
| 火警状态 | 1    | 0：火警关、1：火警开         | 无           |
| 非法开门 | 2    | 无                           | 无           |
| 开门超时 | 3    | 无                           | 无           |
| 关门超时 | 4    | 无                           | 无           |

[回到顶部](#category)

## 权限类型说明

| type | num | 说明                        |
| -------- | ---- | ---------------------------- |
| qrcode  | 100、101、103 | 100：透传码,101：静态码 ,103：动态码|
| password | 400 |  400：密码数据 ，密码长度：1~20位|
| card | 200 | 200:物理卡信息，203：身份证 |
| bluetooth | 600 |  600:蓝牙开门凭证 |

[回到顶部](#category)

## 时间区间

### 支持四种时间区域设置
- 1.缺省模式，不限时间，一直有效
```json
{
    "type": 0
}
```
- 2.通常模式，从开始到结束时间内有效
```json
{
    "type": 1,
    "range": {
      "beginTime": 1640917147,
      "endTime": 1690917147
    }
}
```
- 3.每日模式，每日特定时间到特定时间内有效(时间戳为当日零点到该时间的秒数)
```json
{
    "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"。1~7至少有一天为必传,无此项代表无权限，"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"
```json
{
    "type": 3,
    "weekPeriodTime":{
      "1":"9:00-10:00",
      "2":"12:00-13:30|15:00-16:30"
    },
    "range": {
      "beginTime": 1640917147,
      "endTime": 1690917147
    }
}
```

[回到顶部](#category)