广州市建设领域管理应用信息平台.docx
- 文档编号:23475645
- 上传时间:2023-05-17
- 格式:DOCX
- 页数:8
- 大小:17.74KB
广州市建设领域管理应用信息平台.docx
《广州市建设领域管理应用信息平台.docx》由会员分享,可在线阅读,更多相关《广州市建设领域管理应用信息平台.docx(8页珍藏版)》请在冰豆网上搜索。
广州市建设领域管理应用信息平台
广州市建设领域管理应用信息平台
建筑工人考勤数据接口标准
一、引言
1.1编写目的
为实现广州市建设领域管理应用信息平台对项目从业人员实名制管理和工人工资分账管理,考虑到部分项目已经在使用一些商业化实名制管理系统,为避免数据重复登记、减少系统改造成本,特编写本接口文档以供施工企业相关技术人员对接。
1.2适用范围
本文档的适用对象为接入广州市建设领域管理应用信息平台的施工企业技术开发人员、日常维护人员。
1.3简称和术语
广州市建设领域管理应用信息平台:
以下简称“信息平台”
施工企业:
指依法取得施工企业资质证书,在本市从事建设施工活动的施工总承包企业、专业承包企业和劳务分包企业
二、开发规范
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)),如:
身份证号:
511301************1,接入密钥:
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批量上报工人考勤
接口说明
接口描述
施工企业批量上报工人考勤
请求地址
/attendance/attendance/saves
测试请求地址
请求参数
参数
限制
长度
注释
备注
accessNo
M
FL32
接入编号
“信息平台”为施工企业分配的接入编号
dataList
M
NL
考勤数据列表
考勤数据列表。
不参与签名。
json格式的数据:
[{
builderIdcard:
‘工人身份证号,使用DES加密’,
workDate:
‘考勤日期yyyyMMdd’,
workStart:
‘上班时间yyyyMMddHHmmss’,
workEnd:
‘下班时间yyyyMMddHHmmss’
}]
timestamp
M
FL17
时间戳
北京时间精确到毫秒(yyyyMMddHHmmssSSS)
sign
M
FL32
签名
dataList不参与签名
响应参数
参数
限制
说明
resultCode
M
返回结果码,数字类型。
0表示成功;其它表示失败。
resultDesc
O
返回结果描述
3.2实时上报工人考勤
接口说明
接口描述
施工企业实时上报工人考勤。
工人必须存在。
请求地址
/attendance/attendance/save
测试请求地址
请求参数
参数
限制
长度
注释
备注
accessNo
M
FL32
接入编号
“信息平台”为施工企业分配的接入编号
builderIdcard
M
VL150
工人身份证号
检查工人是否存在的依据,使用DES加密
atteTime
M
FL17
考勤时间
yyyyMMddHHmmss
atteImage
O
NL
考勤图片
取图片的二进制值,转成base64编码。
不参与签名
timestamp
M
FL17
时间戳
北京时间精确到毫秒(yyyyMMddHHmmssSSS)
sign
M
FL32
签名
atteImage不参与签名
响应参数
参数
限制
说明
resultCode
M
返回结果码,数字类型。
0表示成功;其它表示失败。
resultDesc
O
返回结果描述
四、附录
4.1测试环境
测试环境接入编号:
测试环境接入密钥:
teamCode:
builderIdcard:
4.2结果码对照表
返回码
返回码文本介绍
说明
0
请求成功
当且仅当返回码为0时,请求成功
1
签名验证失败
签名错误
2
参数错误
参数长度或数据类型错误
3
接入编号错误
接入编号不存在
201
班组不存在
添加修改班组工人时返回
202
工人不存在
添加修改工人证书、添加修改班组工人时返回
-1
系统内部异常:
[..],请稍候再试
系统内部异常,返回异常描述
4.3调用示例
1、将参数排序(以JavaTreeMap实现参数名按ASCII字典顺序排序)
TreeMap
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);
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 广州市 建设 领域 管理 应用 信息 平台