門禁系統(tǒng)HTTP服務(wù)接口

一、約定

ü 使用HTTP協(xié)議，POST請求

ü 交互數(shù)據(jù)為utf8編碼的JSON數(shù)據(jù)，大小寫敏感。除了表示操作結(jié)果代碼的code為數(shù)字，其它字段默認(rèn)都盡量使用字符串類型。

ü 字符串時(shí)間格式為YYYY-MM-DD HH:MI:SS 24小時(shí)制，時(shí)間從1970-01-01 00:00:00開始

ü 圖片采用jpg格式，數(shù)據(jù)經(jīng)BASE64編碼后傳輸，編碼后的字符串應(yīng)該只有原始數(shù)據(jù)，不能包含特定應(yīng)用專用的標(biāo)記，不能包含為了美觀以及易讀而加入的回車換行符

正確內(nèi)容 /9j/4AAQSkZJRgABAQEAYABgA...

錯(cuò)誤內(nèi)容 data:image/jpg;base64,/9j/4AAQSkZJRgABAQEAYABgA...

ü 加密密鑰key約定為506a848e-d08e-4c70-82e5-xxxxxxxxxxxx

ü 請求Header中添加tick，值為當(dāng)前時(shí)間戳，1970年到當(dāng)前的秒數(shù)，如1626485104

ü 請求Header中添加authorization，值為POST請求內(nèi)容使用&號連接上時(shí)間戳，再使用&號連接上加密密鑰key后的字符串，做md5計(jì)算出來的32位小寫md5值。

舉例，如果POST請求的JSON內(nèi)容為{"id":"NO.00025"}

tick為1626485104，則計(jì)算authorization

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

注意每次調(diào)用都需要使用其實(shí)際POST請求內(nèi)容和當(dāng)時(shí)tick計(jì)算authorization值

二、接口

處理過程

 

（一）獲取門列表

獲取門禁系統(tǒng)中當(dāng)前的門，此數(shù)據(jù)將作為資源用于人員權(quán)限指定

ü 請求數(shù)據(jù)

http://serverIp:port/itf/getDoorList

POST內(nèi)容為空的JSON包，即{}

ü 返回?cái)?shù)據(jù)

返回?cái)?shù)據(jù)格式如下，其中操作成功code為0，其它為失敗，msg為失敗原因，id為設(shè)備標(biāo)志，name為設(shè)備名稱，dir為出入方向，取值為1進(jìn)、2出、3進(jìn)出。flag為設(shè)備標(biāo)簽，取值為face人臉機(jī)、door辦公室、finger指紋機(jī)。

{"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"}]}

（二）新增人員

ü 請求數(shù)據(jù)

http://serverIp:port/itf/addMan

POST內(nèi)容為

{"name":"張三","id":"NO.00025","recType":"staff","headImage":"圖片BASE64編碼后的字符串","extInfo":""}

其中name為姓名，id為工號或者其它唯一編號，recType取值為staff或tempStaff或customer，headImage為人臉圖片的BASE64編碼后的字符串,extInfo為擴(kuò)展信息，可選，不存在或者填空字符串都可以。

ü 返回?cái)?shù)據(jù)

返回?cái)?shù)據(jù)格式如下，其中操作成功code為0，其它為失敗，msg為失敗原因

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

（三）刪除人員

ü 請求數(shù)據(jù)

http://serverIp:port/itf/deleteMan

POST內(nèi)容為

{"id":"NO.00025"}

id為工號或者其它唯一編號

ü 返回?cái)?shù)據(jù)

返回?cái)?shù)據(jù)格式如下，其中操作成功code為0，其它為失敗，msg為失敗原因

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

 

（四）更新人員

ü 請求數(shù)據(jù)

http://serverIp:port/itf/updateMan

POST內(nèi)容為

{"name":"張三","id":"NO.00025","recType":"staff","headImage":"圖片BASE64編碼后的字符串","extInfo":""}

其中name為姓名，id為工號或者其它唯一編號，recType取值為staff或tempStaff或customer，headImage為人臉圖片的BASE64編碼后的字符串。如果id對應(yīng)的人員不存在則自動(dòng)添加新人員。extInfo為擴(kuò)展信息，可選，不存在或者填空字符串都可以。

ü 返回?cái)?shù)據(jù)

返回?cái)?shù)據(jù)格式如下，其中操作成功code為0，其它為失敗，msg為失敗原因

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

（五）重新觸發(fā)人員授權(quán)（更新人員記錄的修改時(shí)間）

ü 請求數(shù)據(jù)

http://serverIp:port/itf/updateManModTime

POST內(nèi)容為

{"id":"NO.00025"}

其中id為工號或者其它唯一編號，更新此id對應(yīng)的人員的修改時(shí)間，即保持原數(shù)據(jù)不變的情況下，讓門禁系統(tǒng)以為人員更新了，因此觸發(fā)人員的所有權(quán)限記錄被重新被處理。

ü 返回?cái)?shù)據(jù)

返回?cái)?shù)據(jù)格式如下，其中操作成功code為0，其它為失敗，msg為失敗原因

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

（六）獲取人員列表

ü 請求數(shù)據(jù)

http://serverIp:port/itf/getManList

POST內(nèi)容為

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

使用姓名、編號、人員類型條件獲取人員列表，當(dāng)姓名或編號或人員類型參數(shù)為空字符串時(shí)表示不匹配此參數(shù)

ü 返回?cái)?shù)據(jù)

返回?cái)?shù)據(jù)格式如下，其中操作成功code為0，其它為失敗，msg為失敗原因，mans為人員列表，其中recType取值為staff表示員工、tempStaff表示臨時(shí)人員、customer表示客戶。

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

（七）獲取圖片無效的人員列表

ü 請求數(shù)據(jù)

http://serverIp:port/itf/getInvalidImageManList

POST內(nèi)容為空的JSON包，即{}

ü 返回?cái)?shù)據(jù)

返回?cái)?shù)據(jù)格式如下，其中操作成功code為0，其它為失敗，msg為失敗原因，mans為人員列表，其中recType取值為staff表示員工、tempStaff表示臨時(shí)人員、customer表示客戶。

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

 

（八）新增人員可訪問門列表（內(nèi)部直接存儲(chǔ)）

ü 請求數(shù)據(jù)

http://serverIp:port/itf/addAccessRight

POST內(nèi)容為

{"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表示權(quán)限記錄生效和失敗時(shí)間。deleteOld為可選參數(shù)，表示添加操作前先刪除當(dāng)前人員當(dāng)前門的舊權(quán)限，默認(rèn)為“0”。注意，對于使用addAccessRight添加的多門權(quán)限，調(diào)用addAccessRightEx并指定deleteOld參數(shù)時(shí)，只會(huì)刪除人員舊的單門權(quán)限并新增當(dāng)前請求參數(shù)指定的權(quán)限，原來的多門權(quán)限不能自動(dòng)刪除。

ü 返回?cái)?shù)據(jù)

返回?cái)?shù)據(jù)格式如下，其中操作成功code為0，其它為失敗，msg為失敗原因

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

（九）新增人員可訪問門列表（內(nèi)部拆分門）

http://serverIp:port/itf/addAccessRightEx

ü 請求數(shù)據(jù)

參數(shù)和返回值與addAccessRight完全一樣，但此接口 內(nèi)部會(huì)將權(quán)限按門拆分后保存。相當(dāng)于按每門多次調(diào)用addAccessRight。

ü 返回?cái)?shù)據(jù)

參數(shù)和返回值與addAccessRight完全一樣，但此接口 內(nèi)部會(huì)將權(quán)限按門拆分后保存。相當(dāng)于按每門多次調(diào)用addAccessRight。

注意：使用此接口添加多門記錄后，不能使用原請求參數(shù)（多門一起）刪除，只能逐個(gè)門調(diào)用來進(jìn)行刪除（其它參數(shù)保持添加參數(shù)一致），或者通過查詢接口getAccessRightList獲取記錄的recId，通過調(diào)用deleteAccessRightByRecId接口刪除。

 

（十）刪除人員可訪問門列表（按新增接口原參數(shù)）

ü 請求數(shù)據(jù)

http://serverIp:port/itf/deleteAccessRight

POST內(nèi)容為

{"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表示權(quán)限記錄生效和失敗時(shí)間。

注意：使用addAccessRight添加一條包含多個(gè)門的記錄后，不能使用本接口指定刪除其中一個(gè)或者部分門，只能使用與請求參數(shù)一致的參數(shù)刪除整個(gè)權(quán)限記錄。對于需要逐門控制的，需要在添加時(shí)就按單個(gè)門進(jìn)行調(diào)用或者使用addAccessRightEx接口新增。

ü 返回?cái)?shù)據(jù)

返回?cái)?shù)據(jù)格式如下，其中操作成功code為0，其它為失敗，msg為失敗原因

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

（十一）刪除人員全部可訪問門列表

ü 請求數(shù)據(jù)

http://serverIp:port/itf/deleteAccessRightAll

POST內(nèi)容為

{"id":"NO.00025"}

其中id為工號或者其它唯一編號。

ü 返回?cái)?shù)據(jù)

返回?cái)?shù)據(jù)格式如下，其中操作成功code為0，其它為失敗，msg為失敗原因

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

（十二）刪除人員可訪問門列表(按recId)

ü 請求數(shù)據(jù)

http://serverIp:port/itf/deleteAccessRightByRecId

POST內(nèi)容為

{"recId":"5"}

其中recId為記錄標(biāo)志，可從獲取人員可訪問門列表接口得到。

ü 返回?cái)?shù)據(jù)

返回?cái)?shù)據(jù)格式如下，其中操作成功code為0，其它為失敗，msg為失敗原因

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

 

 

（十三）獲取人員可訪問門列表

ü 請求數(shù)據(jù)

http://serverIp:port/itf/getAccessRightList

POST內(nèi)容為

{"id":"NO.00025"}

Id為人員編號

ü 返回?cái)?shù)據(jù)

返回?cái)?shù)據(jù)格式如下，其中操作成功code為0，其它為失敗，msg為失敗原因，rights為權(quán)限列表（其中recId為記錄標(biāo)志可用于按標(biāo)志刪除，state為記錄狀態(tài)，取值為

new表示新權(quán)限記錄未處理

wait表示等待生效時(shí)間到

ready表示已經(jīng)進(jìn)入有效期但未選中生效（比如2條都有效但只選了其中一條下發(fā)）

work表示生效中

failed生效，但實(shí)際下發(fā)授權(quán)失敗，系統(tǒng)會(huì)自動(dòng)重新嘗試

expired表示過期

deleted表示記錄被標(biāo)記刪除。其它字段參考新增人員可訪問列表接口說明）

{"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"}]}

（十四）獲取授權(quán)失敗的人員可訪問門列表

ü 請求數(shù)據(jù)

http://serverIp:port/itf/getFailedAccessRightList

POST內(nèi)容為{}，表示查詢門禁系統(tǒng)授權(quán)失敗的記錄。

如果指定參數(shù)state，則查詢指定狀態(tài)的記錄。如{"state":"work"}查詢已經(jīng)生效的。

ü 返回?cái)?shù)據(jù)

返回?cái)?shù)據(jù)格式如下，其中操作成功code為0，其它為失敗，msg為失敗原因，rights為權(quán)限列表（其中recId為記錄標(biāo)志可用于按標(biāo)志刪除，state為記錄狀態(tài)，取值為

new表示新權(quán)限記錄未處理

wait表示等待生效時(shí)間到

ready表示已經(jīng)進(jìn)入有效期但未選中生效（比如2條都有效但只選了其中一條下發(fā)）

work表示生效中

failed生效，但實(shí)際下發(fā)授權(quán)失敗，系統(tǒng)會(huì)自動(dòng)重新嘗試

expired表示過期

deleted表示記錄被標(biāo)記刪除。其它字段參考新增人員可訪問列表接口說明）

{"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"}]}

 

（十五）獲取人員進(jìn)出記錄

ü 請求數(shù)據(jù)

http://serverIp:port/itf/getAccessLogList

POST內(nèi)容為

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

id為人員編號，beginTime,endTime為查詢起止時(shí)間。needImage表示是否返回圖片數(shù)據(jù)。對于記錄及圖片數(shù)據(jù)量大或者無法預(yù)測數(shù)據(jù)量的情況，可以嘗試先限定一個(gè)較小的時(shí)間范圍取回不帶圖像的記錄，再逐記錄取圖像。未指定needImage時(shí)默認(rèn)為1表示需要圖像。

ü 返回?cái)?shù)據(jù)

返回?cái)?shù)據(jù)格式如下，其中操作成功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為記錄唯一標(biāo)志，僅用于調(diào)試。id為人員標(biāo)志，name為人員姓名，door為門標(biāo)志，time為發(fā)生時(shí)間，dir為方向，1進(jìn)2出。Image為BASE64編碼的抓拍圖片。

（十六）遠(yuǎn)程開門

ü 請求數(shù)據(jù)

http://serverIp:port/itf/openDoor

POST內(nèi)容為

{"id":"3"}

其中

id為門號

ü 返回?cái)?shù)據(jù)

返回?cái)?shù)據(jù)格式如下，其中操作成功code為0，其它為失敗，msg為失敗原因

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