湛江市建筑工人管理服务信息平台

数据对接接口标准湛江市建筑业协会目录一、对接流程1二、请求说明2三、加密说明21.
JWT传输加密22.
DES敏感加密2三、接口说明31.
获取Token32.
新增班组33.
修改班组54.
新增人员75.
修改人员96.
人员进/退场117.
绑定设备118.
解绑设备12四、硬件通讯标准131.
建立连接142.
获取注册信息153.
添加人员164.
添加人员人脸库185.
上报考勤数据19五、职位字典20六、银行字典21一、对接流程需要对接的第三方平台,需要首先联系湛江市建筑工人管理服务信息平台开发商(以下简称:平台开发商)申请测试地址、第三方平台接入身份识别测试码、测试项目接入编号和测试项目接入秘钥.
最后由平台开发商评估第三方平台接入的测试结果.
认证第三方平台对接成功后,将会对第三方平台分发一个唯一的第三方平台接入身份识别码.
至此,第三方平台即可正常与湛江市建筑工人管理服务信息平台的生产环境正常进行数据交互.

正式项目对接时,项目需向平台开发商进行项目报备,申请项目唯一的接入编号和唯一的接入秘钥.
第三方平台即可凭借第三方平台的接入身份识别码、项目接入编号和项目接入秘钥上报项目的数据至湛江市建筑工人管理服务信息平台.

二、请求说明湛江市建筑工人管理服务信息平台接口满足RESTful约束条件和原则.
每次请求需要率先获取Token,获取到的Token需在每次操作时附加在RequestHeader的x-access-token中.
敏感的信息数据,则需要使用DES加密规则加密.
最后传输时需要使用JWT加密技术对传输的参数进行加密.
湛江市建筑工人管理服务信息平台一般情况下只会接收两个参数,第一个参数为名为"jwt",第二个名为"_method".

三、加密说明1.
JWT传输加密functiongenJwt(params){params.
iss=UUID();//UUID()方法自行实现,例子:b4893a57-8f85-41c6-993e-a16be26fac11params.
issType='api';params.
appType='api';letjwtHeader="{\"typ\":\"JWT\",\"alg\":\"SHA256\"}";letjwtHeaderBase64=Base64.
encode(jwtHeader);letjwtPayLoadBase64=Base64.
encode(JSON.
stringify(params));letsignature=sha256(jwtHeaderBase64+".
"+jwtPayLoadBase64);Letjwt=encodeURIComponent(jwtHeaderBase64)encodeURIComponent(jwtPayLoadBase64)encodeURIComponent(signature);returnjwt;}2.
DES敏感加密使用DES加密,加密key等于接入密钥,加密后的字节码转为16进制编码的字符串,并在密文字符串的前面加"des:"前缀.

算法:密文="des:"+HEX(DES(idcard,key)),如:身份证号:5113011990010181111,接入密钥:8c2da4c769828fcfa77aedb690999cf9,密文:des:80cfe03525bb2b8d43d62ff369e95334cd1facfe4bbb800c需要使用DES敏感加密的地方本文会特别说明.
三、接口说明1.
获取Token接口说明接口描述获取Token请求地址/api/token请求方法POST备注每个Token服务器保留48小时,过期服务器返回802,x-access-token为空请求参数参数必须类型与长度注解备注accessNoYvarchar(32)第三方接入平台身份识别码projAcessNoYvarchar(32)项目接入编号projKeyYvarchar(32)项目接入密钥响应参数参数必须注解备注responeCodeY响应Code200为成功,其它为失败,失败原因具体可看responeMessageresponeMessageY响应MessageresponseResultY响应Result得到获取的Token2.
新增班组接口说明接口描述新增班组请求地址/api/team/create请求方法PUT备注请求参数参数必须类型与长度注解备注nameYvarchar(32)班组名称workTypeYvarchar(32)班组类型leaderAppointmentYvarchar(32)班组长证明书leaderIdcardYvarchar(18)工人身份证号DES加密leaderNameYvarchar(24)工人姓名leaderSexYtinyint(1)性别1:男2:女leaderNationYvarchar(32)民族leaderBirthdayYvarchar(10)生日格式:yyyy-MM-ddleaderAddressYvarchar(256)住址leaderSignOrganYvarchar(256)签发机关leaderExpiryStartYvarchar(10)有效期开始日期格式:yyyy-MM-ddleaderExpiryEndYvarchar(10)有效期结束日期格式:yyyy-MM-ddleaderHeadImgYvarchar(256)身份证头像URLleaderIdcardFrontYvarchar(256)身份证正面照URLleaderIdcardBackYvarchar(256)身份证反面照URLleaderCurrentAddressYvarchar(256)常住地址leaderPoliticalYtinyint(1)政治面貌1:党员2:团员3:群众leaderEducationYtinyint(1)文化程度1:本科及以上2:大专3:中专4:高中5:初中6:小学及以下leaderPhoneYvarchar(11)手机号DES加密leaderContractCodeYvarchar(256)合同编号leaderContractFileYvarchar(256)合同URLleaderCardNumYvarchar(256)工资卡账号DES加密leaderCardBankYvarchar(10)工资卡开户行代码参照银行字典leaderWorkTypeYvarchar(10)工种代码参照职位字典leaderSecurityCodeYvarchar(18)社保号DES加密leaderSafetyEduYtinyint(1)是否参加安全教育1:参加2:未参加leaderSafetyEduImgN安全教育图片URL参加了安全培训则为必须leaderDoDateY进场日期格式:yyyy-MM-dd响应参数参数必须注解备注responeCodeY响应Code200为成功,其它为失败,失败原因具体可看responeMessageresponeMessageY响应MessageresponseResultY响应Result得到teamId,修改时必须使用到3.
修改班组接口说明接口描述新增班组请求地址/api/team/update/{teamId}请求方法PUT备注请求参数参数必须类型与长度注解备注nameYvarchar(32)班组名称workTypeYvarchar(32)班组类型leaderAppointmentYvarchar(32)班组长证明书leaderIdcardYvarchar(18)工人身份证号DES加密leaderNameYvarchar(24)工人姓名leaderSexYtinyint(1)性别1:男2:女leaderNationYvarchar(32)民族leaderBirthdayYvarchar(10)生日格式:yyyy-MM-ddleaderAddressYvarchar(256)住址leaderSignOrganYvarchar(256)签发机关leaderExpiryStartYvarchar(10)有效期开始日期格式:yyyy-MM-ddleaderExpiryEndYvarchar(10)有效期结束日期格式:yyyy-MM-ddleaderHeadImgYvarchar(256)身份证头像URLleaderIdcardFrontYvarchar(256)身份证正面照URLleaderIdcardBackYvarchar(256)身份证反面照URLleaderCurrentAddressYvarchar(256)常住地址leaderPoliticalYtinyint(1)政治面貌1:党员2:团员3:群众leaderEducationYtinyint(1)文化程度1:本科及以上2:大专3:中专4:高中5:初中6:小学及以下leaderPhoneYvarchar(11)手机号DES加密leaderContractCodeYvarchar(256)合同编号leaderContractFileYvarchar(256)合同URLleaderCardNumYvarchar(256)工资卡账号DES加密leaderCardBankYvarchar(10)工资卡开户行代码参照银行字典leaderWorkTypeYvarchar(10)工种代码参照职位字典leaderSecurityCodeYvarchar(18)社保号DES加密leaderSafetyEduYtinyint(1)是否参加安全教育1:参加2:未参加leaderSafetyEduImgNvarchar(256)安全教育图片URL参加了安全培训则为必须leaderDoDateYvarchar(10)进场日期格式:yyyy-MM-dd响应参数参数必须注解备注responeCodeY响应Code200为成功,其它为失败,失败原因具体可看responeMessageresponeMessageY响应MessageresponseResultY响应Result4.
新增人员接口说明接口描述新增人员请求地址/api/per/create请求方法PUT备注请求参数参数必须类型与长度注解备注teamIdNvarchar(60)班组ID人员工种代码为管理人员时无需填写,为工人时必须填写idcardYvarchar(18)工人身份证号DES加密nameYvarchar(24)工人姓名sexYtinyint(1)性别1:男2:女nationYvarchar(32)民族birthdayYvarchar(10)生日格式:yyyy-MM-ddaddressYvarchar(256)住址signOrganYvarchar(256)签发机关expiryStartYvarchar(10)有效期开始日期格式:yyyy-MM-ddexpiryEndYvarchar(10)有效期结束日期格式:yyyy-MM-ddheadImgYvarchar(256)身份证头像URLidcardFrontYvarchar(256)身份证正面照URLidcardBackYvarchar(256)身份证反面照URLcurrentAddressYvarchar(256)常住地址politicalYtinyint(1)政治面貌1:党员2:团员3:群众educationYtinyint(1)文化程度1:本科及以上2:大专3:中专4:高中5:初中6:小学及以下phoneYvarchar(11)手机号DES加密contractCodeYvarchar(256)合同编号contractFileYvarchar(256)合同URLcardNumYvarchar(256)工资卡账号DES加密cardBankYvarchar(10)工资卡开户行代码参照银行字典workTypeYvarchar(10)工种代码参照职位字典securityCodeYvarchar(18)社保号DES加密safetyEduYtinyint(1)是否参加安全教育1:参加2:未参加safetyEduImgNvarchar(256)安全教育图片URL参加了安全培训则为必须doDateYvarchar(10)进场日期格式:yyyy-MM-dd响应参数参数必须注解备注responeCodeY响应Code200为成功,其它为失败,失败原因具体可看responeMessageresponeMessageY响应MessageresponseResultY响应Result得到perId,修改时必须使用到5.
修改人员接口说明接口描述新增人员请求地址/api/per/update/{perId}请求方法PUT备注请求参数参数必须类型与长度注解备注teamIdNvarchar(60)班组ID人员工种代码为管理人员时无需填写,为工人时必须填写idcardYvarchar(18)工人身份证号DES加密nameYvarchar(24)工人姓名sexYtinyint(1)性别1:男2:女nationYvarchar(32)民族birthdayYvarchar(10)生日格式:yyyy-MM-ddaddressYvarchar(256)住址signOrganYvarchar(256)签发机关expiryStartYvarchar(10)有效期开始日期格式:yyyy-MM-ddexpiryEndYvarchar(10)有效期结束日期格式:yyyy-MM-ddheadImgYvarchar(256)身份证头像URLidcardFrontYvarchar(256)身份证正面照URLidcardBackYvarchar(256)身份证反面照URLcurrentAddressYvarchar(256)常住地址politicalYtinyint(1)政治面貌1:党员2:团员3:群众educationYtinyint(1)文化程度1:本科及以上2:大专3:中专4:高中5:初中6:小学及以下phoneYvarchar(11)手机号DES加密contractCodeYvarchar(256)合同编号contractFileYvarchar(256)合同URLcardNumYvarchar(256)工资卡账号DES加密cardBankYvarchar(10)工资卡开户行代码参照银行字典workTypeYvarchar(10)工种代码参照职位字典securityCodeYvarchar(18)社保号DES加密safetyEduYtinyint(1)是否参加安全教育1:参加2:未参加safetyEduImgNvarchar(256)安全教育图片URL参加了安全培训则为必须doDateYvarchar(10)进场日期格式:yyyy-MM-dd响应参数参数必须注解备注responeCodeY响应Code200为成功,其它为失败,失败原因具体可看responeMessageresponeMessageY响应MessageresponseResultY响应Result6.
人员进/退场接口说明接口描述人员进/退场请求地址/api/per/status请求方法POST备注请求参数参数必须类型与长度注解备注perIdYvarchar(60)第三方接入平台身份识别码statusYvarchar(32)项目接入编号响应参数参数必须注解备注responeCodeY响应Code200为成功,其它为失败,失败原因具体可看responeMessageresponeMessageY响应MessageresponseResultY响应Result7.
绑定设备接口说明接口描述绑定设备请求地址/api/dev/create请求方法POST备注请求参数参数必须类型与长度注解备注deviceKeyYvarchar(9)9位设备序列号代码typeYtinyint(1)类型1:进门2:出门channelYtinyint(1)匝道1:1匝道2:2匝道3:3匝道4:4匝道5:5匝道响应参数参数必须注解备注responeCodeY响应Code200为成功,其它为失败,失败原因具体可看responeMessageresponeMessageY响应MessageresponseResultY响应Result得到devId,解绑时必须使用到8.
解绑设备接口说明接口描述绑定设备请求地址/api/dev/delete/{devId}请求方法DELETE备注请求参数参数必须类型与长度注解备注无响应参数参数必须注解备注responeCodeY响应Code200为成功,其它为失败,失败原因具体可看responeMessageresponeMessageY响应MessageresponseResultY响应Result四、硬件通讯标准连接方式:TCP/IP端口:终端作为服务器端口为32068;连接方向终端主动连接PC,或者PC主动连接终端数据包基本格式:包标识、包序号、包类型、数据长度、数据内容共五个字段各字段描述如下:包标识:包头标识(2字节,固定为0x8888)包序号:包序列号(2字节,值域0-65535),不强制从0开始,但响应包必须与对应的请求包的包序号相同包类型:请求或响应命令(1字节),详见下表描述.
子类型:命令对应的数据类型(1字节)详见下表描述.
数据长度:包数据内容长度,不包括本字段及前面各字段(单位:4字节)数据内容:请求或响应数据的内容(当数据长度为0时本字段不存在),具体格式依不同包类型不同,详见各种包类型描述与子类型描述.

关于包类型与子类型取值说明包类型包类型取值AUTH0认证,连接GET1GET_NEXT2PUT3PUT_NEXT4RESPONSE5应答TRAP6终端数据自动上报HEARTBEAT7心跳子类型子类型取值AUTH_RANDOM0AUTH_AUTHENTICATE1USER_ENROLL_FACE65USER_MANAGE_USER_ADMIN108USER_SEND_USER_ADMIN_TMPL63TRAP_VERIFY_RESULT901.
建立连接功能描述包类型子类型协议交互细节数据描述系统设置之建立连接,包括:终端主动连接PC、PC主动连接终端AUTHAUTH_RANDOMAUTH_AUTHENTICATE终端作为客户端:1、TCP/IP连接建立后,客户端发起认证申请获取认证随机数包类型:AUTH子类型:AUTH_RANDOM数据长度:52字节数据:协议版本号(2)+终端类型(2)+终端名称(16)+终端型号(16)+序列号(16)2、服务器端收到此认证请求后,返回认证随机数包类型:RESPONSE子类型:ACK数据长度:4字节数据:随机数,由终端SN生成(4字节二进制数)3、客户端收到认证随机数后,发送认证请求:包类型:AUTH子类型:AUTH_AUTHENTICATE数据长度:16字节数据:16字节MD5校验码(由终端默认密码"f1i2r3s4F%I^R&S*"+序列号(不足16位需要补零)+随机数(低字节在前,高字节在后)生成)4、服务器收到认证请求后进行认证,如果认证成功返回:包类型:RESPONSE子类型:成功为ACK,失败为NAK数据长度:0数据:0//#defineACK0/*请求成功*/#defineNAK1/*请求失败*AUTH_RANDOMAUTH_AUTHENTICATE终端作为服务端:1、TCP/IP连接建立后,客户端发起认证申请获取认证随机数包类型:AUTH子类型:AUTH_RANDOM数据长度:02、服务器收到认证请求后,返回认证随机数包类型:RESPONSE子类型:ACK数据长度:4字节数据:随机数,由终端SN生成(4字节二进制数)3、客户端收到认证随机数后,发送认证请求:包类型:AUTH子类型:AUTH_AUTHENTICATE数据长度:用户名(16字节)+MD5校验码(16字节)数据:16字节用户名(用户名为"admin")+16字节MD5校验码(密码(设备端admin用户密码,默认"88888888",不需要补0)+随机数生成(低位在前,高位在后))4、服务器收到认证请求后进行认证,如果认证成功返回:包类型:RESPONSE子类型:成功为ACK,失败为NAK数据长度:52字节数据:协议版本号(2)+终端类型(2)+终端名称(16)+终端型号(16)+序列号(16)2.
获取注册信息功能描述包类型子类型协议交互细节数据描述返回人脸注册信息PUTUSER_ENROLL_FACEA.
客户端发送用户注册请求:包类型:PUT子类型:USER_ENROLL_FACE数据长度:用户工号长度(4字节)+保存用户标识(1字节)+用户类型(1字节)数据:用户工号(4字节,为0表示注册新用户)+保存用户标识(0:只上传用户信息但终端不保存用户,1:保存并上传用户信息)B.

终端收到有效的用户注册请求后响应:包类型:RESPONSE子类型:ACK长度:用户注册响应数据结构长度数据:用户注册响应数据结构,包含用户工号+用户特征码长度+用户特征码(二进制加密数据,与提取用户特征码方式得到的特征码一致)+图片类型+用户照片长度+用户照片数据+卡号备注:请求的用户工号或保存用户标识无效时返回NAK用户注册响应数据结构:字段名称长度备注用户工号4字节用户工号特征码长度4字节用户特征码长度特征码特征码长度用户特征码数据照片类型1字节0-BMP;1-JPG照片长度4字节照片的长度,0为无照片照片数据照片长度数据长度由照片长度决定(照片长度为0时本字段不存在)卡号4字节用户卡号3.
添加人员功能描述包类型子类型协议交互细节数据描述添加人员PUTUSER_MANAGE_USER_ADMIN1、客户端发起请求:包类型:PUT子类型:USER_MANAGE_USER_ADMIN数据长度:添加或修改用户信息时为用户信息记录长度,删除用户时长度等于5(1字节用户类型+4字节用户工号)数据:添加或修改用户信息时为用户信息,删除用户时为用户工号,工号等于0时删除全部用户2、终端响应:包类型:RESPONSE子类型:成功为ACK,失败为NAK数据长度:0数据:无用户信息记录格式定义如下:字段名称长度备注用户类别1字节(0-普通用户,1-管理员,2-超级管理员)用户工号4字节用户卡号32字节开门权限4字节用户名32字节部门编号4字节用户识别模式1字节(1-人脸识别,2-人脸或刷卡,3-人脸与刷卡,4-人脸与密码5-人脸与工号6-密码7-刷卡8-人脸或密码9-刷卡+密码)(普通用户:使用1,2,3,5,6,7模式;管理员:使用3,4模式)注册状态1字节0-未注册人脸特征,1-已注册人脸特征照片类型1字节,固定为0照片长度4字节照片的长度,0为无照片照片数据照片长度数据长度由照片长度决定(照片长度为0时本字段不存在)4.
添加人员人脸库功能描述包类型子类型协议交互细节数据描述下发用户人脸特征文件PUTUSER_SEND_USER_ADMIN_TMPL1、客户端发起请求:包类型:PUT子类型:USER_SEND_USER_ADMIN_TMPL数据长度:用户工号(4字节)+用户类型(1字节)+用户特征码数据长度数据:用户工号(4字节)+用户类型(1字节)+用户特征码数据(二进制加密数据,通过提取用户特征码方式得到)2、终端收到有效的修改用户特征码信息请求后响应:包类型:RESPONSE子类型:ACK长度:0数据:无备注:用户工号或特征码数据无效时返回NAK5.
上报考勤数据功能描述包类型子类型协议交互细节数据描述上报识别结果TRAPTRAP_VERIFY_RESULT1、系统连接后,终端识别通过或失败将自动给系统发送识别结果通知.
识别结果通知信息格式为:包类型:TRAP子类型:TRAP_VERIFY_RESULT数据长度:用户工号(4字节)+用户识别结果(1字节)+相似度(1字节)+照片类型(1字节0-BMP,1-JPG)+抓拍照片长度(JPG文件长度)数据:用户工号(4字节二进制整数)+用户识别结果(1-识别成功;0-识别失败)+相似度(0-100)+照片类型(1字节0-BMP,1-JPG)+照片长度+抓拍照片数据(JPG文件格式)备注:系统请求识别只发送请求响应(已包含此通知信息),不再额外发送此TRAP通知2、服务器应答:包类型:RESPONSE子类型:ACK数据长度:0数据:0备注:失败返回NAK.