广东省建筑工人管理服务信息平台 数据接口标准

附件1 

广东省建筑工人管理服务信息平台

数据接口标准

(V1.3版)

 发布单位:广东省住房和城乡建设厅
发布时间:2022年8月

目  录
1 概述 1
1.1 简介 1

1.2 基本术语 1

1.3 接口调用方式 1

1.4 接口响应 2

1.5 接口类型 4

1.5.1 异步处理接口 4

1.5.2 同步处理接口 4

2 接口详细信息 4

2.1 企业 5

2.1.1 上传企业基本信息 5

2.1.2 查询企业基本信息 8

2.2 项目 10

2.2.1 项目基本信息 10

2.2.2 项目参建单位 20

2.2.3 项目班组 28

2.2.4 项目人员 39

2.2.5 项目人员进退场 48

2.2.6 项目人员合同 51

2.2.7 项目人员考勤 56

2.2.8 项目人员工资 61

2.2.9 项目培训 67

2.2.10新开工项目密钥办理信息 73

2.3 人员 81

2.3.1 查询人员基本信息 81

2.4 异步接口调用结果查询 83

2.4.1 接口信息说明 83

3 数据字典85

3.1 企业登记注册类型字典表 85

3.2 行政区划字典表 86

3.3 人员证件类型字典表 86

3.4 币种字典表 87

3.5 企业资质资格类型字典表 87

3.6 企业资质资格专业类别字典表 88

3.7 企业资质等级字典表 97

3.8 企业资质取得方式字典表 98

3.9 企业资质状态字典 99

3.10 项目分类字典表 99

3.11 项目状态字典表 99

3.12 立项级别字典表 100

3.13 建设规模字典表 100

3.14 建设性质分类字典表 100

3.15 工程用途字典表 101

3.16 国籍及地区字典表 101

3.17 参建单位类型字典表 101

3.18 工人工种字典表 102

3.19 银行代码字典表 104

3.20 是否字典表 112

3.21 合同期限类型字典表 112

3.22 工人考勤方向字典表 112

3.23 工人进退场类型字典表 112

3.24 计量单位类型字典表 113

3.25 工人通行方式字典表 113

3.26 培训类型字典表 113

3.27 性别字典表 114

3.28 政治面貌字典表 114

3.29 文化程度字典表 114

3.30 婚姻状况字典表 115

3.31 人员证书种类字典表 115

3.32 人员证书类型:安管证书专业字典表 115

3.33 人员证书类型:岗位证书专业字典表 115

3.34 人员证书类型:执业注册类别字典表 116

3.35 人员证书类型:执业注册证书专业字典表 117

3.36 人员证书类型:职业技能人员类别 118

3.37 人员资质等级:职称等级 124

3.38 人员资质等级:职业技能等级 124

3.39 资质证书状态字典表 125

3.40 企业不良行为字典表 125

3.41 认定部门级别字典表 140

3.42 市场主体类别字典表 140

3.43 人员不良行为字典表 141

3.44 附件类型字典表 146

3.45 银行卡业务类型字典表 146

3.46 异步处理结果状态字典表 146

3.47 工人类型字典表 147

3.48 管理岗位字典表 147

3.49 民族信息 149

编 制 说 明

本数据接口标准根据住房和城乡建设部主编的《全国建筑工人管理服务信息平台数据对接方案》(V1.2.1版本)进行编制,本接口标准将根据《全国建筑工人管理服务信息平台数据对接方案》的更新情况和我省实名制管理需要,适时进行修改。

本数据接口标准与《全国建筑工人管理服务信息平台数据对接方案》(V1.2.1版本)相比,根据“广东省建筑工人管理服务信息平台”的管理需要,做了如下调整:

一、上传、修改项目信息接口的输入参数增加了“软/硬件供应商名称”;

二、上传、修改项目信息接口的输入参数增加了“场所ID”;

三、上传、修改项目信息接口的输入参数增加了“项目所属部门”;

四、增加“新开工项目密钥办理信息”接口标准(本接口仅为市级实名制管理系统向“广东省建筑工人管理服务信息平台”同步数据使用)。

除以上四点外,接口调用方式、签名算法、字段命名、接口方法命名等均与《全国建筑工人管理服务信息平台数据对接方案》(V1.2.1版本)保持一致。

1 概述

1.1 简介 

本数据接口标准为广东省“一地接入、全省通用”的统一标准,地市用工实名制管理系统应根据本数据接口标准,规范本地市的用工实名制管理系统数据与项目实名制数据的对接接口。同时,地市用工实名制管理系统与广东省建筑工人管理服务信息平台的数据交互也将同步更新。

1.2 基本术语 

接口提供方(API Provider):接口的定义和实现者,为接口调用方提供接口合法访问的授权。 

接口调用方(API Client):接口的调用者,需要从接口提供方获得所需接口合法访问的授权。

接口端点(API Endpoint):接口的 Http 资源入口,由一个 Http URL 所表示,代表了一个或由参数确定的多个接口的集合。 

1.3 接口调用方式 

POST 格式为:POST <API Endpoint>  参数列表。

参数列表格式为:参数名 1=参数值 1&参数名 2=参数值 2……。 

请求标准参数 

敏感信息(银行卡号,证件号码等)需要加密传输,请使用 AES 加密,算法

说明:

算法密钥=接入密钥 KEY, 编码=UTF8,加密模式(CipherMode)=CBC,填充模式(PaddingMode)=PKCS7, 数据块大小(BlockSize)=128, 

算法的初始化向量(IV)= 接入密钥 KEY 的前 16 位字符,加密后的字节数组转为 Base64 字符串,需要加密的字段会在字段备注中添

加‘AES’标记。算法:密文=Base64(AES(info, KEY))。 

例如:  

RequestBody:  method=employee.create&format=json&version=1.0&appid=appcode123&tim estamp=20160614133300&nonce=321431&sign=23697537dc822216fdded329361f4

311ea9f&data={"phone": ["12345678","87654321"],"name": "zhangsan","age":

100,"address": {"country": "china","province": "chengdu"},"married": false}

1.4 接口响应 

统一返回参数结构 

返回的 Json 格式:  

{"code":"0","message":"","data":{ "phone":["12345678","87654321"],"name":

"zhangsan"}}

标准 Code 代码定义  

0: 正确  

-1: 请求参数错误  

-2: 签名校验错误  

-3: 无 API 访问权限  

-4: IP 校验错误  -5: 访问超过限制  

注:标准错误码小于 0,大于 0 的错误码由各接口根据接口语义自行定义 

接口参数签名方法

(1)第一步:拼接参数字符串 

将除 sign 以外的请求参数(包括标准参数,除非有特别说明)按照参数名称的字典升序排列,然后按此顺序,将“参数名=参数值”用“&”符号连接。

示例: 

appid=appcode123&data={"phone":["12345678","87654321"],"name": "zhangsan","age":30,"address":{"country":"china","province":"chengdu"},"married":f alse}&format=json&method=employee.create&nonce=11223344×tamp=20160

614133300&version=2.0

注意事项: 

1) data 参数必须转换为 JSON 格式的字符串。 

2) 仅对接口定义中声明且请求参数列表中包含的参数(包括空值)进行签名。 

3)参数值不作去除空格。

(2)第二步:在拼接参数字符串后再拼接&appsecret,如&appsecret=df23hlir85353;appsecret 即密钥,由广东省建筑工人管理服务信息平台技术支持人员提供。 

示例: 

appid=appcode123&data={"phone":["12345678","87654321"],"name":

"zhangsan","age":100,"address":{"country":"china","province":"chengdu"},"married"

:false}&format=json&method=employee.create&nonce=11223344×tamp=2016

0614133300&version=2.0&appsecret=df23hlir85353gfgd86775jjdh6322

(3)第三步:将上一步的获得的字符串全部转换为小写。再进行 SHA256 加密(SHA256 64 位),生成的字符串就是验签数据 sign。注意:SHA256 加密哈希值请转换为 16 进制表示。 

OpenAPI 对验签数据 sign 进行校验时不区分大小写。 

访问频率限制 

OpenAPI 对访问过于频繁等情况做了屏蔽处理,针对同一调用方(API Client) 访问同一方法这一级别可以做如下限制: 访问时间间隔不能少于 1 秒,且不允许并发(即上一次访问还没有返回结果就开始下一次访问);具体访问限制参数可配置,会根据上线后实际业务数据量和访问频率做优化调整。 

1.5 接口类型 

1.5.1异步处理接口

异步处理接口是指调用之后不会立即返回处理结果,而是返回响应体字段 requestSerialCode供后续查询使用。可通过异步接口调用结果查询进行结果查询,其返回内容可参考每一接口的异步处理结果响应体字段部分, 若异步处理结果响应体字段部分没有任何内容,则表明该异步处理不返回任何额外信息,仅需关注异步处理状态即可;上传/修改接口都是异步处理接口。

1.5.2同步处理接口

同步处理接口是指调用之后立即返回处理结果,查询接口都是同步处理口;

返回的内容在每一查询接口的‘响应体字段’中进行描述。