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