门禁系统HTTP服务接口

一、约定

ü 使用HTTP协议，POST请求

ü 交互数据为utf8编码的JSON数据，大小写敏感。除了表示操作结果代码的code为数字，其它字段默认都尽量使用字符串类型。

ü 字符串时间格式为YYYY-MM-DD HH:MI:SS 24小时制，时间从1970-01-01 00:00:00开始

ü 图片采用jpg格式，数据经BASE64编码后传输，编码后的字符串应该只有原始数据，不能包含特定应用专用的标记，不能包含为了美观以及易读而加入的回车换行符

正确内容 /9j/4AAQSkZJRgABAQEAYABgA...

错误内容 data:image/jpg;base64,/9j/4AAQSkZJRgABAQEAYABgA...

ü 加密密钥key约定为506a848e-d08e-4c70-82e5-e2128cd5b8cd

ü 请求Header中添加tick，值为当前时间戳，1970年到当前的秒数，如1626485104

ü 请求Header中添加authorization，值为POST请求内容使用&号连接上时间戳，再使用&号连接上加密密钥key后的字符串，做md5计算出来的32位小写md5值。

举例，如果POST请求的JSON内容为{"id":"NO.00025"}

tick为1626485104，则计算authorization

MD5({"id":"NO.00025"}&1626485104&506a848e-d08e-4c70-82e5-e2128cd5b8cd)=f1da31b60b1504441ccba0c29afd4040

注意每次调用都需要使用其实际POST请求内容和当时tick计算authorization值

二、接口

处理过程

（一）获取门列表

获取门禁系统中当前的门，此数据将作为资源用于人员权限指定

ü 请求数据

http://serverIp:port/itf/getDoorList

POST内容为空的JSON包，即{}

ü 返回数据

返回数据格式如下，其中操作成功code为0，其它为失败，msg为失败原因，id为设备标志，name为设备名称，dir为出入方向，取值为1进、2出、3进出。flag为设备标签，取值为face人脸机、door办公室、finger指纹机。

{"code":0,"msg":"操作成功","doors":[{"id":"5","name":"大门","dir":"1","flag":"face"},{"id":"6","name":"测试2号门","dir":"3","flag":"door"},{"id":"9","name":"测试2号门","dir":"2","flag":"finger"}]}

（二）新增人员

ü 请求数据

http://serverIp:port/itf/addMan

POST内容为

{"name":"张三","id":"NO.00025","recType":"staff","headImage":"图片BASE64编码后的字符串","extInfo":""}

其中name为姓名，id为工号或者其它唯一编号，recType取值为staff或tempStaff或customer，headImage为人脸图片的BASE64编码后的字符串,extInfo为扩展信息，可选，不存在或者填空字符串都可以。

ü 返回数据

返回数据格式如下，其中操作成功code为0，其它为失败，msg为失败原因

{"code":0,"msg":"操作成功"}

（三）删除人员

ü 请求数据

http://serverIp:port/itf/deleteMan

POST内容为

{"id":"NO.00025"}

id为工号或者其它唯一编号

ü 返回数据

返回数据格式如下，其中操作成功code为0，其它为失败，msg为失败原因

{"code":0,"msg":"操作成功"}

（四）更新人员

ü 请求数据

http://serverIp:port/itf/updateMan

POST内容为

{"name":"张三","id":"NO.00025","recType":"staff","headImage":"图片BASE64编码后的字符串","extInfo":""}

其中name为姓名，id为工号或者其它唯一编号，recType取值为staff或tempStaff或customer，headImage为人脸图片的BASE64编码后的字符串。如果id对应的人员不存在则自动添加新人员。extInfo为扩展信息，可选，不存在或者填空字符串都可以。

ü 返回数据

返回数据格式如下，其中操作成功code为0，其它为失败，msg为失败原因

{"code":0,"msg":"操作成功"}

（五）重新触发人员授权（更新人员记录的修改时间）

ü 请求数据

http://serverIp:port/itf/updateManModTime

POST内容为

{"id":"NO.00025"}

其中id为工号或者其它唯一编号，更新此id对应的人员的修改时间，即保持原数据不变的情况下，让门禁系统以为人员更新了，因此触发人员的所有权限记录被重新被处理。

ü 返回数据

返回数据格式如下，其中操作成功code为0，其它为失败，msg为失败原因

{"code":0,"msg":"操作成功"}

（六）获取人员列表

ü 请求数据

http://serverIp:port/itf/getManList

POST内容为

{"name":"张三","id":"NO.00025","recType":"staff"}

使用姓名、编号、人员类型条件获取人员列表，当姓名或编号或人员类型参数为空字符串时表示不匹配此参数

ü 返回数据

返回数据格式如下，其中操作成功code为0，其它为失败，msg为失败原因，mans为人员列表，其中recType取值为staff表示员工、tempStaff表示临时人员、customer表示客户。

{"code":0,"msg":"操作成功","mans":[{"id":"NO.00025","name":"张三","recType":"staff"},{"id":"NO.00026","name":"李四","recType":"staff"}]}

（七）获取图片无效的人员列表

ü 请求数据

http://serverIp:port/itf/getInvalidImageManList

POST内容为空的JSON包，即{}

ü 返回数据

{"code":0,"msg":"操作成功","mans":[{"id":"NO.00025","name":"张三","recType":"staff"},{"id":"NO.00026","name":"李四","recType":"staff"}]}

（八）新增人员可访问门列表（内部直接存储）

ü 请求数据

http://serverIp:port/itf/addAccessRight

POST内容为

{"id":"NO.00025","doors":"3;5","times":"0","beginTime":"2021-07-06 00:00:00","endTime":"2021-07-06 23:59:59","deleteOld":"0"}

其中id为工号或者其它唯一编号，doors为以小写分号分隔的可访问门列表，times取值为0表示长期可出入，为1表示只可出入一次。beginTime和endTime表示权限记录生效和失败时间。deleteOld为可选参数，表示添加操作前先删除当前人员当前门的旧权限，默认为“0”。注意，对于使用addAccessRight添加的多门权限，调用addAccessRightEx并指定deleteOld参数时，只会删除人员旧的单门权限并新增当前请求参数指定的权限，原来的多门权限不能自动删除。

ü 返回数据

返回数据格式如下，其中操作成功code为0，其它为失败，msg为失败原因

{"code":0,"msg":"操作成功"}

（九）新增人员可访问门列表（内部拆分门）

http://serverIp:port/itf/addAccessRightEx

ü 请求数据

参数和返回值与addAccessRight完全一样，但此接口内部会将权限按门拆分后保存。相当于按每门多次调用addAccessRight。

ü 返回数据

参数和返回值与addAccessRight完全一样，但此接口内部会将权限按门拆分后保存。相当于按每门多次调用addAccessRight。

注意：使用此接口添加多门记录后，不能使用原请求参数（多门一起）删除，只能逐个门调用来进行删除（其它参数保持添加参数一致），或者通过查询接口getAccessRightList获取记录的recId，通过调用deleteAccessRightByRecId接口删除。

（十）删除人员可访问门列表（按新增接口原参数）

ü 请求数据

http://serverIp:port/itf/deleteAccessRight

POST内容为

{"id":"NO.00025","doors":"3;5","times":"0","beginTime":"2021-07-06 00:00:00","endTime":"2021-07-06 23:59:59"}

其中id为工号或者其它唯一编号，doors为以小写分号分隔的可访问门列表，times取值为0表示长期可出入，为1表示只可出入一次。beginTime和endTime表示权限记录生效和失败时间。

注意：使用addAccessRight添加一条包含多个门的记录后，不能使用本接口指定删除其中一个或者部分门，只能使用与请求参数一致的参数删除整个权限记录。对于需要逐门控制的，需要在添加时就按单个门进行调用或者使用addAccessRightEx接口新增。

ü 返回数据

返回数据格式如下，其中操作成功code为0，其它为失败，msg为失败原因

{"code":0,"msg":"操作成功"}

（十一）删除人员全部可访问门列表

ü 请求数据

http://serverIp:port/itf/deleteAccessRightAll

POST内容为

{"id":"NO.00025"}

其中id为工号或者其它唯一编号。

ü 返回数据

返回数据格式如下，其中操作成功code为0，其它为失败，msg为失败原因

{"code":0,"msg":"操作成功"}

（十二）删除人员可访问门列表(按recId)

ü 请求数据

http://serverIp:port/itf/deleteAccessRightByRecId

POST内容为

{"recId":"5"}

其中recId为记录标志，可从获取人员可访问门列表接口得到。

ü 返回数据

返回数据格式如下，其中操作成功code为0，其它为失败，msg为失败原因

{"code":0,"msg":"操作成功"}

（十三）获取人员可访问门列表

ü 请求数据

http://serverIp:port/itf/getAccessRightList

POST内容为

{"id":"NO.00025"}

Id为人员编号

ü 返回数据

返回数据格式如下，其中操作成功code为0，其它为失败，msg为失败原因，rights为权限列表（其中recId为记录标志可用于按标志删除，state为记录状态，取值为

new表示新权限记录未处理

wait表示等待生效时间到

ready表示已经进入有效期但未选中生效（比如2条都有效但只选了其中一条下发）

work表示生效中

failed生效，但实际下发授权失败，系统会自动重新尝试

expired表示过期

deleted表示记录被标记删除。其它字段参考新增人员可访问列表接口说明）

{"code":0,"msg":"操作成功","rights":[{"recId":"1","id":"NO.00025","doors":"3;5","times":"0","beginTime":"2021-07-06 00:00:00","endTime":"2021-07-06 23:59:59","state":"new"},{"recId":"2","id":"NO.00026","doors":"2;5","times":"0","beginTime":"2021-07-06 00:00:00","endTime":"2021-07-06 23:59:59","state":"work"}]}

（十四）获取授权失败的人员可访问门列表

ü 请求数据

http://serverIp:port/itf/getFailedAccessRightList

POST内容为{}，表示查询门禁系统授权失败的记录。

如果指定参数state，则查询指定状态的记录。如{"state":"work"}查询已经生效的。

ü 返回数据

new表示新权限记录未处理

wait表示等待生效时间到

ready表示已经进入有效期但未选中生效（比如2条都有效但只选了其中一条下发）

work表示生效中

failed生效，但实际下发授权失败，系统会自动重新尝试

expired表示过期

deleted表示记录被标记删除。其它字段参考新增人员可访问列表接口说明）

{"code":0,"msg":"操作成功","rights":[{"recId":"1","id":"NO.00025","doors":"3;5","times":"0","beginTime":"2021-07-06 00:00:00","endTime":"2021-07-06 23:59:59","state":"failed"},{"recId":"2","id":"NO.00026","doors":"2;5","times":"0","beginTime":"2021-07-06 00:00:00","endTime":"2021-07-06 23:59:59","state":"failed"}]}

（十五）获取人员进出记录

ü 请求数据

http://serverIp:port/itf/getAccessLogList

POST内容为

{"id":"NO.00025","beginTime":"2020-01-01 00:00:00","endTime":"2021-01-01 23:59:59","needImage":"1"}

id为人员编号，beginTime,endTime为查询起止时间。needImage表示是否返回图片数据。对于记录及图片数据量大或者无法预测数据量的情况，可以尝试先限定一个较小的时间范围取回不带图像的记录，再逐记录取图像。未指定needImage时默认为1表示需要图像。

ü 返回数据

返回数据格式如下，其中操作成功code为0，其它为失败，msg为失败原因，logs为日志列表

{"code":0,"msg":"操作成功","logs":[{"recId":"23415","id":"NO.00025","name"："张三"，"door":"3","time":"2021-07-06 08:03:00","dir":"1","image":"base64编码的抓拍图片"},{"recId":"23416","id":"NO.00025","name"："张三"，"door":"5","time":"2021-07-06 18:05:00","dir":"1","image":"base64编码的抓拍图片"}]}

其中recId为记录唯一标志，仅用于调试。id为人员标志，name为人员姓名，door为门标志，time为发生时间，dir为方向，1进2出。Image为BASE64编码的抓拍图片。

（十六）远程开门

ü 请求数据

http://serverIp:port/itf/openDoor

POST内容为

{"id":"3"}

其中

id为门号

ü 返回数据

返回数据格式如下，其中操作成功code为0，其它为失败，msg为失败原因

{"code":0,"msg":"操作成功"}