本协议主要实现采集设备上传采集的建筑工人基本信息到实名制系统，以及考勤设备从实名制系统获取人员考勤信息、禁入人员信息，并上传考勤的数据，采集设备与系统通讯支持 https 协议，考勤设备与系统通讯支持 https 协议。施工现场原则上实施封闭式管理，设立进出场门禁系统，采用人脸、指纹、虹膜等生物识别技术进行电子打卡。 不具备封闭式管理条件的工程项目，应采用移动定位、电子围栏等技术实施考勤管理。
建筑用工实名制管理系统
实名制考勤设备数据对接协议（试行）
1.前言
x协议适用于考勤设备以接口方式对接市级建筑工人实名制平台，适合在四川省登记的考勤设备设备厂商。
2.对接目的
为实现建筑工人基本信息、考勤信息的标准化采集和全省统一。 3.协议概述
x协议主要实现采集设备上传采集的建筑工人基本信息到实名制系统，以及考勤设备从实名制系统获取人员考勤信息、禁入人员信息，并上传考勤的数据，采集设备与系统通讯支持 https 协议，考勤设备与系统通讯支持 https 协议。施工现场原则上实施封闭式管理，设立进出场门禁系统，采用人脸、指纹、虹膜等生物识别技术进行电子打卡。不具备封闭式管理条件的工程项目，应采用移动定位、电子围栏等技术实施考勤管理。
4.加密方式
1)各接口请求参数中含 sign 数字签名，签名方式为:
调用 HMAC MD5 算法; 根据提供的密钥（设备密钥）和密文（传输的数据顺序组合）输出 Hex 格式的密文摘要；密文和密钥的编码字符集使用 UTF8 格式。
2)返回参数 Content 及部分请求参数采用 SM4 加密传输：
SM4 签名方式，编码 UTF-8，加密方式：CBC，填充方式：PKCS7Padding。
5.接口及参数说明
5.1 接口描述
1)使用的通讯协议（https） 2)请求返回结果
{
Result: // 返回请求结果类型 Content: // 返回详细内容，json 格式 Msg: // 返回消息
}
3)采集成功后返回人员工号。
4)应保证身份证照片和现场照片是同一个人。
5)为了保证传输过程中的数据安全，返回结果中 Content 包体数据设定为使用 SM4 进行加密。
6)字符编码格式 UTF-8。
5.2 采集设备方法名称
RegistData
方法说明
上传实名认证后的注册人员信息。请求方法
POST
URL 地址
https://{API_ROOT}/RegistData
请求参数，post 参数（form-data）:
参数名 | 必选 | 类型范围 | 说明 |
Idno | 是 | string | 身份证号,SM4 加密传输 |
Name | 是 | string | 姓名 |
gender | 是 | int | 详见性别字典表 |
nation | 是 | string | 民族 |
birthday | 是 | string | 出生日期（yyyy-MM-dd） |
address | 是 | string | 住址 |
idissue | 是 | string | 发证机关 |
idperiod | 是 | string | 证件有效期，格式:20010101-20110101 （长期） |
idphoto | 是 | string | 身份证照片（base64）,SM4 加密传输 |
photo | 是 | string | 现场人员人脸照片（base64）,SM4 加密 传输 |
userType | 是 | int | 详见注册人员类型字典表 |
sn | 是 | string | 设备序列号 |
timestamp | 是 | String | 当前时间戳（精确到秒），5 分钟内有效 |
sign | 是 | String | 数字签名: 调用 HMAC MD5 算法; 根据提供的密钥 （设备密钥）和密文（传输的数据顺序组合）输出 Hex 格式的密文摘要； 密文和密钥的编码字符集使用UTF8 格式 |
返回结果
参数名 | 必选 | 类型范围 | 说明 |
Result | 是 | int | 详见返回结果字典表 |
Content | 否 | string | 返回内容，Result=0 时返回采集成功的人员userId |
Msg | 否 | string | 返回消息 |
返回示例
{
"Result":0, "Content":
{"userId":"XXXXXXXX"},
"Msg":""
}
数据说明：
序 号 | 属性 | 类型 | 名称 | 说明 |
1 | userId | String | 用户工号 |
5.3 考勤设备
5.3.1 心跳请求
考勤设备的心跳请求适用于封闭式管理工程项目所使用的实名制考勤设备，对采用移动定位、电子围栏等技术实施考勤管理的不需提供心跳请求。
方法名称
Online
方法说明
POST
心跳包，保持设备在线，同时有人员需要禁入和下发的时候，根据心跳返回消息。请求方法
URL 地址
https://{API_ROOT}/Online
请求参数(x-www-form-urlencoded)
参数名 | 必选 | 类型范围 | 说明 |
sn | 是 | String | 设备序列号 |
timestamp | 是 | String | 当前时间戳（精确到秒），5 分钟内有效 |
参数名 | 必选 | 类型范围 | 说明 |
sign | 是 | String | 数字签名: 调用 HMAC MD5 算法; 根据提供的密钥（设备密钥）和密文（sn、timestamp 顺序组合）输出 Hex格式的密文摘要； 密文和密钥的编码字符集使用 UTF8 格式 |
返回结果
参数名 | 必选 | 类型范围 | 说明 |
Result | 是 | int | 详见返回结果字典表 |
Content | 否 | string | 返回内容，Result=1 的时候返回的是 SM4 加密后任 务列表 |
Msg | 否 | string | 返回消息 |
返回示例
正常请求：
{
"Result":0, "Content":"",
"Msg":""
}
有待处理任务请求：
{
"Result":1,
"Content":[
{"Id":"XXXXXX","Type":1},
{"Id":"XXXXXX","Type":2}
],
"Msg":""
}
说明：Content 内容经过 SM4 加密的，解密后的格式如上示例
数据说明：
序 号 | 属性 | 类型 | 名称 | 说明 |
1 | Id | String | 任务 id | |
2 | Type | Int | 类别 | 详见待处理数据类别字典表 |
注意事项
心跳请求不能过于频繁，建议 5-10 分钟较合理。
GetTaskData
5.3.2 获取下发数据方法名称
方法说明
根据设备编号和任务 id 获取需要下发或禁入到设备的人员信息，设备获取到数据后应对设备上的人员进行新增或禁入。
请求方法
POST
URL 地址
https://{API_ROOT}/GetTaskData
请求参数(x-www-form-urlencoded)
参数名 | 必选 | 类型范围 | 说明 |
sn | 是 | String | 设备序列号 |
id | 是 | String | 任务 id |
timestamp | 是 | String | 当前时间戳（精确到秒），5 分钟内有效 |
sign | 是 | String | 数字签名: |
参数名 | 必选 | 类型范围 | 说明 |
调用 HMAC MD5 算法; 根据提供的密钥（设备密钥）和密文（sn、id、timestamp 顺序组合）输出 Hex 格式的密文摘要； 密文和密钥的编码字符集使用 UTF8 格式 |
返回结果
参数名 | 必选 | 类型范围 | 说明 |
Result | 是 | int | 详见返回结果字典表 |
Content | 否 | string | 返回内容,见数据说明 |
Msg | 否 | string | 返回消息 |
返回示例
待处理数据类别等于 1 的返回结果：
{
"Result":0, "Content"[
{"userId":" 用 户 工 号 ","name":" 姓 名 ","userType":" 人 员 类 型 ","photo":"人脸图片 Base64"},
{"userId":" 用 户 工 号 ","name":" 姓 名 ","userType":" 人 员 类 型 ","photo":"人脸图片 Base64"}
],
"Msg":""
}
待处理数据类别等于 2 的返回结果：
{
"Result":0, "Content"[
{"userId":"用户工号","name":"姓名","delType":"删除类型"},
{"userId":"用户工号","name":"姓名","delType":"删除类型"}
],
"Msg":""
}
说明：Content 内容经过 SM4 加密的，解密后的格式如上示例
数据说明：
待处理数据类别等于 1 的返回结果：
序 号 | 属性 | 类型 | 名称 | 说明 |
1 | userId | string | 用户工号 | |
2 | name | string | 姓名 | |
3 | userType | int | 人员类型 | 详见注册人员类型字典表 |
4 | photo | string | 人脸图片 | Base64 |
待处理数据类别等于 2 的返回结果：
序 号 | 属性 | 类型 | 名称 | 说明 |
1 | userId | string | 用户工号 | |
2 | name | string | 姓名 | |
3 | delType | int | 删除类型 | 详见删除类型字典表 |
RetResult
5.3.3 反馈数据处理结果方法名称
方法说明
设备把数据处理结果反馈给平台，平台根据结果处理任务，任务处理后不能再被获取。
请求方法
POST
URL 地址
https://{API_ROOT}/RetResult
请求参数(x-www-form-urlencoded)
参数名 | 必选 | 类型范围 | 说明 |
sn | 是 | String | 设备序列号 |
id | 是 | String | 任务 id |
result | 是 | Int | 详见反馈结果字典表 |
msg | 否 | String | 失败的时候必须传失败原因 |
timestamp | 是 | String | 当前时间戳（精确到秒），5 分钟内有效 |
sign | 是 | String | 数字签名: 调用 HMAC MD5 算法; 根据提供的密钥（设备密钥）和密文（sn、id、result、msg、timestamp顺序组合）输出 Hex 格式的密文摘要； 密文和密钥的编码字符集使用 UTF8 格式 |
返回结果
参数名 | 必选 | 类型范围 | 说明 |
Result | 是 | int | 详见返回结果字典表 |
Content | 否 | string | 返回内容 |
Msg | 否 | string | 返回消息 |
返回示例
{
"Result":0, "Content":"",
"Msg":""
}
注意事项
失败时必须上传失败原因。
UploadData
5.3.4 上传考勤数据方法名称
方法说明
POST
设备上传考勤数据到平台。请求方法
URL 地址
https://{API_ROOT}/UploadData
请求参数(x-www-form-urlencoded)
参数名 | 必选 | 类型范围 | 说明 |
sn | 是 | String | 设备序列号 |
data | 是 | String | 识别结果 json 加密字符串，经过 SM4 加密 |
timestamp | 是 | String | 当前时间戳（精确到秒），5 分钟内有效 |
sign | 是 | String | 数字签名: 调用 HMAC MD5 算法; 根据提供的密钥（设备密钥）和密文（sn、data、timestamp 顺序组合）输出 Hex 格式的密文摘要； 密文和密钥的编码字符集使用 UTF8 格式。 |
返回结果
参数名 | 必选 | 类型范围 | 说明 |
Result | 是 | int | 详见返回结果字典表 |
Content | 否 | string | 返回内容 |
参数名 | 必选 | 类型范围 | 说明 |
Msg | 否 | string | 返回消息 |
data 示例
[
{"sn":"XXXX","userId":"XXXXX","type":1,"recogTime":"yyyy-Mm-dd HH:mm:SS"},
{"sn":"XXXX","userId":"XXXXX","type":1,"recogTime":"yyyy-Mm-dd HH:mm:SS"}
]
返回示例
{
"Result":0, "Content":"",
"Msg":""
}
数据说明
序 号 | 属性 | 类型 | 名称 | 说明 |
1 | sn | string | 设备序列号 | |
2 | userId | string | 人员工号 | |
3 | type | int | 考勤数据类型 | 详见考勤类型字典表 |
4 | recogTime | datetime | 识别时间 | 格式： yyyy-Mm-dd HH:mm:SS |
注意事项
一次上传识别数据包不大于 10 条。
6.数据字典表
6.1 性别字典表
序号 | 字典数据编码 | 字典数据名称 |
1 | 1 | 男 |
2 | 2 | 女 |
6.2 注册人员类型字典表
序号 | 字典数据编码 | 字典数据名称 |
1 | 采集劳务人员 | |
2 | 采集岗位人员 |
6.3 返回结果字典表
序号 | 字典数据编码 | 字典数据名称 |
1 | 有待处理任务 | |
0 | 成功 | |
-1 | 设备序列号不存在 | |
-2 | 签名不正确 | |
-3 | 数据已失效 | |
-4 | 请求太频繁 | |
-99 | 服务器异常 |
6.4 反馈结果字典表
序号 | 字典数据编码 | 字典数据名称 |
1 | 0 | 成功 |
2 | 1 | 失败 |
6.5 待处理数据类别字典表
序号 | 字典数据编码 | 字典数据名称 |
1 | 删除 | |
2 | 下发 |
6.6 删除类型字典表
序号 | 字典数据编码 | 字典数据名称 |
1 | 离职 | |
2 | 禁入人员 | |
3 | 红码、黄码人员 |
6.7 考勤类型字典表
序号 | 字典数据编码 | 字典数据名称 |
1 | 进场 | |
2 | 离场 |