网关服务接口定义

多弦门禁设备有很多型号，不同的型号接口有差异，但是总体上差不太多，当前文档是通用的接口文档描述，不同的型号可能还有一些特殊的接口和对应的接口文档。

# 一. 概述
## 1. 基本概念
- 门禁设备：可以控制门的开与关的物理设备，设备具备存储和计算功能，可以把能开门的凭证存储在设备里，当用户出示相应的“凭证”后，设备通过比较出示的凭证和存储的凭证来判断是否可以开门。
- 门禁设备接口：这里通常指门禁设备暴露给应用开发者的控制接口，开发者通过接口可以直接对接物理设备，但是我们不建议直接对接设备，比较繁琐、困难而且需要理解更多技术概念。我们推荐通过“多弦网关系统”来对接设备。
- 网关系统：多弦网关系统是可以独立安装部署的软件系统，对北向提供 Http 的管理接口，南向管理设备。注意，多弦网关系统是可以同时对接和管理多个门禁设备。当前文档就是北向的 HTTP 接口文档。
- 通行凭证：通行的凭证有很多类型，比如二维码、人脸、卡、指纹、密码等，不同的设备类型支持一种或几种凭证组合，每个用户针对每种类型也可以有多个凭证，不同的凭证的值也不同，比如二维码可能是用手机号做标识、人脸是用人的照片做凭证、指纹当然是用人的指纹做凭证。
- 离线验证/在线验证: 我们提供的设备都具备离线验证的功能，也就是设备里存储了通行凭证，即使设备离线也能实现门禁功能。部分设备也支持在线验证，也就是设备里存储不通行凭证，在人通行的时候获取到的凭证会上报到应用系统，由应用系统来决定是否能开门。
- 凭证(权限)下发: 我们通常也把凭证称之为权限，意思是能开门的权限。权限下发是指把用户的凭证通过接口发送到设备上存储下来，确保设备即使离线也能正常控制门禁，所以这里的权限下发是特指离线验证的方式。
- UUID： 每个设备都有一个唯一标识(SN)，我们用 UUID 来表示，通常是一个10几位的字符串。UUID 值不可修改。
- 门控标识: 通常一个设备控制一个门锁（门），但是个别设备具备一控多门的功能，控制板对接多个读头，每个读头对应一个门。这个时候需要有一个门控的标识来标记是那个门，我们通常用1，2，3，4来区分。远程开门或下发权限的时候需要用设备 UUID 加门控标识来唯一区分那个门。

## 2. 对接过程
网关系统的接入基本步骤是一致的，不同类型的设备有些许的差异。
- 第一步：安装网关系统
网关系统是 Java 开发的软件系统，可以运行在 Linux 和 Windows 下（需要不同的安装包，主要是内嵌 JRE 的差异），剩下就是配置文件和启动即可。一个平台实例可以同时对接几百个到上千个设备，主要看平台对应的服务器的配置性能。
我们也可以给客户提供安装系统的服务。

- 第二步：设备的网络配置和服务配置
 
![](/media/202502/WechatIMG4367_20250214160745823209.jpg)

如上图，我们的门禁设备基本上都具有网络功能，需要先设置好设备自身的ip，再在设备里设置需要对接的网关系统的ip，确保设备能连上平台。
不同的设备类型配置的方式不同，通常具备二维码功能的门禁设备都可以通过配置二维码来配置，平台也提供了生成配置二维码的接口。带屏幕的设备可以通过触屏来设置。还有一些设备通过上位机程序、内嵌网页、配置卡、配置 App 配置。

- 第三步：设置回调地址

![](/media/202502/WechatIMG4368_20250214160812350849.jpg)

如上图，网关系统提供了很多 HTTP API 给北向的应用系统来调用，本文档后面主要就是列出可以被调用的 API 详细说明，应用系统发出请求，平台返回结果。但是有一些情况是应用系统不发请求，而平台会主动上报一些数据，所以需要应用系统根据回调 API 的定义来实现 HTTP 的回调接口提供给平台来调用。
不同类型的上报数据会有不同的回调 API，北向 HTTP API提供了对应的设置回调地址的接口。应用系统对接平台需要调用一下设置回调地址的 API 。

- 第四步：权限下发
如前面的概念介绍，需要把用户的各种凭证通过接口下发到设备上，比如人脸、卡号等等。

- 第五步：通行记录和告警记录
第四步设置好后，任何人出示凭证尝试通行都会自动产生通行成功或失败的记录，设备会自动上报给平台，平台也会自动上报给应用系统。
还有一些特殊的告警事件，比如火警，异常开门等也会主动上报给应用系统。
应用系统收到这些上报数据后做相应的处理。

## 3. 接口概述
接口分二大类：
- 北向接口：应用系统调用这些接口来管控设备。
- 回调接口：应用系统提供这些接口来接收设备主动上报的数据。

接口只支持 GET 和 POST
支持多租户，也就是同样一个平台下允许不同的租户管理自己名下的设备，为了确保接口的安全，可以使用我们提供的AppKey和AppSecrect来区分和保证安全，这里会用到 HMAC 签名规则，详情参考 [多弦产品API签名安全规则](../278)

# 二. 北向接口
## 1. 远程开门
##### 接口描述
- 下发指令远程控制门禁设备，远程打开门

##### 请求URL
- `http://serveraddr:port/access/openDoor`

##### 请求方式
- **GET**

##### Query参数

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|uuid |是  |string |设备唯一标识   |-   |
|index |否  |string |门控标识，个别设备支持一控多门，比如一控四，每个门控都有一个编号来区分   |1，2，3，4这种标识   |

##### 请求示例
``` json
http://serveraddr:port/access/openDoor?uuid=s49li42fjo
```

##### 响应参数说明

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|code | 是   |int| 状态码 | 成功：1，失败：0   |
|msg | 是   |string| 描述信息 |-   |
|data | 是   |object| 返回内容 |-   |

##### 响应示例
``` json
{
        "code": 1,
        "msg": "",
        "data": ""
}
```
## 2. 远程重启
##### 接口描述
- 下发指令远程控制门禁设备，远程重启设备，部分设备类型不支持

##### 请求URL
- `http://serveraddr:port/access/reboot`

##### 请求方式
- **GET**

##### Query参数

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|uuid |是  |string |设备唯一标识   |-   |

##### 请求示例
``` json
http://serveraddr:port/access/reboot?uuid=s49li42fjo
```

##### 响应参数说明

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|code | 是   |int| 状态码 | 成功：1，失败：0   |
|msg | 是   |string| 描述信息 |-   |
|data | 是   |object| 返回内容 |-   |

##### 响应示例
``` json
{
        "code": 1,
        "msg": "",
        "data": ""
}
```
## 3. 语音播报
##### 接口描述
- 下发指令远程控制门禁设备，语音播报（暂时仅通用人脸设备支持）

##### 请求URL
- `http://serveraddr:port/access/broadcast`

##### 请求方式
- **GET**

##### Query参数

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|uuid |是  |string |设备唯一标识   |-   |
|text |否  |string | 播报内容 |   |

##### 请求示例
``` json
http://serveraddr:port/access/broadcast?uuid=s49li42fjo&text=请通行
```

##### 响应参数说明

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|code | 是   |int| 状态码 | 成功：1，失败：0   |
|msg | 是   |string| 描述信息 |-   |
|data | 是   |object| 返回内容 |-   |

##### 响应示例
``` json
{
        "code": 1,
        "msg": "",
        "data": ""
}
```

## 4. 同步时间
##### 接口描述
- 下发指令远程同步门禁设备的时间戳，确保设备的时间和应用的时间是同步的，长时间设备运行有可能有时间的偏差。

##### 请求URL
- `http://serveraddr:port/access/setTime`

##### 请求方式
- **GET**

##### Query参数

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|uuid |是  |string |设备唯一标识   |-   |
|timestamp |是  |number |13位时间戳（毫秒）   |-   |

##### 请求示例
``` json
http://serveraddr:port/access/setTime?uuid=s49li42fjo&timestamp=1676281886769
```

##### 响应参数说明

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|code | 是   |int| 状态码 | 成功：1，失败：0   |
|msg | 是   |string| 描述信息 |-   |
|data | 是   |object| 返回内容 |-   |

##### 响应示例
``` json
{
        "code": 1,
        "msg": "",
        "data": ""
}
```

## 5. 添加/更新设备
##### 接口描述
- 添加当前租户自己管理的设备，如果添加的设备uuid已经存在，则更新其他属性

##### 请求URL
- `http://serveraddr:port/access/insertDevice`

##### 请求方式
- **POST**

##### Body参数
Body是一个列表，以下是列表内一个对象的说明
|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|uuid |是  |string |设备唯一标识   |-   |
|firmwareProtocol |是  |string |设备固件协议id   |参考[附录2](#firmwareProtocol)   |
|ip |否  |string |规划的设备ip地址   |-   |
|remark |否  |string |设备备注，比如名称   |-   |

##### 请求示例
``` json
http://serveraddr:port/access/insertDevice
[
  {    
    "uuid":"ABAQEAeAB4A",
    "firmwareProtocol":"vg20180820",
    "ip":"192.168.1.22",
    "remark":"北大门"
  },
]
```

##### 响应参数说明

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|code | 是   |int| 状态码 | 成功：1，失败：0   |
|msg | 是   |string| 描述信息 |-   |
|data | 是   |object| 返回内容 |-   |

##### 响应示例
``` json
{
  "code": 1,
  "msg": "",
  "data": ""
}
```

## 6. 删除设备
##### 接口描述
- 删除当前租户自己管理的设备

##### 请求URL
- `http://serveraddr:port/access/deleteDevice`

##### 请求方式
- **POST**

##### Body参数
Body是一个列表，以下是列表内一个对象的说明
|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|uuid |是  |string |设备唯一标识   |-   |

##### 请求示例
``` json
http://serveraddr:port/access/deleteDevice
[
  {    
    "uuid":"ABAQEAeAB4A"
  },
]
```

##### 响应参数说明

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|code | 是   |int| 状态码 | 成功：1，失败：0   |
|msg | 是   |string| 描述信息 |-   |
|data | 是   |object| 返回内容 |-   |

##### 响应示例
``` json
{
  "code": 1,
  "msg": "",
  "data": ""
}
```

## 7. 查询设备
##### 接口描述
- 分页查询租户下设备及设备基本在线状态

##### 请求URL
- `http://serveraddr:port/access/findAllDevice`

##### 请求方式
- **GET**

##### Query参数

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|page |否  |string |分页查询的第几页，从0开始   |缺省为0   |
|size |否  |string |分页查询的每页大小   |缺省为10   |

##### 请求示例
``` json
http://serveraddr:port/access/findAllDevice?page=1&size=100
```

##### 响应参数说明

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|code | 是   |int| 状态码 | 成功：1，失败：0   |
|msg | 是   |string| 描述信息 |-   |
|data | 是   |object| 返回内容 |-   |
|- totalPages | 是   |number| 返回的总页数 |-   |
|- totalElements | 是   |number| 返回的元素总数 |-   |
|- number | 是   |number| 当前第几页，从0开始 |-   |
|- size | 是   |number| 每页的元素个数 |-   |
|- numberOfElements | 是 |number| 返回当前页的元素数量，如果是最后一页有可能这个值和size不一致 |-   |
|- content | 是   |list| 返回的真正数据列表 |-   |
|- - uuid | 是   |string| 设备uuid |-   |
|- - ip | 否   |string| 设备规划的ip |-   |
|- - realIp | 否   |string| 设备如果连上平台会有实际的ip，有可能和规划的ip不符 |-   |
|- - firmwareProtocol |是  |string |设备固件协议id   |参考[附录2](#firmwareProtocol)   |
|- - remark |否  |string |设备备注，比如名称   |-   |
|- - online |是  |bool |设备是否在线   |true或false   |

##### 响应示例
``` json
{
	"code": 1,
	"msg": "",
	"data": {
		"totalPages": 2,
		"totalElements": 19,
		"number": 0,
		"size": 10,
		"numberOfElements": 10,
		"content": [{
			"uuid": "s49li42fjo",
			"ip": "192.168.2.34",
			"realIp": "192.168.2.32",
			"firmwareProtocol": "vg20180820",
			"remark": "南大门",
			"online": true
		}, {
			"uuid": "agrtd2fjo",
			"ip": "192.168.2.33",
			"realIp": "192.168.2.33",
			"firmwareProtocol": "vg20180820",
			"remark": "北大门",
			"online": true
		}]
	}
}
```
## 8. 抓拍人脸照片
##### 接口描述
- 下发指令远程控制门禁设备，使设备处于人脸抓拍的状态，获取照片base64后返回，部分设备类型不支持

##### 请求URL
- `http://serveraddr:port/vf/getPicBase64`

##### 请求方式
- **GET**

##### Query参数

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|uuid |是  |string |设备唯一标识   |-   |

##### 请求示例
``` json
http://serveraddr:port/vf/getPicBase64?uuid=s49li42fjo
```

##### 响应参数说明

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|code | 是   |int| 状态码 | 成功：1，失败：0   |
|msg | 是   |string| 描述信息 |-   |
|data | 是   |sting| 抓拍照片的base64值 |约100kb   |

##### 响应示例
``` json
{
        "code": 1,
        "msg": "",
        "data": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAoHBwgH..."
}
```

## 9. 下发人脸照片
##### 接口描述
- 下发一张人脸照片（base64）到指定设备，并和用户的唯一id绑定在一起,人脸权限比较特殊，人脸凭证数据太大而且一个人只能是一张人脸，需要先下发照片，再下发权限，下发权限的时候只需要以用户id 为人脸凭证。

> 注意图片大小不超过200k，格式只支持 PNG 和 JPG

##### 请求URL
- `http://serveraddr:port/access/insertPersonFace`

##### 请求方式
- **POST**

##### Body参数
|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|uuid | 是   |string| 设备uuid |-   |
|data |是  |string |照片的base64值   |-   |
|userId |是  |string |人员的id   |-   |
|index |否  |string |门控标识，个别设备支持一控多门，比如一控四，每个门控都有一个编号来区分   |1，2，3，4这种标识   |
| extra |是  |string |额外数据，比如人员姓名  |-   |

##### 请求示例
``` json
http://serveraddr:port/access/insertPersonFace

{
  "data":"/9j/4AAQSkZJRgABAQEAeAB4AAD/2wBDAAIQICAgICAgICAwUDAwMDAwYEBAMF...",
  "userId":"534950249",
  "uuid":"s49li42fjo"
  "extra":"{\"name\":\"名称\"}"
}
```

##### 响应参数说明

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|code | 是   |int| 状态码 | 成功：1，失败：0   |
|msg | 是   |string| 描述信息 |-   |
|data | 是   |object| 返回内容 |-   |

##### 响应示例
``` json
{
  "code": 1,
  "msg": "",
  "data": ""
}
```
## 10. 删除人脸照片
##### 接口描述
- 根据 userid 在设备上删除一张人脸照片。

##### 请求URL
- `http://serveraddr:port/access/deletePersonFace`

##### 请求方式
- **GET**

##### Query参数
|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|uuid | 是   |string| 设备uuid |-   |
|userId |是  |string |人员的id   |-   |
|index |否  |string |门控标识，个别设备支持一控多门，比如一控四，每个门控都有一个编号来区分   |1，2，3，4这种标识   |

##### 请求示例
``` json
http://serveraddr:port/access/deletePersonFace?uuid=s49li42fjo&userId=534950249

```

##### 响应参数说明

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|code | 是   |int| 状态码 | 成功：1，失败：0   |
|msg | 是   |string| 描述信息 |-   |
|data | 是   |object| 返回内容 |-   |

##### 响应示例
``` json
{
  "code": 1,
  "msg": "",
  "data": ""
}
```
## 11. 下发权限
##### 接口描述
- 给设备下发权限（凭证）。

##### 请求URL
- `http://serveraddr:port/access/insertPermission`

##### 请求方式
- **POST**
##### Query参数

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|uuid |是  |string |设备唯一标识   |-   |
|index |否  |string |门控标识，个别设备支持一控多门，比如一控四，每个门控都有一个编号来区分   |1，2，3，4这种标识   |

##### Body参数
Body是一个列表，以下是列表每个对象的参数说明
|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
| id |否  |string |权限的唯一标识，非必填，因为很多设备并不支持唯一标识   | VF203、安卓人脸、DW200必填|
| type |是  |string |设备支持的身份类型,人脸、二维码、密码、蓝牙等，必填  |支持 face,qrcode,password,bluetooth,card,fingerprint  |
| subType |否  |string |某些类型可能还有子类型，比如卡，二维码可能有多种子类型，非必填  |-   |
| userId |是  |string |人员id等  |-   |
| code |是  |string |通行凭证：卡号、密码、人脸照片对应的userId等，这个是必填项  |-   |
| uuid |是  |string |设备唯一标识  |-   |
| timePeriod |是  |object |权限时间设置  |参考[附录1](#timeperiod)   |
| extra |否  |string |额外数据，比如人员姓名，梯控楼层权限  |格式看示例 对象转字符串( 106/206人脸权限时必填) |
|├─├─name  |否  |String |人员名称  | 如下例子|
|├─├─floor  |否  |String |楼层信息  |extra的元素  设备属于cc101梯控设备时必填，参数值为：{"floor":"1,2,3"}其中floor表示楼层，floor值为"all"表示所有楼层都有权限；设备属于人脸梯控设备时必填，参数参考[附录2](#tikong) 。|

##### 请求示例
``` json
http://serveraddr:port/access/insertPermission?uuid=s49li42fjo

[
    {
      "id":"",
      "type":"face",
      "subType":"",
      "code":"534950249",
      "userId":"49fg95j93oo",
      "uuid":"s49li42fjo",
      "timePeriod":{
      "type":0
},
      "extra":"{\"name\":\"姓名\"}"
    },{
      "id":"",
      "type":"password",
      "subType":"",
      "code":"123456",
      "userId":"49fg95j93oo",
      "uuid":"s49li42fjo",
      "timePeriod":{
      "type":0
},
      "extra":"{\"name\":\"姓名\"}"
    },{
      "id":"",
      "type":"card",
      "subType":"",
      "userId":"49fg95j93oo",
      "code":"123141212312",
      "uuid":"s49li42fjo",
      "timePeriod":{
      "type":0
},
      "extra":"{\"name\":\"姓名\"}"
    }
]
```

##### 响应参数说明

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|code | 是   |int| 状态码 | 成功：1，失败：0   |
|msg | 是   |string| 描述信息 |-   |
|data | 是   |array| 返回成功或失败的权限内容 |-   |
|- result |是  |number |下发权限成功或失败，0表示失败，1表示成功  |-   |
|- data |否  |string |成功或失败对应的说明，失败对应是失败原因  |-   |
|- permission |是  |object |下发的权限完整数据  |-   |
|- - id |否  |string |权限的唯一标识，非必填，因为很多设备并不支持唯一标识   |-   |
|- - type |是  |string |设备支持的身份类型,人脸、二维码、密码等，必填  |支持 face,qrcode,password,card,fingerprint  |
|- - subType |否  |string |某些类型可能还有子类型，比如卡，二维码可能有多种子类型，非必填  |-   |
|- - userId |是  |string |人员id等  |-   |
|- - code |是  |string |通行凭证：卡号、密码、人脸照片对应的userId等，这个是必填项  |-   |
|- - uuid |是  |string |设备唯一标识  |-   |
|- - timePeriod |是  |object |权限时间设置  |参考[附录1](#timeperiod)   |
|- - extra |否  |string |额外数据，比如人员姓名  |-   |

##### 响应示例
``` json
{
  "code": 1,
  "msg": "",
  "data": [
    {
      "result":1,
      "data":"",
      "permission":{
        "id":"",
        "type":"face",
        "subType":"",
        "code":"534950249",
        "userId":"49fg95j93oo",
        "uuid":"s49li42fjo",
        "timePeriod":{
      "type":0
},
        "extra":""
      }
    },    
    {
      "result":1,
      "data":"",
      "permission":{
        "id":"",
        "type":"card",
        "subType":"",
        "userId":"49fg95j93oo",
        "code":"123141212312",
        "uuid":"s49li42fjo",
        "timePeriod":{
      "type":0
},
        "extra":""
      }，{
      "result":1,
      "data":"",
      "permission":{
        "id":"",
        "type":"password",
        "subType":"",
        "code":"123456",
        "userId":"49fg95j93oo",
        "uuid":"s49li42fjo",
        "timePeriod":{
      "type":0
},
        "extra":""
      }
    }
    }
	]
}
```
## 12. 删除权限
##### 接口描述
- 给设备删除权限（凭证）

##### 请求URL
- `http://serveraddr:port/access/deletePermission`

##### 请求方式
- **POST**
##### Query参数

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|uuid |是  |string |设备唯一标识   |-   |
|index |否  |string |门控标识，个别设备支持一控多门，比如一控四，每个门控都有一个编号来区分   |1，2，3，4这种标识   |

##### Body参数
Body是一个数组，以下是数组每个元素的参数说明
cc104和DW200 只有id必传
|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
| id |否(VF203、cc104和DW200必传)  |string |权限的唯一标识，非必填，因为很多设备并不支持唯一标识   | VF203、安卓人脸、DW200必填  |
| type |是(cc104和DW200为否)  |string |设备支持的身份类型,人脸、二维码、密码等，必填  |支持 face,qrcode,password,card,fingerprint  |
| subType |否  |string |某些类型可能还有子类型，比如卡，二维码可能有多种子类型，非必填  |-   |
| userId |是(cc104和DW200为否)  |string |人员id  |-   |
| code |是(cc104和DW200为否)  |string |通行凭证：卡号、密码、人脸照片对应的id等，这个是必填项  |-   |
| uuid |是(cc104和DW200为否)  |string |设备唯一标识  |-   |
| timePeriod |是(cc104和DW200为否)  |object |权限时间设置  |参考[附录1](#timeperiod)  |
| extra |是(cc104和DW200为否)  |string |额外数据  |-   |

##### 请求示例
``` json
http://serveraddr:port/access/deletePermission?uuid=s49li42fjo

[
    {
      "id":"",
      "type":"face",
      "subType":"",
      "code":"534950249",
      "uuid":"s49li42fjo",
      "userId":"49fg95j93oo",
      "timePeriod":{
      "type":0
},
      "extra":""
    },
    {
      "id":"",
      "type":"card",
      "subType":"",
      "code":"123141212312",
      "userId":"49fg95j93oo",
      "uuid":"s49li42fjo",
      "timePeriod":{
      "type":0
},
      "extra":""
    },{
      "id":"",
      "type":"password",
      "subType":"",
      "code":"123456",
      "userId":"49fg95j93oo",
      "uuid":"s49li42fjo",
      "timePeriod":{
      "type":0
},
      "extra":""
    }
]
```

##### 响应参数说明

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|code | 是   |int| 状态码 | 成功：1，失败：0   |
|msg | 是   |string| 描述信息 |-   |
|data | 是   |object| 返回内容 |-   |
|- result |是  |number |删除权限成功或失败，0表示失败，1表示成功  |-   |
|- data |否  |string |成功或失败对应的说明，失败对应是失败原因  |-   |
|- permission |是  |object |下发的权限完整数据  |-   |
|- - id |否  |string |权限的唯一标识，非必填，因为很多设备并不支持唯一标识   |-   |
|- - type |是  |string |设备支持的身份类型,人脸、二维码、密码等，必填  |支持 face,qrcode,password,card,fingerprint  |
|- - subType |否  |string |某些类型可能还有子类型，比如卡，二维码可能有多种子类型，非必填  |-   |
|- - userId |是  |string |人员id等  |-   |
|- - code |是  |string |通行凭证：卡号、密码、人脸照片对应的userId等，这个是必填项  |-   |
|- - uuid |是  |string |设备唯一标识  |-   |
|- - timePeriod |是  |object |权限时间设置  |参考[附录1](#timeperiod)   |
|- - extra |否  |string |额外数据，比如人员姓名  |-   |

##### 响应示例
``` json
{
  "code": 1,
  "msg": "",
  "data": [
    {
      "result":1,
      "data":"",
      "permission":{
        "id":"",
        "type":"face",
        "subType":"",
        "code":"534950249",
        "userId":"49fg95j93oo",
        "uuid":"s49li42fjo",
        "timePeriod":{
      "type":0
},
        "extra":""
      }
    },    
    {
      "result":1,
      "data":"",
      "permission":{
        "id":"",
        "type":"card",
        "subType":"",
        "userId":"49fg95j93oo",
        "code":"123141212312",
        "uuid":"s49li42fjo",
        "timePeriod":{
      "type":0
},
        "extra":""
      }, {
      "result":1,
      "data":"",
      "permission":{
        "id":"",
        "type":"password",
        "subType":"",
        "code":"123456",
        "userId":"49fg95j93oo",
        "uuid":"s49li42fjo",
        "timePeriod":{
      "type":0
},
        "extra":""
      }
    }
    }
	]
}
```
## 13. 清空权限
##### 接口描述
- 根据 uuid 清空设备上所有权限，如果支持人脸，也会同时清空人脸照片

##### 请求URL
- `http://serveraddr:port/access/clearPermission`

##### 请求方式
- **GET**
##### Query参数
|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|uuid |是  |string |设备唯一标识   |-   |
|index |否  |string |门控标识，个别设备支持一控多门，比如一控四，每个门控都有一个编号来区分   |1，2，3，4这种标识   |

##### 请求示例
``` json
http://serveraddr:port/access/clearPermission?uuid=s49li42fjo
```

##### 响应参数说明

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|code | 是   |int| 状态码 | 成功：1，失败：0   |
|msg | 是   |string| 描述信息 |-   |
|data | 是   |object| 返回内容 |-   |

##### 响应示例
``` json
{
  "code": 1,
  "msg": "",
  "data": ""
}
```
## 14. 设置回调地址
##### 接口描述
- 设置回调地址，确保这个地址可以被平台访问到

##### 请求URL
- `http://serveraddr:port/access/setCallback`

##### 请求方式
- **GET**
##### Query参数
|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|url |是  |string |回调地址url   |-   |

##### 请求示例
``` json
http://serveraddr:port/access/setCallback?url=http://192.168.1.1/callback
```

##### 响应参数说明

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|code | 是   |int| 状态码 | 成功：1，失败：0   |
|msg | 是   |string| 描述信息 |-   |
|data | 是   |object| 返回内容 |-   |

##### 响应示例
``` json
{
        "code": 1,
        "msg": "",
        "data": ""
}
```
## 15. 下载图片
##### 接口描述
- 根据文件id下载对应的图片，人脸设备在通行的时候抓拍实时照片，上报到应用只会上报照片对应的文件id，可以通过这个接口来获取真正的照片

##### 请求URL
- `http://serveraddr:port/access/downloadImage`

##### 请求方式
- **GET**
##### Query参数
|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|id |是  |string |图片对应的唯一字符串标识   |-   |

##### 请求示例
``` json
http://serveraddr:port/access/downloadImage?id=sd345f23421
```

##### 响应说明
直接返回图片二进制内容，也可以把这个链接作为H5的 img 标签的 src,比如
``` html
<img src="http://serveraddr:port/access/downloadImage?id=sd345f23421">
```
## 16. 修改配置
##### 接口描述
- 修改设备属性  不同设备对应不同配置项，如需修改联系工作人员获取设备配置项

##### 请求URL
- `http://serveraddr:port/access/setProperty`

##### 请求方式

- **POST**
##### Query参数
|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|uuid |是  |string |设备唯一标识   |-   |

##### Body参数
|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|data | 是   |object| 参考设备各自协议文档[附录-设备协议](#firmwareProtocol)，在各自协议文档的配置功能里查看 |-   |

##### 请求示例
``` json
http://serveraddr:port/access/setProperty
//案例为修改 dw200 背景图
{
  "uiInfo.rotation":0,//0：横屏0度，1：90度，2:180度，3:270度
  "uiInfo.horBgImage":"图片的base64",//水平背景图(图像格式仅支持PNG
  "uiInfo.verBgImage":"图片的base64"//竖直背景图(图像格式仅支持PNG)
}
```

##### 响应示例
``` json
{
        "code": 1,
        "msg": "",
        "data": ""
}
```
## 17. 通行码获取
##### 接口描述
- 传入通行凭证生成设备识别的101、103码内容
-返回结果中的 data字符串直接生成二维码设备即可识别

- `http://serveraddr:port/access/getPassCode`

##### 请求方式
- **POST**
##### Query参数
|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|uuid |是  |string |设备唯一标识(名下任意设备即可，目的校验是否有我们设备)   |-   |

##### Body参数
|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|type | 是   |Integer| 码类型 101、103 |-   |
|code | 是   |String| 通行凭证 |-   |
|orgCode | 否   |String| 组织编号(默认 vguang) 103 必填 |-   |
|expireTime | 否   |String| 码过期时间(秒) 103 必填 |-   |

##### 请求示例
``` json
http://serveraddr:port/access/getPassCode

{
  "type": 103,
  "code": "123456",
  "orgCode": "vguang",
  "expireTime": "999"
}
```

##### 响应参数说明

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|code | 是   |int| 状态码 | 成功：1，失败：0   |
|msg | 是   |string| 描述信息 |-   |
|data | 是   |object| 返回内容 生成二维码数据 |-   |

##### 响应示例
``` json
{
  "code": 1,
  "msg": "",
  "data": "vg://v103AQAGAHZndWFuZwIAQABzBxcRNgRYQM35sZFl～～～～"
}
```
# 三. 回调接口

注意：多弦网关界面上，在系统管理->基本信息—>回调地址 中填写好您的url前缀，多弦网关将在前缀后直接拼接进行回调，例如：填写前缀为 http:xxx.com/xxx 那么网关若回调通行记录，则使用接口http:xxx.com/xxx/accessRecord;
## 1. 告警回调
##### 接口描述
- 设备会主动上报多种告警数据

##### 请求URL
- `http://回调地址/alarmRecord`

##### 请求方式
- **POST**

##### Body参数
|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|uuid |是  |string |设备唯一标识   |-   |
|type |是  |string |告警类型   |online:在线离线告警；fire:火警类型；door_sensor:门磁状态告警；door_abnormal:异常开门告警；door_timeout:开门超时   |
|value |否  |string |告警值（可能为空）   |type是online的时候：0表示离线，1表示在线；type是fire的时候：0表示关，1表示开；type是door_sensor的时候：0表示关，1表示开   |
|time |是  |string |告警的时间戳（毫秒)   |-   |

##### 请求示例
``` json
{
  "type":"online",
  "value":1,
  "time":"1676281886769",
  "uuid":"s49li42fjo"
}
```

##### 响应参数说明

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|code | 是   |int| 状态码 | 成功：1，失败：0   |
|msg | 是   |string| 描述信息 |-   |
|data | 是   |object| 返回内容 |-   |

##### 响应示例
``` json
{
  "code": 1,
  "msg": "",
  "data": ""
}
```
## 2. 通行回调
##### 接口描述
- 设备会主动上报通行的记录

##### 请求URL
- `http://回调地址/accessRecord`

##### 请求方式
- **POST**

##### Body参数
参数是一个对象列表，以下是对象的属性说明
|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|- id |否  |string |权限的唯一标识，可能为空   |-   |
|- type |是  |string |设备支持的身份类型,人脸、二维码、密码等  |支持 face,qrcode,password,card,fingerprint  |
|- code |是  |string |通行凭证：卡号、密码、人脸对应的文件id等 |-   |
|- uuid |是  |string |设备唯一标识  |-   |
|- userId |是  |string |人员id  |-   |
|- result |是  |number |通行成功或失败，0表示失败，1表示成功  |-   |
|- extra |否  |string |人员名称等扩展数据  |-   |
|- faceCaptureImage |否  |string |人脸设备可能在通行的时候会抓拍实时的照片，这个值是照片对应的唯一标识，可以通过downloadImage接口来下载对应的图片  |-   |
|- time |是  |string |告警的时间戳（毫秒)   |-   |
|- index |否  |string |门控标识，个别设备支持一控多门，比如一控四，每个门控都有一个编号来区分   |1，2，3，4这种标识   |

##### 请求示例
``` json
[
    {
      "id":"",
      "type":"face",
      "code":"534950249",
      "result":1,
      "uuid":"s49li42fjo",
      "userId":"49fg95j93oo",
      "extra":"",
      "faceCaptureImage":"sd345f23421",
      "time":"1676281886888"
    },
    {
      "id":"",
      "type":"card",
      "code":"123141212312",
      "result":0,
      "uuid":"s49li42fjo",
      "userId":"49fg95j93oo",
      "extra":"",
      "faceCaptureImage":"",
      "time":"1676281886999"
    }
  ]
```

##### 响应参数说明

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|code | 是   |int| 状态码 | 成功：1，失败：0   |
|msg | 是   |string| 描述信息 |-   |
|data | 是   |object| 返回内容 |-   |

##### 响应示例
``` json
{
        "code": 1,
        "msg": "",
        "data": ""
}
```
## 3. 在线验证
##### 接口描述
- 设备会主动上报通行的记录根据返回结果来控制是否开门

##### 请求URL
- `http://回调地址/onlineCheck`

##### 请求方式
- **POST**

##### Body参数
参数是一个对象，以下是对象的属性说明
|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|- id |否  |string |权限的唯一标识，可能为空   |-   |
|- type |是  |string |设备支持的身份类型,人脸、二维码、密码等  |支持 face,qrcode,password,card,fingerprint  |
|- code |是  |string |通行凭证：卡号、密码、人脸对应的文件id等 |-   |
|- uuid |是  |string |设备唯一标识  |-   |
|- userId |是  |string |人员id  |-   |
|- result |是  |number |通行成功或失败，0表示失败，1表示成功  |-   |
|- extra |否  |string |人员名称等扩展数据  |-   |
|- faceCaptureImage |否  |string |人脸设备可能在通行的时候会抓拍实时的照片，这个值是照片对应的唯一标识，可以通过downloadImage接口来下载对应的图片  |-   |
|- time |是  |string |告警的时间戳（毫秒)   |-   |
|- index |否  |string |门控标识，个别设备支持一控多门，比如一控四，每个门控都有一个编号来区分   |1，2，3，4这种标识   |

##### 请求示例
``` json

{
      "id":"",
      "type":"face",
      "code":"534950249",
      "result":1,
      "uuid":"s49li42fjo",
      "userId":"49fg95j93oo",
      "extra":"",
      "faceCaptureImage":"sd345f23421",
      "time":"1676281886888"
    }
```

##### 响应参数说明

|参数名|必填|类型|说明|备注|
|:----    |:---|:----- |-----   |-----   |
|code | 是   |int| 状态码 | 允许通行：1，拒绝通行：0   |
|msg | 是   |string| 描述信息 |-   |
|data | 是   |object| 返回内容 |-   |

##### 响应示例
``` json
{
        "code": 1,
        "msg": "",
        "data": ""
}
```
# 四. 附录
<span id="timeperiod">
  
## 1. 权限时间
timePeriod 支持多种类型：
- 第一种是永久有效，这个是缺省值，不设置就是永久有效，如果设置的话，示例如下

``` json
  {
        "type":0
  }
        ```
- 第二种是在一个时间区间内有效，如果设置的话，示例如下
        
  ``` json
  {
        "type":1,
        "startTime":1677662234324，//毫秒时间戳
        "endTime":1677662277000,
  }
        ```
  
- 第三种是周重复模式（部分设备支持），周一到周日特定时间到特定时间内有效，其它时间无效(每天的多组时间段不重叠，最多支持五组)。weekPeriodTimes参数如下，每天的时间格式为："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"
  
  ```json
  {
      "type": 2,
      "weekPeriodTimes":
      {
          "1": "9:00-10:00",
          "2": "12:00-13:30|15:00-16:30"
      }
  --需要把这个weekPeriodTimes转成字符串--
  {\"1\": \"9:00-10:00\",\"2\": \"12:00-13:30|15:00-16:30\"},
      "beginTime": 1640917147000,
      "endTime": 1690917147000
  }
  ```
  
  其中开始时间和结束时间都是毫秒级别的时间戳
<span id="firmwareProtocol">
  
## 2. 固件协议类型
|协议ID	|	协议名称	|	支持设备型号	|协议文档|	
|---	|	---	|	---	|	---	|	
| jy20230302 | 捷易人脸协议   | P103-BG||
| nq20230210 | 纳奇人脸协议   | NQ-F5901 plus ||
| qt20230313 |  停车设备协议 |     -       |   |
| qy20230301 |  芊熠人脸协议   |    -          ||
| tt20230619 | TT锁设备     | TT锁设备     ||
| vg20180820 |  扫码器通用协议 | M350、MP86、MX86、DW100、MET、MU86 |[2018扫码器协议](/duoxian/对外发布/文档/设备协议/2018扫码器协议) |
| vg20211101 |  控制板单控协议 | CC101 | |
| vg20211214 |  人脸通用协议   | VF101、VF102、VF104、VF105 |[VF系列MQTT协议文档V1_0_19](/duoxian/对外发布/文档/设备协议/VF系列MQTT协议文档V1_0_19)|
| vg20211214vf205 | vf205人脸设备 | vf205      | |
| vg20220814 |  VF106协议(老) | VF106    | [VF106&VF206](/duoxian/对外发布/文档/设备协议/VF106&VF206)|
| vg20220814vf206 | vf206人脸设备 | vf206      |[VF106&VF206](/duoxian/对外发布/文档/设备协议/VF106&VF206)｜
| vg20230223 |  控制板多控协议 | CC104         | |
| vg20230308 |  M800扫码器设备协议 | M800       | |
| vg20230404 |  人脸适配梯控协议 | VF105     | | 
| vg20230406 |  控制板适配梯控协议 | CC101   |    | 
| vg20230520 |  vf106设备协议（新） | vf106    |    |
| vg20230601 |  DW200设备协议 | DW200     |   | 
| vg20230601_0 |  DW200设备协议（不带屏） | DW200   |     |
| vg20230612 |  M08、M500等设备协议 | M08、M500 | |
| vg20230626 |vf202、203设备协议 | VF202、VF203 ||
| vg20230703 |  卷帘门设备协议 | 卷帘门设备 | |
| yf20230208 |  宇泛人脸协议 | 宇泛人脸全品类 ||
| zkc20230808 |  ZKC 音响 | ZKC 音响 ||
| cc104 |  CC104新版协议 | CC104新版协议 |[门禁控制板MQTT协议文档v1_0_6](/duoxian/对外发布/文档/设备协议/门禁控制板MQTT协议文档v1_0_6)|
  <span id="tikong">
    
## 3. 梯控格式
- 直达某个楼层
D2+楼层
4楼：D2+4
10楼：D2+10
- 手动开放楼层，开放时间为按钮响应时间
D3+楼层
4楼：D3+4
10楼：D3+10
（多楼层可用","英文逗号隔开如 "floor"="D3+2,3,4"）

- 关闭手动所有受控楼层
DE+0
- 开放手动所有受控楼层
DF+0

注意：楼层数=实际楼层数+楼层偏置数；例如，某栋建筑存在地下2层，那么楼层偏置数为2，因此实际上的3楼需要变为3+2=5。