重庆市智建慧筑工人实名制管理OpenApi接口v1.0

重庆市智建筑工人
实名制管理OpenApi接口v1.0  

1. 接口总体说明

1.1. 总体方案

智慧工地平台实名制人员信息采集、考勤与供应商实名制服务关系如下：

工程项目现场统一使用智慧工地app进行人员信息采集，平台提供人员信息下载接口，供各供应商实名制服务应用下载，供应商实名制应用下载后，在其应用中完成人员与考勤介质（如考勤卡，指纹、人脸识别等）绑定，现场人员实际进出场时，供应商实名制应用调用平台接收考勤数据接口，将考勤结果实时上传。

本接口包含实名制人员信息下载接口和实名制人员考勤数据上传接口。

实名制人员信息下载接口每次调用最多返回100行人员记录，同时返回记录总数和当前分页信息，当项目人员信息超过100行人员记录，需要供应商应用根据记录分页信息，分批次调用此接口直至返回该项目所有人员记录。基于安全考虑，下载的人员信息已经过脱敏处理，身份证号使用sha1算法进行加密。

考勤数据上传接口可接收设备直传数据和供应商服务器转发数据，要求设备或供应商服务器在收到考勤数据时，实时上传到平台。

1.2. 通讯方式

数据接口采用HTTP协议，数据格式采用JSON。

1.3. 接口鉴权

1.3.1. 接口说明

智慧工地信息管理平台所有接口的权限认证都采用密钥签名的认证方式，工作原理为：在系统内生成唯一的密钥，颁发给数据采集设备或其他外部系统。外部系统获取密钥对之后妥善保存密钥，在调用接口上传数据时，外部系统使用密钥当前请求进行签名，将签名后的结果放在http请求头部与数据一起发送至监管端的数据采集接口。数据采集接口根据请求头部包含的签名信息查找对应的密钥信息，验证当前请求是否合法。

1.3.2. 签名方法

1.3.2.1. 生成密钥

1.3.2.1.1. 供应商密钥

智慧工地信息管理平台中可以为获得建委授权的设备供应商或软件供应商创建密钥对，密钥主要包括以下信息：

1.3.2.1.2. 项目密钥

获得建委授权的设备供应商或软件供应商可以从项目上获得项目生成的密钥对，密钥主要包括以下信息：

1.3.2.2. 为密钥授权

对设备或软件供应商进行数据授权，指定的密钥可以上传那种类型的数据。模块维度目前包括：环境数据、机械设备数据、视频监控数据三个主要分类。获得环境数据授权后可以上传扬尘、噪音数据；获得机械设备数据授权后可以上传塔吊运行数据、升降机运行数据；获得视频监控数据授权后可以进行视频的在线直播。

1.3.2.3. 为请求签名

在调用数据接口发送数据时，需要使用密钥对请求进行签名，具体签名方式如下所示:

本次示例所用密钥对：

1. 取发送请求时取服务器的UNIX时间戳（服务器时间需要提前与标准时间进行校对），例如：1526438202

2. 生成一个随机字符串，长度至少10位，由英文字符与数字组成，如：jUY9ybWcM3DH，注意随机字符串每次请求都要不同，不要在不同请求中使用相同随机字符串。

3. 使用下划线将随机字符串，时间戳与密钥(供应商密钥在前项目密钥在后)拼接为预处理字符串：

jUY9ybWcM3DH_1526438202_Ny35o694RgXURrNQ7hCBbI4wyearCWxx7H4n_ RMSRvZBhviBiWlddbXil5EqVQhkHJ0WJUbH7

4. 使用sha1 Hash算法对预处理字符串进行加密，得到的结果即为签名后的字符串：e914fed7db86318b6d8ce01a6f7cfe463c929f3d

5. 将密钥的keyId，随机字符串（rCode），计算签名时的UNIX时间戳以及签名放入http请求的头部,格式为：[供应商keyId]_[项目keyId]，与数据一起发送给重庆市两江新区智慧工地信息管理平台数据接口。此时HTTP请求头中包含的签名信息如下：

keyId=e6fe9dd5-58af-11e8-857d-00163e32d704_1b0f28a4-a5a8-4ea8-ae1a-3b80d6e72397（授权id,以下划线连接，供应商的在前，项目的在后）

ts=1526438202（时间戳）

rCode= jUY9ybWcM3DH (随机字符串)

signature= e914fed7db86318b6d8ce01a6f7cfe463c929f3d（密钥签名）

1.3.2.4. 校验签名

接上述例子，平台收到请求后，从请求头部获取到密钥的keyId，随机串，时间戳与签名。平台鉴权计算过程如下：

1. 检查时间戳，如果时间戳小于当前时间60秒（这个值可以根据具体情况设置），则判定请求已过期，丢弃本次请求。

1. 通过密钥的keyId找到对应的密钥，按照2.3所述的方法计算签名。

2. 将计算结果与接种中的签名进行比较，如果相等则说明请求合法。

3. 记录请求日志。

5. 处理请求中上传的数据。

1.3.2.5. 算法特点

密钥签名方式进行接口权限认证主要有以下特点：

l 在整个请求的鉴权过程中，密钥不会随数据一起通过网络进行传输，只有监管端与数据采集与提供方知晓密钥的具体内容，只要不泄露密钥，就能保证数据传输过程的安全。

l 密钥与具体的数据结构无关，即使意外泄露，也只需要双方更新对应的密钥secret值，对已有的数据与接口无任何影响。

l 整个鉴权过程由算法控制，无需保持客户端连接与会话上下文，所有请求都是无状态的，在客户端较多的情况下能够大幅减少服务器的资源消耗，提高系统运行的效率与稳定性。

2. 业务接口说明

2.1. 人员信息下载接口

2.1.1. 接口地址

/api/open/v1/projectWorker

请求方法

GET

2.1.2. 请求内容

URL参数

2.1.3. 返回值

返回值说明：

2.1.4. 错误代码

2.2. 考勤数据上传接口

2.2.1. 接口地址

/api/open/v1/attendance

2.2.2. 请求方法

POST

2.2.3. 请求内容

1. 请求体

请求体数据说明：

2.2.4. 返回值

返回值说明：

2.2.5. 错误代码