四川省建筑工人管理服务信息平台数据共享交换接口标准试行模板.docx

四川省建筑工人管理服务信息平台数据共享交换接口标准试行模板.docx

《四川省建筑工人管理服务信息平台数据共享交换接口标准试行模板.docx》由会员分享，可在线阅读，更多相关《四川省建筑工人管理服务信息平台数据共享交换接口标准试行模板.docx（36页珍藏版）》请在冰豆网上搜索。

四川省建筑工人管理服务信息平台数据共享交换接口标准试行模板

四川省建筑工人管理服务信息平台

数据共享交换接口标准

（试行）

四川省住房和城乡建设厅

2018年9月

1接口说明1

1.1实名核验接口1

1.2数据上报接口1

2接口方式2

2.1REST风格2

2.2公共参数2

2.2.1请求公共参数2

2.2.2返回公共参数3

2.2.3错误信息结构3

2.3访问控制4

2.4数据加密4

3接口流程4

4接口API6

4.1安全会话接口6

4.1.1security/login6

4.1.2security/logout8

4.2实名制验证接口9

4.2.1Verification/enterprise9

4.2.2Verification/personnel10

4.2.3Verification/project12

4.2.4Verification/getProjectCode14

4.2.5Verification/getDeviceCode14

4.2.6Verification/getProjectPayCode16

4.2.7Verification/retVeriInfo17

4.3实名制数据上报接口18

4.3.1Post/enterprise18

4.3.2Post/personnel19

4.3.3Post/project20

4.3.4Post/projectAttend22

4.3.5Post/projectEntryExit23

4.3.6Post/projectPay24

4.3.7Post/projectMechanics25

4.3.8Post/projectAppraise26

4.3.9Post/retUpInfo27

5接口内容28

5.1企业实名核验28

5.2建筑工人实名核验29

5.3项目信息申报核验29

5.4项目数据上报29

5.4.1项目信息上报30

5.4.2考勤信息上报31

5.4.3进退场信息上报31

5.4.4工资信息上报31

5.4.5现场机械上报32

5.4.6工人评价上报32

5.5企业数据上报32

5.6人员数据上报33

6接口验证33

6.1实名核验规则33

6.1.1企业实名核验规则33

6.1.2建筑工人实名核验规则34

6.1.3项目信息核验规则34

6.2信息上报验证规则34

6.2.1项目数据上报验证规则34

6.2.2企业数据上报验证规则34

6.2.3人员数据上报验证规则35

1接口说明

四川省建筑工人管理服务信息平台提供“实名核验接口”、“数据上报接口”两大类开放式服务接口。

1.1实名核验接口

1）企业实名核验接口：

通过接口API提交企业实名认证资料，省级建筑工人管理服务信息平台对企业基础信息进行校验，通过后返回企业实名核验码；

2）建筑工人实名核验接口：

通过接口API建筑工人实名认证资料，省级建筑工人管理服务信息平台对建筑工人身份进行校验，通过后返回建筑工人实名核验码；

3）项目信息申报核验接口：

通过接口API申请项目编码，提交项目基本资料，省级建筑工人管理服务信息平台对项目基本信息进行校验，通过后返回项目核验码。

1.2数据上报接口

1）项目数据上报接口：

通过项目信息上报、考勤信息上报、进退场信息上报、工资信息上报、现场机械上报、工人评价上报等六个接口API分别上报项目信息、参建单位信息、项目班组信息、管理人员信息、工人培训信息、考勤记录信息、工人及班组进退场记录、工人工资信息、施工现场机械信息、建筑工人诚信评价信息等数据，省级建筑工人管理服务信息平台进行数据更新和存储；

2）企业数据上报接口：

通过接口API上报企业基本信息、企业资质证书信息、企业资质信息等数据，省级建筑工人管理服务信息平台进行数据更新和存储；

3）人员数据上报接口：

通过接口API上报人员实名信息、人员证书信息等数据，省级建筑工人管理服务信息平台进行数据更新和存储。

2接口方式

2.1REST风格

建筑工人实名制数据接口API按照REST风格设计，通过HTTP协议的GET方法或POST方法提交请求。

使用GET方法，请求参数通过URL查询参数（QueryParam）提供。

使用POST方法，请求公共参数通过URL查询参数（QueryParam）提供，接口专用参数通过请求正文（Body）、按照JSON格式封装提供。

2.2公共参数

建筑工人实名制数据接口API的请求和返回均包含规定的公共参数，如无特殊说明，所有接口方法都包含以下请求公共参数以及返回公共参数。

2.2.1请求公共参数

参数名

必选

类型范围

说明

access_token

是

String

访问令牌。

成功调用login接口后返回

sign

否

String

请求参数签名值（预留）

signCert

否

String

签名证书序列号

sign_method

否

String

签名方法（预留）

timestamp

否

Date

应用程序发出请求的客户端时间。

平台在接收到请求后，会与当前服务端时间比较，如果在误差范围大于10分钟，将请求视为无效

request_id

否

String

应用程序发出请求的唯一标识号。

平台如果在误差时间内接收到多个request_id相同的请求，除最早收到的一个请求外，其它请求将视为重放攻击而被忽略

2.2.2返回公共参数

参数名

必选

类型范围

说明

ack_code

是

String

接口调用是否成功

SUCCESS：

成功

FAILURE：

失败

errors

否

List

错误信息

sign

否

String

请求参数签名值（预留）

sign_method

否

String

签名方法（预留）

timestamp

否

Date

接口响应的服务端时间

correlation_id

否

String

对应的请求request_id。

如果请求提供了request_id参数，在响应时会原样返回

response_id

否

String

接口返回的唯一标识号

2.2.3错误信息结构

Error类

属性

类型

长度

可空

说明

code

String

10

否

错误代码

message

String

4000

否

错误信息描述

inner_code

String

50

是

内部代码

2.3访问控制

接入单位通过接口只允许上报指定行政区划范围内的数据，每用户并发请求数目必须小于10r/s，即用户1s内最多请求10次，超过则拒绝访问。

2.4数据加密

敏感信息（银行卡号，证件号码等）需要加密传输，请使用AES加密,算法说明:

算法密钥=接入密钥KEY,

编码=UTF-8，

加密模式（CipherMode）=CBC，

填充模式（PaddingMode）=PKCS7,

数据块大小（BlockSize）=128，

算法的初始化向量（IV）=接入密钥KEY的前16位字符。

加密后的字节数组转为Base64字符串，需要加密的字段会在字段备注中添加‘AES’标记。

算法：

密文=Base64（AES（info,KEY））。

3接口流程

接口API调用流程分为三个步骤：

第一步：

调用login创建安全会话获取access_token

调用安全会话接口的login方法，以创建会话获取访问令牌access_token。

请求示例

POSThttps:

//{API_ROOT}/security/login

Content-Type:

application/json

{"app_key":

"APP_KEY","app_secret":

"APP_SECRET","account":

"ACCOUNT","password":

"PASSWORD"}

返回结果

{"ack_code":

"SUCCESS","errors":

[],"access_token":

"ACCESS_TOKEN","expires_in":

"86400"}

第二步：

使用access_token调用接口API

把access_token作为请求的公共参数来调用建筑工人实名制接口API。

请求示例

GEThttps:

//{API_ROOT}/security/get_current_user?

access_token=ACCESS_TOKEN

返回结果

{

  "ack_code":

"SUCCESS"

  ,"errors":

[]

  ,"data":

    {

    "account":

"sc_wjl"

    ,"name":

"xxxxx用户"

    ,"identity_num":

"440102************"

    ,"division":

"XX市"

    ,"division_code":

"510000xxx

    ,"service_org":

"*********"

    ,"creator":

"admin"

    ,"creation_time":

"2018-5-22"

    ,"last_modificator":

"admin"

    ,"last_modification_time":

"2020-5-22"

    }

}

第三步：

调用logout注销会话

调用安全会话接口的logout方法，设置access_token为无效。

请求示例

POSThttps:

//{API_ROOT}/security/logout?

access_token=ACCESS_TOKEN

Content-Type:

application/json

返回结果

{"ack_code":

"SUCCESS","errors":

[]}

4接口API

4.1安全会话接口

4.1.1security/login

方法名称

login

方法说明

通过用户名和密码进行身份验证，验证成功后创建一个会话。

所有对数据和附件的管理操作都必须在有效的会话内进行，因此创建会话是接口系统调用的第一个方法。

请求方法

POST

URL地址

https:

//{API_ROOT}/security/login

访问权限

所有合法第三方程序。

请求参数

参数名

必选

类型范围

说明

app_key

是

String

分配给应用程序的app_key

app_secret

是

String

分配给应用程序的app_secret

account

是

String

用户账户名称

password

是

String

用户账户密码

org_code

否

String

管理员身份登录

返回结果

参数名

必选

类型范围

说明

access_token

是

String

登录成功则返回安全会话访问令牌

expires_in

是

Integer

访问令牌超时时间（以秒为单位），缺省24小时

请求示例

POSThttps:

//{API_ROOT}/security/login

Content-Type:

application/json

{

  "app_key":

"APP_KEY"

  "app_secret":

"APP_SECRET"

  "account":

"test_gd_jkc"

  "password":

"abc123"

}

返回示例

{

  "ack_code":

"SUCCESS"

  ,"errors":

[]

  ,"access_token":

"ACCESS_TOKEN"

  ,"expires_in":

"86400"

}

注意事项

无

4.1.2security/logout

方法名称

logout

方法说明

注销当前会话。

请求方法

POST

URL地址

https:

//{API_ROOT}/security/logout

访问权限

所有已登录用户。

请求参数

无

请求示例

POSThttps:

//{API_ROOT}/security/logout?

access_token=ACCESS_TOKEN

Content-Type:

application/json

{

}

返回示例

{

  "ack_code":

"SUCCESS"

  ,"errors":

[]

}

注意事项

无

4.2实名制验证接口

4.2.1Verification/enterprise

方法名称

enterprise

方法说明

提交验证企业实名制信息，返回取信息号码。

请求方法

GET

URL地址

https:

//{API_ROOT}/Verification/enterprise

访问权限

所有已登录用户。

请求参数

参数名

必选

类型范围

说明

CompanyName

是

String

企业名称

SocialCreditNumber

是

String

社会统一信用代码

RepresentativeName

是

String

法定代表人姓名

CellPhone

是

String

法定代表人手机号

Status

是

String

企业经营状态

返回结果

{

  "ack_code":

"SUCCESS"

"ID":

"取信息号码"

  ,"errors":

[]

}

请求示例

POSThttps:

//{API_ROOT}/Verification/enterprise?

access_token=ACCESS_TOKEN

Content-Type:

application/json

{

"CompanyName":

"公司名"

"SocialCreditNumber":

"社会统一信用代码"

"RepresentativeName":

"法定代表人姓名"

"CellPhone":

"法定代表人电话号码"

"Status":

"企业经营状态"

}

4.2.2Verification/personnel

方法名称

personnel

方法说明

提交验证人员实名制信息，返回取信息号码。

请求方法

GET

URL地址

https:

//{API_ROOT}/Verification/personnel

访问权限

所有已登录用户。

请求参数

参数名

必选

类型范围

说明

PersonName

是

String

人员姓名

Mobile

是

String

手机号码

IDCardType

是

String

证件类型

IDCardNumber

是

String

证件号码（AES）

CardFront

是

String

身份证正面照片Base64（传入）

CardBack

是

String

身份证背面照片Base64（传入）

PensonAndCard

是

String

手持身份证照片Base64（传入）

ProfilePhoto

是

String

默认头像Base64（传入）

返回结果

{

  "ack_code":

"SUCCESS"

"ID":

"取信息号码"

  ,"errors":

[]

}

请求示例

POSThttps:

//{API_ROOT}/Verification/personnel?

access_token=ACCESS_TOKEN

Content-Type:

application/json

{

"WorkerName":

"人员姓名"

"Mobile":

"手机号码"

"IDCardType":

"证件类型"

"IDCardNumber":

"证件号码"

"CardFront":

"身份证正面照片Base64编码"

"CardBack":

"身份证背面照片Base64（传入）"

"PensonAndCard":

"手持身份证照片Base64（传入）"

"ProfilePhoto":

"默认头像Base64（传入）"

}

4.2.3Verification/project

方法名称

personnel

方法说明

提交项目申报核验信息，返回取信息号码。

请求方法

GET

URL地址

https:

//{API_ROOT}/Verification/project

访问权限

所有已登录用户。

请求参数

参数名

必选

类型范围

说明

ProjectCode

是

String

项目编码

ProjectName

是

String

项目名称

ProjectCategory

是

String

项目类别

OwnerName

是

String

建设单位名称

BuildCorporationCode

是

String

建设单位统一社会信用代码

AreaCode

是

String

项目所在地

Address

是

String

项目位置

Invest

是

String

项目投资额

PrjSize

是

String

项目规模

StartDate

是

String

开工日期

CompleteDate

是

String

拟竣工日期

PrjStatus

是

String

项目状态

返回结果

{

  "ack_code":

"SUCCESS"

"ID":

"取信息号码"

  ,"errors":

[]

}

请求示例

POSThttps:

//{API_ROOT}/Verification/project?

access_token=ACCESS_TOKEN

Content-Type:

application/json

{

"ProjectCode":

"项目编码"

"ProjectName":

"项目名称"

"ProjectCategory":

"项目类别"

"AreaCode":

"项目所在地"

…….

}

4.2.4Verification/getProjectCode

方法名称

getProjectCode

方法说明

申请项目编码，返回项目编码。

请求方法

GET

URL地址

https:

//{API_ROOT}/Verification/getProjectCode

访问权限

所有已登录用户。

请求参数

无

返回结果

{

  "ack_code":

"SUCCESS"

 ,"ProjectCode":

"项目编码"  ,"errors":

[]

}

请求示例

POSThttps:

//{API_ROOT}/Verification/getProjectCode?

access_token=ACCESS_TOKEN

4.2.5Verification/getDeviceCode

方法名称

getDeviceCode

方法说明

申请人员信息采集设备编码，返回设备编码。

请求方法

GET

URL地址

https:

//{API_ROOT}/Verification/getDeviceCode

访问权限

所有已登录用户。

请求参数

参数名

必选

类型范围

说明

ProjectCode

是

String

项目编码

DeviceType

是

String

类型

DeviceBrand

是

String

设备品牌

DeviceModel

是

String

设备型号

DeviceSN

是

String

设备序号

DeviceHardwareSN

是

String

设备硬件唯一编号

返回结果

{

  "ack_code":

"SUCCESS"

 ,"DeviceCode":

"设备编码"  ,"errors":

[]

}

请求示例

POSThttps:

//{API_ROOT}/Verification/getDeviceCode?

access_token=ACCESS_TOKEN

Content-Type:

application/json

{

"ProjectCode":

"项目编码"

"DeviceType":

"类型"

"DeviceBrand":

"设备品牌"

"DeviceModel":

"设备型号"

"DeviceSN":

"设备序号"

"DeviceHardwareSN":

"设备硬件唯一编号"

}

4.2.6Verification/getProjectPayCode

方法名称

getProjectPayCode

方法说明

申请工资单编码，返回工资单编码。

请求方法

GET

URL地址

https:

//{API_ROOT}/Verification/getProjectPayCode

访问权限

所有已登录用户。

请求参数

无

返回结果

{

  "ack_code":

"SUCCESS"

 ,"ProjectPayCode":

"工资单编码"  ,"errors":

[]

}

请求示例

POSThttps:

//{API_ROOT}/Verification/getProjectPayCode?

access_token=ACCESS_TOKEN

4.2.7Verification/retVeriInfo

方法名称

RetVeriInfo

方法说明

传入取信息号码，获取实名制验证结果。

请求方法

GET

URL地址

https:

//{API_ROOT}/Verification/RetVeriInfo

访问权限

所有已登录用户。

请求参数

参数名

必选

类型范围

说明

ID

是

String

取信息号码

VeriType

是

String

验证类型:

enterprise：

企业实名制验证

personnel：

个人实名制验证

project：

项目信息制验证

返回结果

{  

"ack_code":

"SUCCESS"

 ,"datas":

[]

  ,"errors":

[]

}

请求示例

POSThttps:

//{API_ROOT}/Verification/RetVeriInfo?

access_token=ACCESS_TOKEN

Content-Type:

application/json

{

"ID":

"项目编号"

，"VeriType":

"验证类型"

}

4.3实名制数据上报接口

4.3.1Post/enterprise

方法名称

enterprise

方法说明

上报企业信息，返回