一、 概述
为规范上海市建筑工程实名制管理系统（以下简称“市实名制系统“）中工地现场考勤数据的采集，统一考勤信息的数据标准，实现工地现场考勤数据同步至市实名制系统，编制《上海市建筑工程实名制管理系统工地现场考勤数据对接技术规范及数据标准》。
本市用于工地现场考勤信息系统的开发和使用，除了遵守相关国家和上海市相关产品标准规范外，还需遵守本技术规范及数据标准。
工地现场考勤信息系统是建设工程施工总承包单位在工地现场建设，用于出入施工现场的人员考勤的设施，应当包括门禁装置、人脸识别装置、信息显示设备以及实名信息采集设备等。工地现场考勤信息系统应具备插入工地专用数字证书后，方可自动产生经工地专用数字证书数字签名的考勤记录，并通过数据接口方式对接上报市实名制系统的功能。
工地专用数字证书是上海市数字认证中心有限公司（上海CA）签发的上海市建筑工地专用的数字证书，在本标准中用于对上传的考勤数据进行数据签名。
证书介质为USB Key，内含RSA和SM2两种算法的签名和加密证书。证书内容包括：工地名称、工地编号、工地总包单位名称、工地总包单位信用代码，工地施工总包合同编号。
二、 考勤数据接口使用流程
工地总包企业项目负责人登录市实名制系统，插入该工地对应的工地专用证书，输入证书密码，完成工地专用数字证书的登记工作。完成登记操作后，系统会自动分配一个安全令牌作为接口调用凭证。
安全令牌仅允许该工地自行使用，用于调用数据接口时验证权限，若安全令牌泄漏所产生的责任由工地总包企业自行负责。安全令牌使用方法详见3.2考勤信息上报
Ø 工地应确保门禁系统运行时工地专用数字证书正常插在门禁系统运行的设备上
Ø 门禁系统按照本标准（四、考勤数据标准）的要求，生成考勤数据文件，确保数据未经人为修改
Ø 考勤数据文件使用住建委工地签名公钥（获取方式见5.2获取住建委考勤加密公钥），进行加密，加密后文件后缀为kq。加密方法见5.2.3 “使用公钥加密数据加密接口”
应按照管理部门的要求，定时通过数据接口方式上报考勤数据，详见四、考勤数据接口。
三、 考勤数据标准
文件格式：考勤数据原始文件应为一个采用ZIP格式压缩的数据文件，内容应包含一个以UTF-8代码格式创建的txt文件。
文件命名：txt文件及zip文件名称由总包合同编号和随机字符GUID组成，中间用英文符号“_”分隔，共46位。总包合同编号为字母W开头的14位字符（例：W2020100132796），随机字符为GUID（不含-）（例：2BA27C6A7BC1FCAC32EDDFC47F07429E），随机字符不能重复，每次上传必须重新生成随机字符。文件命名示例见下图
W2020100132796_2BA27C6A7BC1FCAC32EDDFC47F07429E.zip
随机字符GUID
总包合同编号
文件尺寸：单个zip文件大小应限制在500kb以内。
加密文件为原始文件通过住建委考勤加密公钥（通过4.2 获取住建委考勤加密公钥 获取），调用5.2.3加密接口进行加密之后，将加密接口返回结果中data值为Base64字符的加密内容保存为后缀名是kq的文件。例如原始文件为XXXX.zip，加密后的加密文件应为XXXX.kq
txt文件中的数据结构应当为标准JSON格式，字段说明如下表所示
|
序号 |
字段名称 |
数据类型 |
长度 |
是否必填 |
字段备注说明 |
|
1 |
wsslbh |
字符型 |
20 |
必填 |
总包合同编号 |
|
2 |
dwmc |
字符型 |
100 |
必填 |
总包单位名称 |
|
3 |
xydm |
字符型 |
18 |
必填 |
总包单位统一社会信用代码 |
|
4 |
xm |
字符型 |
10 |
必填 |
考勤人员姓名 |
|
5 |
zjh |
字符型 |
18 |
必填 |
考勤人员身份证号 |
|
6 |
type |
字符型 |
1 |
必填 |
考勤类型，固定值，1或2 1代表进入 2代表离开 |
|
7 |
time |
字符型 |
20 |
必填 |
考勤时间， 例：2020-08-10 08:30:00 |
文件内容示例如下所示
JSON格式示例
|
{ "Data":[ { "wsslbh":"W2020010112345", "dwmc":"XXXXXXXX单位", "xydm":"XXXXXXXXXXXXXXXXXX", "xm":"张三", "zjh":"xxxxxxxxxxxxxxxxxx", "type":"1", "time":"2020-01-01 09:00:00" }, { "wsslbh":"W2020010112345", "dwmc":"XXXXXXXX单位", "xydm":" XXXXXXXXXXXXXXXXXX ", "xm":"XXX", "zjh":"xxxxxxxxxxxxxxxxxx", "type":"2", "time":"2020-01-01 17:00:00" } ]} |
四、 考勤数据接口
四.1.1 接口通用标准说明
本章节所有接口，未经特殊说明，所有涉及编码的地方都采用UTF-8编码。
|
Response示例（示例仅做参考，具体以接口为准） |
|
|
{ " Result": true, " Code": "200", " Message": "", "Data": { } } |
|
|
Response具体参数说明 |
|
|
参数名 |
说明 |
|
Result |
接口是否调用成功 true为成功 false为失败 |
|
Code |
接口执行结果状态码 200：成功。其余状态码都表示失败。详情见第六章。 |
|
Message |
Code不为200时，执行结果的详细信息。详情见第六章。 |
|
Data |
方法返回的内容，具体参见方法的Response示例 |
|
访问地址 |
||||
|
/v1/GetKey |
||||
|
HTTP请求方式 |
||||
|
POST |
||||
|
Request格式及参数说明 |
||||
|
Header |
||||
|
参数名 |
必需 |
类型 |
说明 |
|
|
SecretKey |
是 |
string |
身份认证安全令牌 |
|
|
TimeStamp |
是 |
string |
自定义时间戳 例：20210426121345 |
|
|
SignatureAccess |
是 |
string |
将SecretKey和TimeStamp拼接后使用工地专用数字证书进行签名得到的签名字符串。 签名方法详见5.2.2签名接口 |
|
|
Response格式 |
||||
|
String Body（application/json） |
||||
|
Response示例（示例仅做参考，具体以接口为准） |
||||
|
{ "Result": true, "Code": "200", "Message": "成功", "Data": { "Key": "XXXXXXXXXXXXXXXX" } } |
||||
|
Response中Data对象的具体参数说明 |
||||
|
参数名 |
说明 |
|||
|
Key |
加密公钥 |
|||
|
访问地址 |
|||
|
HTTP请求方式 |
|||
|
POST |
|||
|
Request格式及参数说明 |
|||
|
Header |
|||
|
参数名 |
必需 |
类型 |
说明 |
|
SecretKey |
是 |
string |
身份认证安全令牌 |
|
TimeStamp |
是 |
string |
自定义时间戳 例：20210426121345 |
|
SignatureAccess |
是 |
string |
将SecretKey和TimeStamp拼接后使用工地专用数字证书进行签名得到的签名字符串。 签名方法详见5.2.2签名接口 |
|
Multipart Body |
|||
|
参数名 |
必需 |
类型 |
说明 |
|
Signature |
是 |
string |
.kq考勤文件的MD5码签名得到的签名字符串 签名方法详见：5.2.2签名接口 |
|
FileName |
是 |
string |
文件名称 例：W2020100132796_20200101235959.kq |
|
Data |
是 |
file |
考勤数据加密文件 加密文件参考：三、考勤数据标准中的3.2加密文件标准 |
|
Response格式 |
|||
|
String Body（application/json） |
|||
|
Response示例（示例仅做参考，具体以接口为准） |
|||
|
{ "Result": true, "Code": "200", "Message": "成功", "Data": { "FileNo": "XXXXXXXXXXXXXXXX" } } |
|||
|
Response中Data对象的具体参数说明 |
|||
|
参数名 |
说明 |
||
|
FileNo |
文件唯一编码，可用于4.3考勤文件处理情况查询接口调用 |
||
|
访问地址 |
||||
|
/v1/result |
||||
|
HTTP请求方式 |
||||
|
POST |
||||
|
Request格式及参数说明 |
||||
|
Header |
||||
|
参数名 |
必需 |
类型 |
说明 |
|
|
SecretKey |
是 |
string |
身份认证安全令牌 |
|
|
TimeStamp |
是 |
string |
自定义时间戳 例：20210426121345 |
|
|
SignatureAccess |
是 |
string |
将SecretKey和TimeStamp拼接后使用工地专用数字证书进行签名得到的签名字符串。 签名方法详见5.2.2签名接口 |
|
|
String Body（application/json） |
||||
|
参数名 |
必需 |
类型 |
说明 |
|
|
FileNo |
是 |
string |
文件唯一编码（4.2考勤信息上报接口的返回值） |
|
|
Response格式 |
||||
|
String Body（application/json） |
||||
|
Response示例（示例仅做参考，具体以接口为准） |
||||
|
{ "Result": true, "Code": "200", "Message": "成功", "Data": { "DealResult": "sucess", "DealMessage": "处理成功" } } |
||||
|
Response中Data对象的具体参数说明 |
||||
|
参数名 |
说明 |
|||
|
DealResult |
处理结果 success代表处理完成 fail代码处理失败 |
|||
|
DealMessage |
处理情况的详细说明 |
|||
五、 数字证书接口
五.1.1 安装证书助手
登录https://www.sheca.com/resources/tools 下载证书助手并安装。
安装证书助手后，接口即可调用。
接口协议：http协议
地址：http://127.0.0.1:18455/
五.2.1 工地数字证书信息获取接口
|
访问地址 |
|||
|
http://127.0.0.1:18455/uk/action/100 |
|||
|
HTTP请求方式 |
|||
|
POST |
|||
|
Request格式 |
|||
|
String Body（application/json） |
|||
|
Request具体参数说明 |
|||
|
参数名 |
必需 |
说明 |
|
|
|
|
|
|
|
Response格式 |
|||
|
String Body（application/json） |
|||
|
Response示例（示例仅做参考，具体以接口为准） |
|||
|
|
|||
|
Response具体参数说明 |
|||
|
参数名 |
说明 |
||
|
type |
操作类型 |
||
|
code |
返回码，0：成功，非0失败 |
||
|
data |
code为0时返回信息，结构如下 { "keySN":"XXXXXXXXXXXX", "vid":"", "skfLib":"", "type":0 } |
||
|
ukddl_version |
动态库版本号 |
||
五.2.2 签名接口
|
访问地址 |
|||
|
http://127.0.0.1:18455/uk/action/300 |
|||
|
HTTP请求方式 |
|||
|
POST |
|||
|
Request格式 |
|||
|
String Body（application/json） |
|||
|
Request具体参数说明 |
|||
|
参数名 |
必需 |
说明 |
|
|
type |
否 |
标记类型 |
|
|
keySN |
是 |
工地专用数字证书介质序列号(唯一标识)，通过5.2.1数字证书信息查询接口获取到的KeySN
|
|
|
pin |
是 |
工地专用数字证书密码 |
|
|
raw |
是 |
待签名内容 |
|
|
asymid |
是 |
签名算法标识，此处固定使用1 |
|
|
wrapperType |
否 |
数据包装类型，此处固定使用0 |
|
|
signMethodID |
否 |
签名算法标识，此处固定使用65540 （65540:sha256withRSA） |
|
|
|
|
|
|
|
Response格式 |
|||
|
String Body（application/json） |
|||
|
Response示例（示例仅做参考，具体以接口为准） |
|||
|
|
|||
|
Response具体参数说明 |
|||
|
参数名 |
说明 |
||
|
type |
操作类型 |
||
|
code |
返回码，0：成功，非0失败 |
||
|
data |
code为0时返回签名值 |
||
|
ukddl_version |
动态库版本号 |
||
5.2.3 使用公钥加密数据加密接口
|
访问地址 |
|||
|
http://127.0.0.1:18455/uk/action/704 |
|||
|
HTTP请求方式 |
|||
|
POST |
|||
|
Request格式 |
|||
|
String Body（application/json） |
|||
|
Request具体参数说明 |
|||
|
参数名 |
必需 |
说明 |
|
|
type |
是 |
标记类型，固定传：704 |
|
|
pubkey |
是 |
公钥载体的BASE64,证书或公钥（通过4.2 获取加密公钥 获取到的证书） |
|
|
raw |
是 |
待加密内容（此处使用考勤原始文件zip的base64字符） |
|
|
|
|
|
|
|
Response格式 |
|||
|
String Body（application/json） |
|||
|
Response示例（示例仅做参考，具体以接口为准） |
|||
|
|
|||
|
Response具体参数说明 |
|||
|
参数名 |
说明 |
||
|
type |
操作类型 |
||
|
code |
返回码，0：成功，非0失败 |
||
|
data |
code为0时返回加密内容 |
||
六、 接口返回码标准
六.1 接口返回码说明
本文档4.2、4.3、4.4中的接口，未经特殊说明，所有涉及返回报文Response格式见下图：
|
Response示例（示例仅做参考，具体以接口为准） |
|
{ " Result": true, " Code": "200", " Message": "", "Data": { } } |
其中Code与Message返回码字典详见6.2接口返回码字典。
六.2 接口返回码字典
|
Code |
Message |
|
200（成功） |
|
|
400 |
接口异常（详细信息为代码抛出异常exception） |
|
501 |
安全令牌与登记证书安全令牌不一致，请检查。 |
|
502 |
未上传签名串（字段名Signature），请按要求正确上传。 |
|
503 |
未上传文件名称（字段名FileName），请按要求正确上传。 |
|
504 |
每次调用只允许上传一个文件，本次上传数量超出。 |
|
505 |
文件大小超出500KB，请上传小于500KB考勤文件。 |
|
506 |
上传文件名称参数（字段名Signature）与上传文件的名称不一致，请检查。 |
|
507 |
上传文件扩展名不正确,请上传.kq格式的文件。 |
|
508 |
文件唯一编码不正确或校验结果不唯一，查询失败。 |
|
509 |
接口调用超出限制次数,1分钟内同接口只能调用3次。 |
|
510 |
请求头中身份认证相关字段SecretKey、TimeStamp、SignatureAccess值不能为空。 |
|
511 |
自定义时间戳TimeStamp日期格式不正确，请上传格式为yyyyMMddHHmmss的时间戳。 |
|
512 |
自定义时间戳TimeStamp超出安全时间间隔，请在自定义时间戳生成后60秒内调用接口。 |
|
513 |
验证签名错误，请检查SecretKey与TimeStamp的原值与两者拼接字符串后的签名值SignatureAccess是否匹配。 |
|
514 |
上传文件大小为0KB，请上传大于0KB考勤文件。 |
|
515 |
上传文件名称为空，请上传正确考勤文件。 |
