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

1、全国建筑工人管理服务信息平台数据接口标准附件2全国建筑工人管理服务信息平台数据接口标准（试行）1 概述1.1 简介全国建筑工人管理服务信息平台数据开放式接口OpenAPI主要为第三方服务商与全国建筑工人管理服务信息平台进行数据交互使用；所有API均基于Post方式请求调用。1.2 基本术语接口提供方(API Provider)：接口的定义和实现者，为接口调用方提供接口合法访问的授权。接口调用方(API Client)：接口的调用者，需要从接口提供方获得所需接口合法访问的授权。接口端点(API Endpoint)：接口的Http资源入口，由一个Http URL所表示，代表了一个或由参数确定的多个

2、接口的集合。1.3 接口调用方式POST格式为：POST 参数列表 参数列表格式为：参数名1参数值1&参数名2参数值2。参数名称参数说明method 由接口提供方指定的接口标识符。version 由接口提供方指定的接口版本。注：Endpoint+ method+version决定了接口的语义。appid 由接口提供方分配给接口调用方的身份标识符。format 接口返回结果类型:json timestamp 调用方时间戳，格式为“4位年+2位月+2位日+2位小时(24小时制)+2位分+2位秒”，用于接口提供方判断调用方的时间，通常约定调用请求的时间戳与接口提供方收到请求的时间差在约定的范围内。n

3、once 随机数，由调用方生成，在约定的调用时差范围内不可重复。sign 签名，按照签名生成算法计算得来。data 具体的接口方法中的参数实体信息（对象需要转换成JSON String）请求标准参数敏感信息（银行卡号，证件号码等）需要加密传输，请使用AES加密,算法说明:算法密钥=接入密钥KEY,编码=UTF8，加密模式(CipherMode)=CBC，填充模式(PaddingMode)=PKCS7,数据块大小(BlockSize)=128，算法的初始化向量(IV)= 接入密钥KEY的前16位字符，加密后的字节数组转为Base64字符串，需要加密的字段会在字段备注中添加AES标记。算法：密文=

4、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: false1.4 接口响

5、应统一返回参数结构参数名称参数说明code 处理结果编码（参考下面的“标准错误代码定义”）message 处理结果消息data 接口处理完毕返回的数据（请参见具体接口的返回信息）。返回的Json格式: code:0,message:,data: phone:12345678,87654321,name: zhangsan标准Code代码定义 0: 正确 -1: 请求参数错误 -2: 签名校验错误 -3: 无API访问权限 -4: IP校验错误 -5: 访问超过限制 注：标准错误码小于0，大于0的错误码由各接口根据接口语义自行定义接口参数签名方法（1）第一步：拼接参数字符串将除sign以外的请求

6、参数（包括标准参数，除非有特别说明）按照参数名称的字典升序排列，然后按此顺序，将”参数名参数值”用”&”符号连接。示例：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)

7、仅对接口定义中声明且请求参数列表中包含的参数（包括空值）进行签名。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&n

8、once=11223344×tamp=20160614133300&version=2.0&appsecret=df23hlir85353gfgd86775jjdh6322（3）第三步：将上一步的获得的字符串全部转换为小写。再进行SHA256加密（SHA256 64位），生成的字符串就是验签数据sign。注意：SHA256加密哈希值请转换为16进制表示。OpenAPI对验签数据sign进行校验时不区分大小写。访问频率限制OpenAPI对访问过于频繁等情况做了屏蔽处理，针对同一调用方(API Client)访问同一方法这一级别可以做如下限制: 访问时间间隔不能少于1秒，且不允许并发（即

9、上一次访问还没有返回结果就开始下一次访问）；具体访问限制参数可配置，会根据上线后实际业务数据量和访问频率做优化调整。1.5 接口类型1.5.1 异步处理接口异步处理接口是指调用之后不会立即返回处理结果，而是返回响应体字段requestSerialCode供后续查询使用。可通过异步接口调用结果查询进行结果查询，其返回内容可参考每一接口的异步处理结果响应体字段部分， 若异步处理结果响应体字段部分没有任何内容，则表明该异步处理不返回任何额外信息，仅需关注异步处理状态即可；上传/修改接口都是异步处理接口；具体流程图如下：1.5.2 同步处理接同步处理接口是指调用之后立即返回处理结果，查询接口都是同步处

10、理接口；返回的内容在每一查询接口的响应体字段中进行描述。在具体调用流程图如下：2 接口详细信息2.1企业2.1.1 上传企业基本信息接口信息Endpointhttps:/host/open.apiMethodCorp.UploadVersion1.0返回方式响应体(JSON)接口说明上传企业基本信息输入参数名称类型是否必需备注corpCodestring是企业统一社会信用代码，如果无统一社会信用代码，则用组织机构代码corpNamestring是企业名称corpTypestring否单位性质。参考企业登记注册类型字典表licenseNumstring否工商营业执照注册号areaCodestri

11、ng是企业注册地区编码。参考行政区划字典表addressstring否企业营业地址zipCodestring否邮政编码legalManstring否法定代表人姓名legalManDutystring否法定代表人职务legaManProTitlestring否法定代表人职称legalManIDCardTypestring否法定代表人证件类型。参考人员证件类型字典表legalManIDCardNumberstring否法定代表人证件号码。AESregCapitaldecimal否注册资本（万元）factRegCapitaldecimal否实收资本(万元)capitalCurrencyTypestr

12、ing否注册资本币种。参考币种字典表registerDatestring是注册日期，格式yyyy-MM-ddestablishDatestring否成立日期，格式yyyy-MM-ddofficePhonestring否办公电话faxNumberstring否传真号码linkmanstring否联系人姓名linkTelstring否联系人办公电话emailstring否企业联系邮箱capitalCurrencyTypestring否注册资本币种。参考币种字典表registerDatestring是注册日期，格式yyyy-MM-ddwebsiteString否企业网址remarkString否企业

13、备注响应体字段名称 类型 是否必需 备注requestSerialCodestring是请求序列编码2.1.2 查询企业基本信息接口信息Endpointhttps:/host/open.apiMethodCorp.QueryVersion1.0返回方式响应体(JSON)接口说明查询企业信息输入参数名称类型是否必需备注pageIndexint是指定页号，以0为起始数字，表示第1页pageSizeint是每页记录数，最多不能超过50corpNamestring否企业名称，与统一社会信用代码必传一个corpCodestring否统一社会信用代码，如果无统一社会信用代码，则用组织机构代码，与企业名称必

14、传一个响应体字段名称 类型 是否必需 备注totalCountint是记录总数pageIndexint是指定页号，以0为起始数字，表示第1页pageSizeint是每页记录数，最多不能超过50rowsarray是记录集合。JSON数组rows数组内对象字段名称类型是否必需备注corpCodestring是企业统一社会信用代码,如果无统一社会信用代码，则用组织机构代码corpNamestring是企业名称corpTypestring否单位性质。参考企业登记注册类型字典表licenseNumstring否工商营业执照注册号areaCodestring是企业注册地区编码。参考行政区划字典表addre

15、ssstring否企业营业地址zipCodestring否邮政编码legalManstring否法定代表人姓名legalManDutystring否法定代表人职务legaManProTitlestring否法定代表人职称legalManIDCardTypestring否法定代表人证件类型。参考人员证件类型字典表legalManIDCardNumberstring否法定代表人证件号码。AESregCapitaldecimal否注册资本（万元）factRegCapitaldecimal否实收资本(万元)capitalCurrencyTypestring否注册资本币种。参考币种字典表register

16、Datestring是注册日期，格式yyyy-MM-ddestablishDatestring否成立日期，格式yyyy-MM-ddofficePhonestring否办公电话faxNumberstring否传真号码linkmanstring否联系人姓名linkTelstring否联系人办公电话emailstring否企业联系邮箱websiteString否企业网址remarkString否企业备注2.1.3 查询企业资质信息接口信息Endpointhttps:/host/open.apiMethodCorpCredential.QueryVersion1.0返回方式响应体(JSON)接口说明查

17、询企业资质数据输入参数名称 类型 是否必需 备注pageIndexint是指定页号，以0为起始数字，表示第1页pageSizeint是每页记录数，最多不能超过50corpCodestring否统一社会信用代码，如果无统一社会信用代码，则用组织机构代码，与企业名称必填一个corpNamestring否企业名称，与统一社会信用代码必填一个响应体字段名称 类型 是否必需 备注totalCountint是记录总数pageIndexint是指定页号，以0为起始数字，表示第1页pageSizeint是每页记录数，最多不能超过50rowsarray是记录集合。JSON数组rows数组内对象字段名称 类型 是

18、否必需备注corpCodestring是统一社会信用代码，如果无统一社会信用代码，则用组织机构代码corpNamestring是企业名称certTypeNumint是资质资格类型。参考企业资质资格类型字典表certIDstring是证书编号。AEStradeBoundNumint是专业类别。参考企业资质资格专业类别字典表tradeTypeBoundChildMarkstring否专业子项titleLevelNumint是资质资格等级。参考企业资质等级字典表markstring是批准资质资格内容。该资质的打印内容limitContentstring否资质资格限定内容noteNumberstrin

19、g否首次批准资质资格文号noteDatestring是首次批准资质资格日期addTypeNumstring是资质资格取得方式。参考资质取得方式字典表certTradeStatusNumstring是资质资格状态。参考企业资质状态字典表certTradeModifyDatestring否资质资格状态变更时间certTradeModifyMarkstring否资质资格状态变更原因。资质资格降级、暂扣、注销的原因2.2项目2.2.1 项目基本信息2.2.1.1 上传项目信息接口信息Endpointhttps:/host/open.apiMethodProject.AddVersion1.0返回方式响

20、应体(JSON)接口说明上传项目信息输入参数名称 类型 是否必需 备注contractorCorpCodestring是总承包单位统一社会信用代码，如果无统一社会信用代码，则用组织机构代码contractorCorpNamestring是总承包单位名称namestring是项目名称descriptionstring否项目简介categorystring是项目分类。参见项目分类字典表buildCorpNamestring否建设单位名称buildCorpCodestring否建设单位统一社会信用代码，如果无统一社会信用代码，则用组织机构代码builderLicensesarray是施工许可证。JS

21、ON数组buildPlanNumstring否建设用地规划许可证编号。AESprjPlanNumstring否建设工程规划许可证编号。AESareaCodestring是项目所在地。参考行政区划字典表investdecimal否总投资，单位：（万元）buildingAreadecimal否总面积，单位：平方米buildingLengthdecimal否总长度，单位：米startDatestring否开工日期，精确到天，格式：yyyy-MM-ddcompleteDatestring否竣工日期，精确到天，格式：yyyy-MM-ddlinkManstring否联系人姓名linkPhonestring

22、否联系人办公电话prjStatusstring是项目状态。参考项目状态字典表latdecimal否WGS84经度lngdecimal否WGS84纬度addressstring否项目地点approvalNumstring否立项文号approvalLevelNumstring否立项级别。参考立项级别字典表prjSizestring否建设规模。参考建设规模字典表propertyNumstring否建设性质。参考建设性质分类字典表functionNumstring否工程用途。参考工程用途字典表nationNumstring否国籍或地区。参考国籍及地区字典表builderLicenses数组内对象字段名

23、称 类型 是否必需 备注prjNamestring是工程名称builderLicenseNumstring是施工许可证编号。AES响应体字段名称 类型 是否必需 备注requestSerialCodestring是请求序列编码异步处理结果响应体字段名称 类型 是否必需 备注projectCodestring是项目编码2.2.1.2 修改项目信息接口信息Endpointhttps:/host/open.apiMethodProject.UpdateVersion1.0返回方式响应体(JSON)接口说明修改项目信息输入参数名称 类型 是否必需 备注projectCodestring是项目编码nam

24、estring是项目名称descriptionstring否项目简介buildCorpNamestring否建设单位名称buildCorpCodestring否建设单位统一社会信用代码，如果无统一社会信用代码，则用组织机构代码builderLicensesarray是施工许可证。JSON数组buildPlanNumstring否建设用地规划许可证编号。AESprjPlanNumstring否建设工程规划许可证编号。AESareaCodestring是项目所在地。参考行政区划字典表investdecimal否总投资，单位：（万元）buildingAreadecimal否总面积，单位：平方米bui

25、ldingLengthdecimal否总长度，单位：米startDatestring否开工日期，精确到天，格式yyyy-MM-ddcompleteDatestring否竣工日期，精确到天，格式yyyy-MM-ddlinkmanstring否联系人姓名linkPhonestring否联系人办公电话prjStatusstring是项目状态。参考项目状态字典表latdecimal否WGS84经度lngdecimal否WGS84纬度addressstring否项目地点approvalNumstring否立项文号approvalLevelNumstring否立项级别。参考立项级别字典表prjSizest

26、ring否建设规模。参考建设规模字典表propertyNumstring否建设性质。参考建设性质分类字典表functionNumstring否工程用途。参考工程用途字典表nationNumint 否国籍或地区。参考国籍及地区字典表builderLicenses数组内对象字段名称 类型 是否必需 备注prjNamestring是工程名称builderLicenseNumstring是施工许可证编号。AES响应体字段名称 类型 是否必需 备注requestSerialCodestring是请求序列编码异步处理结果响应体字段名称 类型 是否必需 备注projectCodestring是项目编号2.2.1.3 查询项目信息接口信息Endpointhttps:/host/open.apiMethodProject.QueryVersion1.0返回方式响应体(JSON)接口说明查询项目信息输入参数名称 类型 是否必需 备注pageIndexint是指定页号，以0为起始数字，表示第1页pageSizeint是每页记录数，最多不能超过50projectCodestring否项目编码contractorCorpCodestring否总承包统一社会信用代码，如果无统一社会信用代码，则用组织机构代码，与企业名称必传一个contractorCorpNamestring否总承包企业名称，与统