门禁系统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为人员列表,其中recType取值为staff表示员工、tempStaff表示临时人员、customer表示客户。

{"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"}查询已经生效的。

ü 返回数据

返回数据格式如下,其中操作成功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":"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":"操作成功"}