1、1 广州市建设领域管理应用信息平台 建筑工人实名制数据接口标准 2 目录 一、引言 . 1 1.1 编写目的 . 1 1.2 适用范围 . 1 1.3 简称和术语 . 1 二、开发规范 . 2 2.1 通信协议 . 2 2.2 通信安全 . 2 2.3 注意事项 . 3 三、接口说明 . 4 3.1 新增班组 . 4 3.2 修改班组 . 6 3.3 添加班组工人 . 7 3.4 修改班组工人 . 9 3.5 班组工人进退场 .10 四、附录 . 10 4.1 测试环境 .10 4.2 结果码对照表 .11 4.3 工种代码表 .11 4.4 银行代码表 .11 1 一、引言 1.1 编写目的
2、 为实现 广州市建设领域 管理应用信息平台对 项目从业人员实名制管理，考虑到部分项目已经在使用一些商业化实名制管理系统，为避免数据重复登记、减少系统改造成本，特编写本接口文档以供施工企业相关技术人员对接。 1.2 适用范围 本文档的适用对象为接入 广州市建设领域管理应用信息平台的施工企业 技术开发人员、日常维护人员。 1.3 简称和术语 广州市建设领域管理应用信息平台：以下简称“信息平台” 施工企业 ：指依法取得施工企业资质证书，在本市从事建设施工活动的施工总承包企业、专业承包企业和劳务分包企业 2 二、开发规范 2.1 通信协议 采用 HTTP（ 或 HTTPS）协议进行请求和响应的处理。接
3、口请求采用 GET/POST 方式。接口响应返回 JSON 格式的数据。 由 “信息平台” 提供接口地址，企业实名制或考勤系统。 接口请求 URL 地址：详见接口说明。 接口未注明处均使用 UTF-8 编码。 通信过程中涉及的中文或特殊符号的传输，需进行 urlencode 处理。 HTTP（或 HTTPS）请求参数均为字符串。 接口请求需进行签名，详见 2.2 通信安全一节。 2.2 通信安全 为保证数据传输过程中的数据真实性，我们需要对数据进行数字签名，在接收签名数据之后进行签名校验。 “信息 平台”会为施工企业的每个工程分配唯一的 接入编号 和 接入密钥 。签名机制如下： 对 全部有长度
4、限制的传输字段（不包括 NL 类型的字段） 进行签名，将参数名（区分大小写）和参数值（ 需进行 urlencode 处理 ）用“ =”连接， 参数值为空的参数不参与签名 ，参数之间用“ &”连接，格式是： param1=val1¶m2=val2 。 参数组装顺序规则：参数名的字典顺序。 密钥拼接方式为传输参数直接连接密钥，如只有 param1 和 param2 两参数，值分别为 val1 和 val2，密钥为 key，拼接结果为： param1=val1¶m2=val2key。 使用“信息平台”分配的密钥进行 MD5 加密（密钥直接跟在组装好的参数后即可），将值赋给 sign
5、参数。 敏感信息班组编号、身份证图片路径、身份证号、银行卡号、社保号需要加密传输，使用 DES 加密，加密 key 等于接入密钥，加密后的字节码转为 16 进制编码的字符串，并在密文字符串的前面加“ des:”前缀。算法：密文 =”des:” + HEX(DES(idcard, key)，如：身份证号： 5113011990010181111，接入密钥：8c2da4c769828fcfa77aedb690999cf9，密文：des:80cfe03525bb2b8d43d62ff369e95334cd1facfe4bbb800c 3 2.3 注意事项 接口中各项参数当标识是 M 时参数必选，为
6、O 时可选。 接口字段长度分为三种：无限制（ NL），固定长度（ FL），可变长度（ VL）。如果为 FL，则长度必须精确到 FL 后跟随的数字，格式举例 FL14；如果为 VL，则长度在可变范围内即可，如果长度不够，不补空格或其它字符，格式举例 VL30。 接口说明中，若参数字体为红色，请仔细阅读备注说明。 请求返回结果码不为 0 时，需要再次提交 请求。如果结果码大于 0，则需要根据提示信息修改错误后再次提交；如果结果码小于 0，可以间隔一段时间再提交（如：选择间隔 5 分钟、 10 分钟、 30 分钟、 1 小时提交一次，连续 5 次提交不成功时推迟到第二天再提交）。 4 三、接口说明
7、所有 接口响应的返回信息均 以 JSON 字符串形式返回 ， 可以使用 JSON 工具包对其进行解析 。 返回信息具体字段参照接口说明中的响应参数，以下以举例： 处理成功： “resultCode“:0,“resultDesc“:“处理成功 “ 处理失败： “resultCode“:1,“resultDesc“:“签名错误 “ 返回结果码对照见附录 4.2 结果码对照表 。 3.1 新增班组 接口说明 接口描述 施工企业添加班组时调用 请求地址 /smz/team/save 测试请求地址 请求参数 参数 限制 长度 注释 备注 accessNo M FL32 接入编号 “信息平台”为施工企业分
8、配的接入编号 teamCode M VL320 班组编码 工程内部的班组唯一编码，如果班组编码已存在则修改班组。格式：班组长身份证号 + 班组类型代码 ，使用 DES 加密 name M VL40 班组名称 班组命名格式： 班组长姓名 + 班组类型 + “班组” workType M VL32 班组类型 参考附录 4.3 leaderAppointment O VL400 班组长证明书 外网能访问的 URL路径，“信息平台”会自动抓取 leaderIdcard M VL150 工人身份证号 检查工人是否存在的依据 ，使用 DES 加密 leaderName M VL30 工人姓名 leader
9、Sex M FL1 性别 M：男 F：女 leaderNation M VL40 民族 leaderBirthday M FL8 生日 yyyyMMdd 5 leaderAddress M VL400 住址 身份证上的住址 leaderSignOrgan M VL30 签发机关 身份证的签发机关 leaderExpiryStart M FL8 有效期开始日期 身份证有效期开始日期 leaderExpiryEnd O FL8 有效期结束日期 身份证有效期结束日期，为空表示长期 leaderHeadImg O VL400 身份证头像 URL 外网能访问的 URL路径， “信息平台”会自动抓取 le
10、aderIdcardFront O VL1500 身份证正面照 外网能访问的 URL 路径，“信息平台”会自动抓取，使用 DES 加密 leaderIdcardBack O VL1500 身份证反面照 外网能访问的 URL 路径，“信息平台”会自动抓取，使用 DES 加密 leaderCurrentAddress M VL400 常住地址 近期的常住地址 leaderPolitical M FL1 政治面貌 0：党员 1：团员 2：群众 leaderEducation M VL32 文 化程度 本科以上、本科、大专、中专、高中、初中及以下 leaderPhone M VL11 手机号 lead
11、erEmployType M FL1 用工形式 0：固定工人 1：外聘 leaderTechLevel M FL1 技能水平 0：无 (普通 )； 1：初级工； 2：中级工； 3：高级工；4：技师； 5：高级技师 leaderContractCode O VL50 合同编号 施工企业内部的合同编号。 leaderContractFile O VL400 合同附件 外网能访问的 URL路径，“信息平台”会 自动抓取。 leaderCardNum O VL150 工资卡账号 使用 DES 加密 leaderCardBank O VL10 工资卡开户行代码 参考附录 4.4 leaderWorkTy
12、pe M VL32 工种代码 参考附录 4.3 leaderSecurityCode O VL300 社保号 使用 DES 加密 leaderSafetyEdu M FL1 是否参加安全教育 true: 是； false：否 leaderSafetyEduImg O VL400 安全教育图片 外网能访问的 URL路径，“信 息平台”会自动抓取。 leaderBuilderType M FL1 工人类型 0：建筑工匠； 1：建筑产业技术工人； 2：其他 leaderDoDate M FL8 进场日期 yyyyMMdd timestamp M FL17 时间戳 北京时间精确到毫秒 (yyyyMMd
13、dHHmmssSSS) sign M FL32 签名 响应参数 参数 限制 说明 6 resultCode M 返回结果码，数字类型。 0 表示成功；其它表示失败。 resultDesc O 返回结果描述 3.2 修改班组 接口说明 接 口描述 施工企业修改班组时调用 请求地址 /smz/team/update 测试请求地址 请求参数 参数 限制 长度 注释 备注 accessNo M FL32 接入编号 “信息平台”为施工企业分配的接入编号 teamCode M VL320 班组编码 工程内部的班组唯一编码，如果班组编码已存在则修改班组。格式：班组长身份证号 + 班组类型代码，使用 DES
14、加密 name M VL40 班组名称 班组命名格式： 班组长姓名 + 班组类型 + “班组” workType M VL32 班组类型 参考附录 4.3 leaderAppointment O VL400 班组长证明书 外网能访问的 URL路径，“信息平台”会自动抓取 leaderIdcard M VL150 工人身份证号 检查工人是否存在的依据，使用 DES 加密 leaderCurrentAddress M VL400 常住地址 近期的常住地址 leaderPolitical M FL1 政治面貌 0：党员 1：团员 2：群众 leaderEducation M VL32 文化程度 本科
15、以上、本科、大专、中专、高中、初中及以下 leaderPhone M VL11 手机号 leaderEmployType M FL1 用工形式 0：固定工人 1：外聘 leaderTechLevel M FL1 技能水平 0：无 (普通 )； 1：初级工； 2：中级工； 3：高级工；4：技师； 5：高级技师 leaderContractCode O VL50 合同编号 施工企业内部的合同编号。 leaderContractFile O VL400 合同附件 外网能访问的 URL路径，“信息平台”会自动抓取。 leaderCardNum O VL150 工 资卡账号 使用 DES 加密 lead
16、erCardBank O VL10 工资卡开户行代码 参考附录 4.4 leaderWorkType M VL32 工种代码 参考附录 4.3 7 leaderSecurityCode O VL300 社保号 使用 DES 加密 leaderSafetyEdu M FL1 是否参加安全教育 true: 是； false：否 leaderSafetyEduImg O VL400 安全教育图片 外网能访问的 URL路径，“信息平台”会自动抓取。 leaderBuilderType M FL1 工人类型 0：建筑工匠； 1：建筑产业技术工人； 2：其他 timestamp M FL17 时间戳 北京
17、时间精确到毫秒 (yyyyMMddHHmmssSSS) sign M FL32 签名 响应参数 参数 限制 说明 resultCode M 返回结果码，数字类型。 0 表示成功；其它表示失败。 resultDesc O 返回结果描述 3.3 添加班组工人 接口说明 接口描述 为已登记的班组添加工人。 请求地址 /smz/teamBuilder/save 测试请求地址 请求参数 参 数 限制 长度 注释 备注 accessNo M FL32 接入编号 “信息平台”为施工企业分配的接入编号 teamCode M VL320 班组编码 工程内部的班组唯一编码，如果班组编码已存在则修改班组，使用 DE
18、S 加密 idcard M VL150 工人身份证号 检查工人是否存在的依据，如果工人已存在则修改，使用 DES 加密 name M VL30 工人姓名 sex M FL1 性别 M：男 F：女 nation M VL40 民族 birthday M FL8 生日 yyyyMMdd address M VL400 住址 身份证上的住址 signOrgan M VL30 签发机关 身份证的签发机关 8 expiryStart M FL8 有效期开始日期 身份证有效期开始日期 expiryEnd O FL8 有效期结束日期 身份证有效期结束日期，为空表示长期 headImg O VL400 身份证
19、头像 URL 外网能访问的 URL路径，“信息平台”会自动抓取 idcardFront O VL1500 身份证正面照 外网能访问的 URL 路径，“信息平台”会自动抓取，使用 DES 加密 idcardBack O VL1500 身份证反面照 外网能访问的 URL 路径，“信息平台”会自动抓取，使用 DES 加密 currentAddress M VL400 常住地址 近期的常住地址 political M FL1 政治面貌 0：党员 1：团员 2：群众 education M VL20 文化程度 本科以上、本科、大专、中专、高中、初中及以下 phone M VL11 手机号 employT
20、ype M FL1 用工类型 0：自有工人； 1：外聘工人 contractCode O VL50 合同编号 施工企业内部的合同编号。 contractFile O VL400 合同附件 外网能访问的 URL路径，“信息平台”会自动抓取。 cardNum O VL150 工资卡账号 使用 DES 加密 cardBank O VL10 工资卡开户行代码 参考附录 4.4 workType M VL32 工种代码 参考附录 4.3 techLevel M FL1 技能水平 0：无 (普通 )； 1：初级工； 2：中级工； 3：高级工；4：技师； 5：高级技师 securityCode O VL30
21、0 社保号 使用 DES 加密 safetyEdu M FL1 是否参加安全教育 true: 是； false：否 safetyEduImg O VL400 安全教育图片 外网能访问的 URL路径，“信息平台”会自动抓取。 builderType M FL1 工人类型 0：建筑工匠； 1：建筑产业技术工人； 2：其他 doDate M FL8 进场日期 yyyyMMdd timestamp M FL17 时间戳 北京时间精确到毫秒 (yyyyMMddHHmmssSSS) sign M FL32 签名 响应参数 参数 限制 说明 resultCode M 返回结果码，数字类型。 0 表示成功；其它表示失败。 resultDesc O 返回结果描述
