全国建筑工人管理服务信息平台数据接口标准.docx

资源描述

全国建筑工人管理服务信息平台数据接口标准.docx

《全国建筑工人管理服务信息平台数据接口标准.docx》由会员分享，可在线阅读，更多相关《全国建筑工人管理服务信息平台数据接口标准.docx（91页珍藏版）》请在冰豆网上搜索。

全国建筑工人管理服务信息平台数据接口标准.docx

全国建筑工人管理服务信息平台数据接口标准

附件2

全国建筑工人管理服务信息平台

数据接口标准

（试行）

1概述

1.1简介

全国建筑工人管理服务信息平台数据开放式接口OpenAPI主要为第三方服务商与全国建筑工人管理服务信息平台进行数据交互使用；所有API均基于Post方式请求调用。

1.2基本术语

接口提供方（APIProvider）：

接口的定义和实现者，为接口调用方提供接口合法访问的授权。

接口调用方（APIClient）：

接口的调用者，需要从接口提供方获得所需接口合法访问的授权。

接口端点（APIEndpoint）：

接口的Http资源入口，由一个HttpURL所表示，代表了一个或由参数确定的多个接口的集合。

1.3接口调用方式

POST格式为：

POST

参数列表

参数列表格式为：

参数名1＝参数值1&参数名2＝参数值2……。

参数名称

参数说明

method

由接口提供方指定的接口标识符。

version

由接口提供方指定的接口版本。

注：

Endpoint+method+version决定了接口的语义。

appid

由接口提供方分配给接口调用方的身份标识符。

format

接口返回结果类型:

json

timestamp

调用方时间戳，格式为“4位年+2位月+2位日+2位小时（24小时制）+2位分+2位秒”，用于接口提供方判断调用方的时间，通常约定调用请求的时间戳与接口提供方收到请求的时间差在约定的范围内。

nonce

随机数，由调用方生成，在约定的调用时差范围内不可重复。

sign

签名，按照签名生成算法计算得来。

data

具体的接口方法中的参数实体信息（对象需要转换成JSONString）

请求标准参数

敏感信息（银行卡号，证件号码等）需要加密传输，请使用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×tamp=20160614133300&nonce=321431&sign=23697537dc822216fdded329361f4311ea9f&data={"phone":

["12345678","87654321"],"name":

"zhangsan","age":

100,"address":

{"country":

"china","province":

"chengdu"},"married":

false}

1.4接口响应

统一返回参数结构

参数名称

参数说明

code

处理结果编码（参考下面的“标准错误代码定义”）

message

处理结果消息

data

接口处理完毕返回的数据（请参见具体接口的返回信息）。

返回的Json格式:

{"code":

"0","message":

"","data":

{"phone":

["12345678","87654321"],"name":

"zhangsan"}}

标准Code代码定义

正确

-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":

false}&format=json&method=employee.create&nonce=11223344×tamp=20160614133300&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=20160614133300&version=2.0&appsecret=df23hlir85353gfgd86775jjdh6322

（3）第三步：

将上一步的获得的字符串全部转换为小写。

再进行SHA256加密（SHA25664位），生成的字符串就是验签数据sign。

注意：

SHA256加密哈希值请转换为16进制表示。

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

访问频率限制

OpenAPI对访问过于频繁等情况做了屏蔽处理，针对同一调用方（APIClient）访问同一方法这一级别可以做如下限制:

访问时间间隔不能少于1秒，且不允许并发（即上一次访问还没有返回结果就开始下一次访问）；具体访问限制参数可配置，会根据上线后实际业务数据量和访问频率做优化调整。

1.5接口类型

1.5.1异步处理接口

异步处理接口是指调用之后不会立即返回处理结果，而是返回响应体字段requestSerialCode供后续查询使用。

可通过异步接口调用结果查询进行结果查询，其返回内容可参考每一接口的异步处理结果响应体字段部分，若异步处理结果响应体字段部分没有任何内容，则表明该异步处理不返回任何额外信息，仅需关注异步处理状态即可；上传/修改接口都是异步处理接口；具体流程图如下：

1.5.2同步处理接

同步处理接口是指调用之后立即返回处理结果，查询接口都是同步处理接口；返回的内容在每一查询接口的‘响应体字段’中进行描述。

在具体调用流程图如下：

2接口详细信息

2.1企业

2.1.1上传企业基本信息

接口信息

Endpoint

https:

//{host}/open.api

Method

Corp.Upload

Version

1.0

返回方式

响应体（JSON）

接口说明

上传企业基本信息

输入参数

名称

类型

是否必需

备注

corpCode

string

是

企业统一社会信用代码，如果无统一社会信用代码，则用组织机构代码

corpName

string

是

企业名称

corpType

string

否

单位性质。

参考企业登记注册类型字典表

licenseNum

string

否

工商营业执照注册号

areaCode

string

是

企业注册地区编码。

参考行政区划字典表

address

string

否

企业营业地址

zipCode

string

否

邮政编码

legalMan

string

否

法定代表人姓名

legalManDuty

string

否

法定代表人职务

legaManProTitle

string

否

法定代表人职称

legalManIDCardType

string

否

法定代表人证件类型。

参考人员证件类型字典表

legalManIDCardNumber

string

否

法定代表人证件号码。

AES

regCapital

decimal

否

注册资本（万元）

factRegCapital

decimal

否

实收资本（万元）

capitalCurrencyType

string

否

注册资本币种。

参考币种字典表

registerDate

string

是

注册日期，格式yyyy-MM-dd

establishDate

string

否

成立日期，格式yyyy-MM-dd

officePhone

string

否

办公电话

faxNumber

string

否

传真号码

linkman

string

否

联系人姓名

linkTel

string

否

联系人办公电话

string

否

企业联系邮箱

capitalCurrencyType

string

否

注册资本币种。

参考币种字典表

registerDate

string

是

注册日期，格式yyyy-MM-dd

website

String

否

企业网址

remark

String

否

企业备注

响应体字段

名称

类型

是否必需

备注

requestSerialCode

string

是

请求序列编码

2.1.2查询企业基本信息

接口信息

Endpoint

https:

//{host}/open.api

Method

Corp.Query

Version

1.0

返回方式

响应体（JSON）

接口说明

查询企业信息

输入参数

名称

类型

是否必需

备注

pageIndex

int

是

指定页号，以0为起始数字，表示第1页

pageSize

int

是

每页记录数，最多不能超过50

corpName

string

否

企业名称，与统一社会信用代码必传一个

corpCode

string

否

统一社会信用代码，如果无统一社会信用代码，则用组织机构代码，与企业名称必传一个

响应体字段

名称

类型

是否必需

备注

totalCount

int

是

记录总数

pageIndex

int

是

指定页号，以0为起始数字，表示第1页

pageSize

int

是

每页记录数，最多不能超过50

rows

array

是

记录集合。

JSON数组

rows数组内对象字段

名称

类型

是否必需

备注

corpCode

string

是

企业统一社会信用代码,如果无统一社会信用代码，则用组织机构代码

corpName

string

是

企业名称

corpType

string

否

单位性质。

参考企业登记注册类型字典表

licenseNum

string

否

工商营业执照注册号

areaCode

string

是

企业注册地区编码。

参考行政区划字典表

address

string

否

企业营业地址

zipCode

string

否

邮政编码

legalMan

string

否

法定代表人姓名

legalManDuty

string

否

法定代表人职务

legaManProTitle

string

否

法定代表人职称

legalManIDCardType

string

否

法定代表人证件类型。

参考人员证件类型字典表

legalManIDCardNumber

string

否

法定代表人证件号码。

AES

regCapital

decimal

否

注册资本（万元）

factRegCapital

decimal

否

实收资本（万元）

capitalCurrencyType

string

否

注册资本币种。

参考币种字典表

registerDate

string

是

注册日期，格式yyyy-MM-dd

establishDate

string

否

成立日期，格式yyyy-MM-dd

officePhone

string

否

办公电话

faxNumber

string

否

传真号码

linkman

string

否

联系人姓名

linkTel

string

否

联系人办公电话

string

否

企业联系邮箱

website

String

否

企业网址

remark

String

否

企业备注

2.1.3查询企业资质信息

接口信息

Endpoint

https:

//{host}/open.api

Method

CorpCredential.Query

Version

1.0

返回方式

响应体（JSON）

接口说明

查询企业资质数据

输入参数

名称

类型

是否必需

备注

pageIndex

int

是

指定页号，以0为起始数字，表示第1页

pageSize

int

是

每页记录数，最多不能超过50

corpCode

string

否

统一社会信用代码，如果无统一社会信用代码，则用组织机构代码，与企业名称必填一个

corpName

string

否

企业名称，与统一社会信用代码必填一个

响应体字段

名称

类型

是否必需

备注

totalCount

int

是

记录总数

pageIndex

int

是

指定页号，以0为起始数字，表示第1页

pageSize

int

是

每页记录数，最多不能超过50

rows

array

是

记录集合。

JSON数组

rows数组内对象字段

名称

类型

是否必需

备注

corpCode

string

是

统一社会信用代码，如果无统一社会信用代码，则用组织机构代码

corpName

string

是

企业名称

certTypeNum

int

是

资质资格类型。

参考企业资质资格类型字典表

certID

string

是

证书编号。

AES

tradeBoundNum

int

是

专业类别。

参考企业资质资格专业类别字典表

tradeTypeBoundChildMark

string

否

专业子项

titleLevelNum

int

是

资质资格等级。

参考企业资质等级字典表

mark

string

是

批准资质资格内容。

该资质的打印内容

limitContent

string

否

资质资格限定内容

noteNumber

string

否

首次批准资质资格文号

noteDate

string

是

首次批准资质资格日期

addTypeNum

string

是

资质资格取得方式。

参考资质取得方式字典表

certTradeStatusNum

string

是

资质资格状态。

参考企业资质状态字典表

certTradeModifyDate

string

否

资质资格状态变更时间

certTradeModifyMark

string

否

资质资格状态变更原因。

资质资格降级、暂扣、注销的原因

2.2项目

2.2.1项目基本信息

2.2.1.1上传项目信息

接口信息

Endpoint

https:

//{host}/open.api

Method

Project.Add

Version

1.0

返回方式

响应体（JSON）

接口说明

上传项目信息

输入参数

名称

类型

是否必需

备注

contractorCorpCode

string

是

总承包单位统一社会信用代码，如果无统一社会信用代码，则用组织机构代码

contractorCorpName

string

是

总承包单位名称

name

string

是

项目名称

description

string

否

项目简介