內(nèi)蒙古建筑業(yè)從業(yè)人員實(shí)名制管理服務(wù)信息平臺(tái)（V2.0）考勤設(shè)備通用集成接口方案

附件1內(nèi)蒙古自治區(qū)建筑業(yè)從業(yè)人員實(shí)名制管理服務(wù)信息平臺(tái)（V2.0）考勤設(shè)備通用集成接口方案集成總體業(yè)務(wù)流程向?qū)嵜破脚_(tái)（V2.0）https整。API調(diào)用說明Https接口規(guī)范拼裝一個(gè)正確的URL，通過HTTPS請(qǐng)求到實(shí)名制平臺(tái)（V2.0）接口。調(diào)用原理示意圖如下。URL地址https://域名:端口/function?輸入?yún)?shù)1=xx&輸入?yún)?shù)2=xxEncodingUTF-8MethodPOSTBodyJSON數(shù)據(jù)返回JSON數(shù)據(jù)調(diào)用API，必須傳入輸入?yún)?shù)和應(yīng)用參數(shù)（POST的BODY數(shù)據(jù)）。參數(shù)類型參數(shù)使用說明輸入?yún)?shù)輸入?yún)?shù)放在url參數(shù)區(qū)，即？后的參數(shù)，例如https://域名:端口/function?token=xx中的token應(yīng)用參數(shù)應(yīng)用參數(shù)放在POST的body數(shù)據(jù)區(qū)（signature）signature（POSTBODY及平apisecretMD5bodybody{}，body{body示例簽名步驟：示例簽名步驟：所有參數(shù)為：token=testtimestamp=2018-06-1009:05:03應(yīng)用參數(shù)：body體里無參數(shù)時(shí)為{}（body體里有參數(shù)時(shí)示例{”license”:”xxxxxxxxxxxx”}）連接組合字符串連接參數(shù)名與參數(shù)值，并在首尾加上隱含驗(yàn)簽因子連接參數(shù)名與參數(shù)值，并在首尾加上隱含驗(yàn)簽因子apisecret的值，示例值為secret123,組合字符串如下（采用body體里無參方式）：secret123tokentesttimestamp2018-06-1009:05:03body{}secret123UTF-8apisecret3）生成簽名（signature）：用通用MD5算法對(duì)組合字符串進(jìn)行加密，產(chǎn)生32位大寫MD5值注意事項(xiàng)所有的請(qǐng)求和響應(yīng)數(shù)據(jù)編碼皆為utf-8格式，url里的所有參數(shù)值請(qǐng)做urlencode編碼。（說明：三位錯(cuò)誤碼代表即時(shí)反饋，四位錯(cuò)誤碼為異步查詢結(jié)果）code結(jié)果200成功500系統(tǒng)異常511參數(shù)中存在必填字段為空101簽名錯(cuò)誤102非法時(shí)間戳，允許客戶端請(qǐng)求時(shí)間誤差6分鐘103請(qǐng)求體解析錯(cuò)誤104異步查詢錯(cuò)誤105通行時(shí)間沒到，或者過期106通行方式值有誤107體溫不在正常范圍內(nèi)35-42108超過一次最多拆查詢?nèi)藬?shù)（1000）109通行方向值有誤110token不存在或已失效111同一設(shè)備在多地請(qǐng)求112license或mac驗(yàn)證失敗114經(jīng)度參數(shù)不合法115緯度參數(shù)不合法1001未查到此設(shè)備數(shù)據(jù)1002設(shè)備未處于運(yùn)行狀態(tài)1003設(shè)備綁定的工程已竣工1004人員信息不存在1005人員不曾屬于該項(xiàng)目或單位或人員狀態(tài)為結(jié)束1006考勤記錄重復(fù)1007圖片Base64解碼失敗1008不允許同一人頻繁往同一方向上報(bào)考勤（一分鐘內(nèi)）API接口說明接口服務(wù)APIAPI接口名稱API描述/get-token獲取訪問令牌/get-time心跳維持/get-employees-hash獲取人員列表哈希/get-employees獲取人員列表信息/get-employees-details獲取人員信息/upload-attendance-record上傳考勤信息/get-upload-attendance-result考勤異步調(diào)用結(jié)果查詢/get-employee-idphoto獲取人員身份證圖片獲取令牌 應(yīng)用場(chǎng)景獲取訪問接口令牌，用于云服務(wù)的其他業(yè)務(wù)接口調(diào)用。要求：最快兩次請(qǐng)求間隔1分鐘。輸入?yún)?shù)名稱類型是否必須描述signatureStringY數(shù)據(jù)簽名應(yīng)用參數(shù)（POST的BODY數(shù)據(jù)）名稱類型是否必須描述macStringY考勤設(shè)備唯一maclicenseStringY授權(quán)賬號(hào)。由平臺(tái)下發(fā)請(qǐng)求url示例https://域名:端口/get-token?mac=xxx&signature=xx請(qǐng)求body示例https://域名:端口/get-token?mac=xxx&signature=xx請(qǐng)求body示例{"license":"ABC055ASQ9D8F7HY5","mac":"123"}返回的JSON數(shù)據(jù)名稱類型是否必須描述codeStringY平臺(tái)響應(yīng)碼，詳見返回碼一覽表messageStringY返回信息dataObjectY返回結(jié)果集成功返回的data結(jié)果集名稱類型是否必須描述tokenStringY服務(wù)器生成的通信訪問令牌，有效時(shí)長10分鐘。超過10分鐘token失效，需要重新獲取。left_timeIntY顯示通信令牌有效剩余時(shí)長（秒返回示例{"code":"00","message":"success","data":{"token":"F2F7A78A741D4N98AC0AB4DAB110PCC8","left_time":600}}獲取心跳 應(yīng)用場(chǎng)景獲取服務(wù)器系統(tǒng)時(shí)間，用于同步服務(wù)器時(shí)間云服務(wù)同時(shí)獲取當(dāng)前考勤設(shè)備的心跳。要求：最慢1小時(shí)同步一次，最快10分鐘同步一次。輸入?yún)?shù)名稱類型是否必須描述tokenStringY訪問令牌timestampStringYyyyy-MM-ddhh:mm:ss2022-10-0613:52:036signatureStringY數(shù)據(jù)簽名應(yīng)用參數(shù)（POST的BODY數(shù)據(jù)）名稱類型是否必須描述無請(qǐng)求url示例https://域名:端口/get-time?token=xxxx×tamp=xxx&signature=xxx請(qǐng)求body示例無返回的JSON數(shù)據(jù)名稱類型是否必須描述codeStringY平臺(tái)響應(yīng)碼，詳見返回碼一覽表messageStringY返回信息dataObjectY返回結(jié)果集成功返回的data結(jié)果集名稱類型是否必須描述sys_timeStringY（yyyy-MM-ddhh:mm:ss）返回示例{"code":"00","message":"success","data":{"sys_time":"2022-10-0613:52:03"}}獲取人員列表散列值 /get-employees-hash應(yīng)用場(chǎng)景獲取人員列表散列值，用于檢測(cè)人員是否需要更新。token30輸入?yún)?shù)名稱類型是否必須描述tokenStringY訪問令牌timestampStringYyyyy-MM-ddhh:mm:ss2016-06-0613:52:03。服務(wù)端允許客戶端請(qǐng)求時(shí)間誤差為6分鐘signatureStringY數(shù)據(jù)簽名應(yīng)用參數(shù)（POST的BODY數(shù)據(jù)）名稱類型是否必須描述無請(qǐng)求url示例https:// 域 名 : 端 口/get-employees-hash?token=xxxx×tamp=xxx&signature=xxx請(qǐng)求body示例無返回的JSON數(shù)據(jù)名稱類型是否必須描述codeStringY平臺(tái)響應(yīng)碼，詳見返回碼一覽表messageStringY返回信息dataObjectY返回結(jié)果集成功返回的data結(jié)果集名稱類型是否必須描述emp_countIntY人員數(shù)量sha1StringY人員列表的十六進(jìn)制小寫散列值返回示例{"code":"00","message":"success","data":{"emp_count":1,"sha1":"xxx"}}獲取人員列表信息 /get-employees應(yīng)用場(chǎng)景從實(shí)名制平臺(tái)（V2.0）獲取平臺(tái)工程人員列表信息，用于獲取人員列表。要求：兩次最快不低于30分鐘為間隔頻率，獲取人員散列列表值輸入?yún)?shù)名稱類型是否必須描述tokenStringY獲取令牌接口獲取timestampStringYyyyy-MM-ddhh:mm:ss2016-06-0613:52:03。服務(wù)端允許客戶端請(qǐng)求時(shí)間誤差為6分鐘signatureStringY數(shù)據(jù)簽名應(yīng)用參數(shù)（POST的BODY數(shù)據(jù)）名稱類型是否必須描述sha1StringY人員列表的十六進(jìn)制小寫散列值請(qǐng)求url示例https:// 域 名 : 端 口/get-employees?token=xxxx×tamp=xxx&signature=xxx請(qǐng)求body示例{"sha1":"abc055asq9d8f7hy5"}返回的JSON數(shù)據(jù)名稱類型是否必須描述codeStringY平臺(tái)響應(yīng)碼，詳見返回碼一覽表messageStringY返回信息dataObjectArrayY返回結(jié)果集成功返回的data結(jié)果集名稱類型是否必須描述idStringY員工idstateStringY工人狀態(tài)：presence：表示工人在場(chǎng)狀態(tài)；exit：表示工人離場(chǎng)狀態(tài)；通過此狀態(tài)可以增加或減少人員updated_atStringY,”yyyy-MM-ddhh:mm:ss.zzz”返回示例{"code":"00","message":"success","data":[{"id":"B06F9F20F70514B7E053020011AC70AA","updated_at":"2022-02-0110:10:10","state":"presence"}]}獲取人員信息 /get-employees-details應(yīng)用場(chǎng)景從實(shí)名制平臺(tái)（V2.0）獲取相應(yīng)人員列表中的人員信息。11000人，否則返回108錯(cuò)誤碼。輸入?yún)?shù)名稱類型是否必須描述tokenStringY訪問令牌timestampStringYyyyy-MM-ddhh:mm:ss2016-06-0613:52:03時(shí)間誤差為6分鐘signatureStringY數(shù)據(jù)簽名應(yīng)用參數(shù)（POST的BODY數(shù)據(jù)）名稱類型是否必須描述employee_listObjectArrayY人員信息數(shù)組idStringY員工id(僅在場(chǎng)狀態(tài)員工)請(qǐng)求url示例https:// 域 名 : 端 口/get-employees-details?token=xxx×tamp=xxx&signature=xxx請(qǐng)求body示例{"employee_list":[{"id":"1"},{"id":"2"}]}返回的JSON數(shù)據(jù)名稱類型是否必須描述codeStringY平臺(tái)響應(yīng)碼，詳見返回碼一覽表messageStringY返回信息dataObjectY返回結(jié)果集成功返回的data結(jié)果集名稱類型是否必須描述idStringY員工id（員工編號(hào)）nameStringY員工姓名sexStringY性別ageStringY人員年齡facephotoStringY員工采集照片的urlcompanyStringY所屬單位team_nameStringY班組名稱pass_periodStringY進(jìn) 場(chǎng) 時(shí) 間 ， 格 式y(tǒng)yyy-MM-dd:yyyy-MM-ddupdatedStringY修 改 時(shí) 間 ,”yyyy-MM-ddhh:mm:ss.zzz”categoryStringY人員類別work_typeStringY人員工種返回示例{"code":"00","message":"success","data":[{"id":"S6FF8GFH9G0JMXNB8DFSG","name":"張三","sex":"男","age":"28",\h"facephoto":"http://xxx/xxx.jpg","company":"中建一局","team_name":"木工組","pass_period":"2022-02-0110:10:10","updated_at":"2022-02-0110:10:10","category":"建筑工人","work_type":"木工"}]}上傳考勤信息 /upload-attendance-record應(yīng)用場(chǎng)景向?qū)嵜脚_(tái)發(fā)送工人考勤通行信息記錄。每次僅限一條通行記錄。1否則返回1008錯(cuò)誤碼。輸入?yún)?shù)名稱類型是否必須描述tokenStringY訪問令牌timestampStringYyyyy-MM-dd如：2016-06-0613:52:03。服務(wù)端允許客6鐘signatureStringY數(shù)據(jù)簽名應(yīng)用參數(shù)（POST的BODY數(shù)據(jù)）名稱類型是否必須描述person_idStringYid（獲取人員信息接口返回的員工編號(hào)）passed_timepassed_timeStringY通過考勤時(shí)間，格式：yyyy-MM-ddhh:mm:ssdirectionStringY通行方向（in/out）說明：in—進(jìn)，out—出wayStringY通行方式固定為1—人臉識(shí)別site_photoStringYBase64圖像底部帶過閘時(shí)間水印50Ksite_photo_hashStringY工地人臉考勤照片md5值longitudeStringN經(jīng)度latitudeStringN緯度temperatureStringN溫度請(qǐng)求url示例https:// 域 名 : 端 /post-attendance-record?token=xxx×tamp=xxx&signature=xxx請(qǐng)求body示例{"project_id":"B06F9F20F70514B7E053020011AC70AA","device_id":"88EE98ACB25D4365A9B8709F78F4F151","person_id":"50B7BBAE68C14A659D26F9B61FFEE28D","passed_time":"2017-03-2912:12:12","direction":"in","way":"1","site_photo":"xxxx","site_photo_hash":"xxxx"}返回的JSON數(shù)據(jù)名稱類型是否必須描述codeStringY平臺(tái)響應(yīng)碼，詳見返回碼一覽表messageStringY返回信息dataObjectY返回結(jié)果集，成功返回的data結(jié)果集名稱類型是否必須描述query_codeStringY異步查詢碼，有效時(shí)間1天，用于查詢上報(bào)考勤情況返回示例{"code":"00","message":"success","data":{"query_code":"B06F9F20F70514B7E053020011AC70AA"}}失敗返回的data結(jié)果集名稱類型是否必須描述無考勤異步調(diào)用結(jié)果查詢 /get-upload-attendance-result應(yīng)用場(chǎng)景通過考勤異步查詢碼查詢考勤反饋信息。要求：兩次最快不低于1分鐘為間隔頻率，查詢考勤上報(bào)結(jié)果輸入?yún)?shù)名稱類型是否必須描述tokenStringY訪問令牌timestampStringYyyyy-MM-ddhh:mm:ss2016-06-0613:52:03時(shí)間誤差為6分鐘signatureStringY數(shù)據(jù)簽名POST的JSON數(shù)據(jù)名稱類型是否必須描述query_codeStringY查詢碼，有效時(shí)間1天請(qǐng)求url示例https:// 域 名 : 端 口/get-upload-attendance-result?token=xxx×tamp=xxx&signature=xxx請(qǐng)求body示例{"query_code":"B06F9F20F70514B7E053020011AC70AA"}返回的JSON數(shù)據(jù)名稱類型是否必須描述codeStringY平臺(tái)響應(yīng)碼，詳見返回碼一覽表messageStringY返回信息dataObjectY返回結(jié)果集成功返回的data結(jié)果集名稱類型是否必須描述stateStringY任務(wù)狀態(tài)：completed：已完成；in-progress:進(jìn)行中；成功返回示例{"code":"200","message":"調(diào)用成功","data":{"state":"completed"}}失敗返回示例{"code":"1001","message":"錯(cuò)誤信息","data":{"state":"completed"}}獲取人員身份證圖片 /get-employees-idphoto應(yīng)用場(chǎng)景通過人員id獲取人員身份證圖片。1拉取1000人，否則返回108錯(cuò)誤碼。輸入?yún)?shù)名稱類型是否必須描述tokenStringY訪問令牌timestampStringYyyyy-MM-ddhh:mm:ss2016-06-0613:52:03時(shí)間誤差為6分鐘signatureStringY數(shù)據(jù)簽名應(yīng)用參數(shù)（POST的BODY數(shù)據(jù)）名稱類型是否必須描述employee_listObjectArrayY人員信息數(shù)組idStringY人員id請(qǐng)求url示例https:// 域 名 : 端 口 /get-employees-idphoto?token=xxx×tamp=xxx&signature=xxx請(qǐng)求body示例{"employee_list":[{"id":"xx"},{"id":"xx"}]}返回的JSON數(shù)據(jù)名稱類型是否必須描述codeStringY平臺(tái)響應(yīng)