XX市建设领域管理应用信息平台建筑工人实名制数据接口标准.docx
《XX市建设领域管理应用信息平台建筑工人实名制数据接口标准.docx》由会员分享，可在线阅读，更多相关《XX市建设领域管理应用信息平台建筑工人实名制数据接口标准.docx（20页珍藏版）》请在冰豆网上搜索。
XX市建设领域管理应用信息平台建筑工人实名制数据接口标准
XX市建设领域管理应用信息平台
建筑工人实名制数据接口标准
一、引言1
1.1编写目的1
1.2适用范围1
1.3简称和术语1
二、开发规范2
2.1通信协议2
2.2通信安全2
2.3注意事项2
三、接口说明4
3.1新增班组4
3.2修改班组5
3.3添加班组工人6
3.4修改班组工人8
3.5班组工人进退场9
四、附录10
4.1测试环境10
4.2结果码对照表10
4.3工种代码表10
4.4银行代码表11
一、引言
1.1编写目的
为实现XX市建设领域管理应用信息平台对项目从业人员实名制管理，考虑到部分项目已经在使用一些商业化实名制管理系统，为避免数据重复登记、减少系统改造成本，特编写本接口文档以供施工企业相关技术人员对接。
1.2适用范围
本文档的适用对象为接入XX市建设领域管理应用信息平台的施工企业技术开发人员、日常维护人员。
1.3简称和术语
XX市建设领域管理应用信息平台：
以下简称“信息平台”
施工企业：
指依法取得施工企业资质证书，在本市从事建设施工活动的施工总承包企业、专业承包企业和劳务分包企业
二、开发规范
2.1通信协议
●采用HTTP（或HTTPS）协议进行请求和响应的处理。
接口请求采用GET/POST方式。
接口响应返回JSON格式的数据。
●由“信息平台”提供接口地址，企业实名制或考勤系统。
●接口请求URL地址：
详见接口说明。
●接口未注明处均使用UTF-8编码。
●通信过程中涉及的中文或特殊符号的传输，需进行urlencode处理。
●HTTP（或HTTPS）请求参数均为字符串。
●接口请求需进行签名，详见2.2通信安全一节。
2.2通信安全
为保证数据传输过程中的数据真实性，我们需要对数据进行数字签名，在接收签名数据之后进行签名校验。
“信息平台”会为施工企业的每个工程分配唯一的接入编号和接入密钥。
签名机制如下：
●对全部有长度限制的传输字段（不包括NL类型的字段）进行签名，将参数名（区分大小写）和参数值（需进行urlencode处理）用“=”连接，参数值为空的参数不参与签名，参数之间用“&”连接，格式是：
param1=val1¶m2=val2…。
●参数组装顺序规则：
参数名的字典顺序。
●密钥拼接方式为传输参数直接连接密钥，如只有param1和param2两参数，值分别为val1和val2，密钥为key，拼接结果为：
param1=val1¶m2=val2key。
●使用“信息平台”分配的密钥进行MD5加密（密钥直接跟在组装好的参数后即可），将值赋给sign参数。
●敏感信息班组编号、身份证图片路径、身份证号、银行卡号、社保号需要加密传输，使用DES加密，加密key等于接入密钥，加密后的字节码转为16进制编码的字符串，并在密文字符串的前面加“des:
”前缀。
算法：
密文=”des:
”+HEX（DES（idcard,key）），如：
身份证号：
****************，接入密钥：
8c2da4c769828fcfa77aedb690999cf9，密文：
des:
80cfe03525bb2b8d43d62ff369e95334cd1facfe4bbb800c
2.3注意事项
●接口中各项参数当标识是M时参数必选，为O时可选。
●接口字段长度分为三种：
无限制（NL），固定长度（FL），可变长度（VL）。
如果为FL，则长度必须精确到FL后跟随的数字，格式举例FL14；如果为VL，则长度在可变范围内即可，如果长度不够，不补空格或其它字符，格式举例VL30。
●接口说明中，若参数字体为红色，请仔细阅读备注说明。
●请求返回结果码不为0时，需要再次提交请求。
如果结果码大于0，则需要根据提示信息修改错误后再次提交；如果结果码小于0，可以间隔一段时间再提交（如：
选择间隔5分钟、10分钟、30分钟、1小时提交一次，连续5次提交不成功时推迟到第二天再提交）。
三、接口说明
●所有接口响应的返回信息均以JSON字符串形式返回，可以使用JSON工具包对其进行解析。
●返回信息具体字段参照接口说明中的响应参数，以下以举例：
处理成功：
{"resultCode":
0,"resultDesc":
"处理成功"}
处理失败：
{"resultCode":
1,"resultDesc":
"签名错误"}
●返回结果码对照见附录4.2结果码对照表。
3.1新增班组
接口说明
接口描述
施工企业添加班组时调用
请求地址
/smz/team/save
测试请求地址
请求参数
参数
限制
长度
注释
备注
accessNo
M
FL32
接入编号
“信息平台”为施工企业分配的接入编号
teamCode
M
VL320
班组编码
工程内部的班组唯一编码，如果班组编码已存在则修改班组。
格式：
班组长身份证号+班组类型代码，使用DES加密
name
M
VL40
班组名称
班组命名格式：
班组长姓名+班组类型+“班组”
workType
M
VL32
班组类型
参考附录4.3
leaderAppointment
O
VL400
班组长证明书
外网能访问的URL路径，“信息平台”会自动抓取
leaderIdcard
M
VL150
工人身份证号
检查工人是否存在的依据，使用DES加密
leaderName
M
VL30
工人姓名
leaderSex
M
FL1
性别
M：
男F：
女
leaderNation
M
VL40
民族
leaderBirthday
M
FL8
生日
yyyyMMdd
leaderAddress
M
VL400
住址
身份证上的住址
leaderSignOrgan
M
VL30
签发机关
身份证的签发机关
leaderExpiryStart
M
FL8
有效期开始日期
身份证有效期开始日期
leaderExpiryEnd
O
FL8
有效期结束日期
身份证有效期结束日期，为空表示长期
leaderHeadImg
O
VL400
身份证头像URL
外网能访问的URL路径，“信息平台”会自动抓取
leaderIdcardFront
O
VL1500
身份证正面照
外网能访问的URL路径，“信息平台”会自动抓取，使用DES加密
leaderIdcardBack
O
VL1500
身份证反面照
外网能访问的URL路径，“信息平台”会自动抓取，使用DES加密
leaderCurrentAddress
M
VL400
常住地址
近期的常住地址
leaderPolitical
M
FL1
政治面貌
0：
党员1：
团员2：
群众
leaderEducation
M
VL32
文化程度
本科以上、本科、大专、中专、高中、初中及以下
leaderPhone
M
VL11
手机号
leaderEmployType
M
FL1
用工形式
0：
固定工人1：
外聘
leaderTechLevel
M
FL1
技能水平
0：
无（普通）；1：
初级工；2：
中级工；3：
高级工；4：
技师；5：
高级技师
leaderContractCode
O
VL50
合同编号
施工企业内部的合同编号。
leaderContractFile
O
VL400
合同附件
外网能访问的URL路径，“信息平台”会自动抓取。
leaderCardNum
O
VL150
工资卡账号
使用DES加密
leaderCardBank
O
VL10
工资卡开户行代码
参考附录4.4
leaderWorkType
M
VL32
工种代码
参考附录4.3
leaderSecurityCode
O
VL300
社保号
使用DES加密
leaderSafetyEdu
M
FL1
是否参加安全教育
true:
是；false：
否
leaderSafetyEduImg
O
VL400
安全教育图片
外网能访问的URL路径，“信息平台”会自动抓取。
leaderBuilderType
M
FL1
工人类型
0：
建筑工匠；1：
建筑产业技术工人；2：
其他
leaderDoDate
M
FL8
进场日期
yyyyMMdd
timestamp
M
FL17
时间戳
北京时间精确到毫秒（yyyyMMddHHmmssSSS）
sign
M
FL32
签名
响应参数
参数
限制
说明
resultCode
M
返回结果码，数字类型。
0表示成功；其它表示失败。
resultDesc
O
返回结果描述
3.2修改班组
接口说明
接口描述
施工企业修改班组时调用
请求地址
/smz/team/update
测试请求地址
请求参数
参数
限制
长度
注释
备注
accessNo
M
FL32
接入编号
“信息平台”为施工企业分配的接入编号
teamCode
M
VL320
班组编码
工程内部的班组唯一编码，如果班组编码已存在则修改班组。
格式：
班组长身份证号+班组类型代码，使用DES加密
name
M
VL40
班组名称
班组命名格式：
班组长姓名+班组类型+“班组”
workType
M
VL32
班组类型
参考附录4.3
leaderAppointment
O
VL400
班组长证明书
外网能访问的URL路径，“信息平台”会自动抓取
leaderIdcard
M
VL150
工人身份证号
检查工人是否存在的依据，使用DES加密
leaderCurrentAddress
M
VL400
常住地址
近期的常住地址
leaderPolitical
M
FL1
政治面貌
0：
党员1：
团员2：
群众
leaderEducation
M
VL32
文化程度
本科以上、本科、大专、中专、高中、初中及以下
leaderPhone
M
VL11
手机号
leaderEmployType
M
FL1
用工形式
0：
固定工人1：
外聘
leaderTechLevel
M
FL1
技能水平
0：
无（普通）；1：
初级工；2：
中级工；3：
高级工；4：
技师；5：
高级技师
leaderContractCode
O
VL50
合同编号
施工企业内部的合同编号。
leaderContractFile
O
VL400
合同附件
外网能访问的URL路径，“信息平台”会自动抓取。
leaderCardNum
O
VL150
工资卡账号
使用DES加密
leaderCardBank
O
VL10
工资卡开户行代码
参考附录4.4
leaderWorkType
M
VL32
工种代码
参考附录4.3
leaderSecurityCode
O
VL300
社保号
使用DES加密
leaderSafetyEdu
M
FL1
是否参加安全教育
true:
是；false：
否
leaderSafetyEduImg
O
VL400
安全教育图片
外网能访问的URL路径，“信息平台”会自动抓取。
leaderBuilderType
M
FL1
工人类型
0：
建筑工匠；1：
建筑产业技术工人；2：
其他
timestamp
M
FL17
时间戳
北京时间精确到毫秒（yyyyMMddHHmmssSSS）
sign
M
FL32
签名
响应参数
参数
限制
说明
resultCode
M
返回结果码，数字类型。
0表示成功；其它表示失败。
resultDesc
O
返回结果描述
3.3添加班组工人
接口说明
接口描述
为已登记的班组添加工人。
请求地址
/smz/teamBuilder/save
测试请求地址
请求参数
参数
限制
长度
注释
备注
accessNo
M
FL32
接入编号
“信息平台”为施工企业分配的接入编号
teamCode
M
VL320
班组编码
工程内部的班组唯一编码，如果班组编码已存在则修改班组，使用DES加密
idcard
M
VL150
工人身份证号
检查工人是否存在的依据，如果工人已存在则修改，使用DES加密
name
M
VL30
工人姓名
sex
M
FL1
性别
M：
男F：
女
nation
M
VL40
民族
birthday
M
FL8
生日
yyyyMMdd
address
M
VL400
住址
身份证上的住址
signOrgan
M
VL30
签发机关
身份证的签发机关
expiryStart
M
FL8
有效期开始日期
身份证有效期开始日期
expiryEnd
O
FL8
有效期结束日期
身份证有效期结束日期，为空表示长期
headImg
O
VL400
身份证头像URL
外网能访问的URL路径，“信息平台”会自动抓取
idcardFront
O
VL1500
身份证正面照
外网能访问的URL路径，“信息平台”会自动抓取，使用DES加密
idcardBack
O
VL1500
身份证反面照
外网能访问的URL路径，“信息平台”会自动抓取，使用DES加密
currentAddress
M
VL400
常住地址
近期的常住地址
political
M
FL1
政治面貌
0：
党员1：
团员2：
群众
education
M
VL20
文化程度
本科以上、本科、大专、中专、高中、初中及以下
phone
M
VL11
手机号
employType
M
FL1
用工类型
0：
自有工人；1：
外聘工人
contractCode
O
VL50
合同编号
施工企业内部的合同编号。
contractFile
O
VL400
合同附件
外网能访问的URL路径，“信息平台”会自动抓取。
cardNum
O
VL150
工资卡账号
使用DES加密
cardBank
O
VL10
工资卡开户行代码
参考附录4.4
workType
M
VL32
工种代码
参考附录4.3
techLevel
M
FL1
技能水平
0：
无（普通）；1：
初级工；2：
中级工；3：
高级工；4：
技师；5：
高级技师
securityCode
O
VL300
社保号
使用DES加密
safetyEdu
M
FL1
是否参加安全教育
true:
是；false：
否
safetyEduImg
O
VL400
安全教育图片
外网能访问的URL路径，“信息平台”会自动抓取。
builderType
M
FL1
工人类型
0：
建筑工匠；1：
建筑产业技术工人；2：
其他
doDate
M
FL8
进场日期
yyyyMMdd
timestamp
M
FL17
时间戳
北京时间精确到毫秒（yyyyMMddHHmmssSSS）
sign
M
FL32
签名
响应参数
参数
限制
说明
resultCode
M
返回结果码，数字类型。
0表示成功；其它表示失败。
resultDesc
O
返回结果描述
3.4修改班组工人
接口说明
接口描述
修改已登记的班组工人。
请求地址
/smz/teamBuilder/update
测试请求地址
请求参数
参数
限制
长度
注释
备注
accessNo
M
FL32
接入编号
“信息平台”为施工企业分配的接入编号
teamCode
M
VL320
班组编码
工程内部的班组唯一编码，如果班组编码已存在则修改班组，使用DES加密
idcard
M
VL150
工人身份证号
检查工人是否存在的依据，如果工人已存在则修改，使用DES加密
currentAddress
M
VL400
常住地址
近期的常住地址
political
M
FL1
政治面貌
0：
党员1：
团员2：
群众
education
M
VL20
文化程度
本科以上、本科、大专、中专、高中、初中及以下
phone
M
VL11
手机号
employType
M
FL1
用工类型
0：
自有工人；1：
外聘工人
contractCode
O
VL50
合同编号
施工企业内部的合同编号。
contractFile
O
VL400
合同附件
外网能访问的URL路径，“信息平台”会自动抓取。
cardNum
O
VL150
工资卡账号
使用DES加密
cardBank
O
VL10
工资卡开户行代码
参考附录4.4
workType
M
VL32
工种代码
参考附录4.3
techLevel
M
FL1
技能水平
0：
无（普通）；1：
初级工；2：
中级工；3：
高级工；4：
技师；5：
高级技师
securityCode
O
VL300
社保号
使用DES加密
safetyEdu
M
FL1
是否参加安全教育
true:
是；false：
否
safetyEduImg
O
VL400
安全教育图片
外网能访问的URL路径，“信息平台”会自动抓取。
builderType
M
FL1
工人类型
0：
建筑工匠；1：
建筑产业技术工人；2：
其他
timestamp
M
FL17
时间戳
北京时间精确到毫秒（yyyyMMddHHmmssSSS）
sign
M
FL32
签名
响应参数
参数
限制
说明
resultCode
M
返回结果码，数字类型。
0表示成功；其它表示失败。
resultDesc
O
返回结果描述
3.5班组工人进退场
接口说明
接口描述
班组工人进场或退场。
请求地址
/smz/enterExit/save
测试请求地址
请求参数
参数
限制
长度
注释
备注
accessNo
M
FL32
接入编号
“信息平台”为施工企业项目分配的接入编号
teamCode
M
VL320
班组编码
工程内部的班组唯一编码，如果班组编码已存在则修改班组，使用DES加密
idcard
M
VL150
工人身份证号
检查工人是否存在的依据，使用DES加密
type
M
FL1
类型
0：
进场；1：
退场
doDate
M
FL8
进退场日期
yyyyMMdd
timestamp
M
FL17
时间戳
北京时间精确到毫秒（yyyyMMddHHmmssSSS）
sign
M
FL32
签名
响应参数
参数
限制
说明
resultCode
M
返回结果码，数字类型。
0表示成功；其它表示失败。
resultDesc
O
返回结果描述
四、附录
4.1测试环境
测试环境接入编号：
测试环境接入密钥：
4.2结果码对照表
返回码
返回码文本介绍
说明
0
请求成功
当且仅当返回码为0时，请求成功
1
签名验证失败
签名错误
2
参数错误
参数长度或数据类型错误
3
接入编号错误
接入编号不存在
201
班组不存在
添加修改班组工人时返回
202
工人不存在
添加修改工人证书、添加修改班组工人时返回
-1
系统内部异常:
[..],请稍候再试
系统内部异常，返回异常描述
4.3工种代码表
4.4银行代码表
4.5调用示例
1、将参数排序（以JavaTreeMap实现参数名按ASCII字典顺序排序）
TreeMapparams=newTreeMap<>（）;
params.put（“param1”,urlencode（“value1”,“UTF-8”））;
params.put（“param2”,urlencode（“value2”,“UTF-8”））;
2、将参数拼接成字符串（空值不参与签名）
Stringstr="";
for（param:
params）{
if（param.value!
=null&¶m.value.length（）>0）{
str+="&"+param.key+"="+param.value;
}
}
str=str.substring（1,str.length（））;
3、生成签名
Stringsign=md5（str+key）;
params.put（"sign",sign）;
4、提交数据
http.post（params）;
升级会员 