广州建设领域管理应用信息平台.docx
《广州建设领域管理应用信息平台.docx》由会员分享，可在线阅读，更多相关《广州建设领域管理应用信息平台.docx（27页珍藏版）》请在冰豆网上搜索。
广州建设领域管理应用信息平台
广州市建设领域管理应用信息平台
银行对账单数据接口标准
目录
一、引言1
1.1编写目的1
1.2适用范围1
1.3简称1
二、开发规范2
2.1通信协议2
2.2通信安全2
2.3注意事项2
三、接口说明4
3.1进账上报4
3.2出账上报5
3.3出账结果上报6
3.4获取班组信息6
3.5获取工人实名信息7
3.6工资表上报8
3.7工资款拨出验证9
3.8工资款拨出上报10
3.9工资专用账户开户验证11
3.10工资专用账户开户上报11
3.11工资专用账户变更销户验证13
3.12工资专用账户销户验证13
3.13工资专用账户销户上报14
四、附录15
4.1测试环境15
4.2结果码对照表15
4.3银行代码表16
4.4企业类型表16
4.5出账上报流程16
4.6调用示例17
一、引言
1.1编写目的
为实现广州市建设领域管理应用信息平台对工人工资支付分账专用账户的监督管理，及时对工人工资支付分账专用账户的异常情况进行预警，需要银行配合将工人工资支付分账专用账户的动账明细数据上报，特编写本接口文档以供银行相关技术人员对接。
1.2适用范围
本文档的适用对象为接入广州市建设领域管理应用信息平台的银行技术开发人员、日常维护人员。
1.3简称
广州市建设领域管理应用信息平台：
以下简称“信息平台”
工人工资支付分账专用账户：
以下简称“专用账户”
二、开发规范
2.1通信协议
●采用HTTP（或HTTPS）协议进行请求和响应的处理。
接口请求采用GET/POST方式。
接口响应返回JSON格式的数据。
●由“信息平台”提供接口地址，银行调用。
●接口请求URL地址：
详见接口说明。
●接口未注明处均使用UTF-8编码。
●通信过程中涉及的中文或特殊符号的传输，需进行urlencode处理。
●HTTP（或HTTPS）请求参数均为字符串。
●接口请求需进行签名，详见2.2通信安全一节。
2.2通信安全
为保证数据传输过程中的数据真实性，我们需要对数据进行数字签名，在接收签名数据之后进行签名校验。
银行接入时，“信息平台”会为银行分配唯一的接入编号和接入密钥。
签名机制如下：
●对全部有长度限制的传输字段（不包括NL类型的字段）进行签名，将参数名（区分大小写）和参数值（需进行urlencode处理）用“=”连接，参数值为空的参数不参与签名，参数之间用“&”连接，格式是：
param1=val1¶m2=val2…。
●参数组装顺序规则：
参数名的字典顺序。
●密钥拼接方式为传输参数直接连接密钥，如只有param1和param2两参数，值分别为val1和val2，密钥为key，拼接结果为：
param1=val1¶m2=val2key。
●使用“信息平台”分配的密钥进行MD5加密（密钥直接跟在组装好的参数后即可），将值赋给sign参数。
2.3注意事项
●接口中各项参数当标识是M时参数必选，为O时可选。
●接口字段长度分为三种：
无限制（NL），固定长度（FL），可变长度（VL）。
如果为FL，则长度必须精确到FL后跟随的数字，格式举例FL14；如果为VL，则长度在可变范围内即可，如果长度不够，不补空格或其它字符，格式举例VL30。
●接口中资金数额参数（如交易金额、余额等）均为非负整数，以分为单位。
●接口说明中，若参数字体为红色，请仔细阅读备注说明。
●请求返回结果码不为0时，需要再次提交请求。
如果结果码大于0，则需要根据提示信息修改错误后再次提交；如果结果码小于0，可以间隔一段时间再提交（如：
选择间隔5分钟、10分钟、30分钟、1小时提交一次，连续5次提交不成功时推迟到第二天再提交）。
三、接口说明
●所有接口响应的返回信息均以JSON字符串形式返回，可以使用JSON工具包对其进行解析。
●返回信息具体字段参照接口说明中的响应参数，以下以举例：
处理成功：
{"resultCode":
0,"resultDesc":
"处理成功","data":
{"transactionNo":
"JZ20170601143015345001"}}
处理失败：
{"resultCode":
1,"resultDesc":
"签名错误","data":
{"transactionNo":
"JZ20170601143015345001"}}
●返回结果码对照见附录4.2结果码对照表。
3.1进账上报
接口说明
接口描述
发生导致“专用账户”余额增加的交易时上报数据
请求地址
/bank/incomeRecord/save
测试请求地址
请求参数
参数
限制
长度
注释
备注
bankId
M
FL8
接入编号
“信息平台”为银行分配的接入编号
transactionNo
M
VL32
交易号
请求的唯一交易号
transactionTime
M
FL17
交易记账时间
北京时间精确到毫秒（yyyyMMddHHmmssSSS）
specialAccount
M
VL25
“专用账户”号
amount
M
VL16
交易金额
交易金额，非负整数并以分为单位
balance
M
VL16
余额
“专用账户”余额，非负整数并以分为单位
srcAccount
O
VL20
资金来源账户号
为空表示现金入账
srcName
O
VL200
资金来源账户名
remarks
O
VL500
备注
备注
sign
M
FL32
签名
响应参数
参数
限制
说明
resultCode
M
返回结果码，数字类型。
0表示成功；其它表示失败。
resultDesc
O
返回结果描述
data
O
交易号
3.2出账上报
接口说明
接口描述
发生导致“专用账户”余额减少的交易时上报数据
请求地址
/bank/paymentRecord/save
测试请求地址
请求参数
参数
限制
长度
注释
备注
bankId
M
FL8
接入编号
“信息平台”为银行分配的接入编号
transactionNo
M
VL32
交易号
请求的唯一交易号
transactionTime
M
FL17
交易记账时间
北京时间精确到毫秒（yyyyMMddHHmmssSSS）
specialAccount
M
VL25
“专用账户”号
amount
M
VL16
交易金额
交易金额，非负整数并以分为单位
balance
M
VL16
余额
“专用账户”余额，非负整数并以分为单位
destAccount
M
VL20
资金到达账户号
destIdcard
O
VL18
账户身份证号
资金到达账户的拥有人的身份证号
destName
M
VL30
账户名
资金到达账户的拥有人的姓名
state
M
FL1
到账结果状态
0：
已出账；1：
已到账；-1：
已退款
remarks
O
VL500
备注
备注
sign
M
FL32
签名
响应参数
参数
限制
说明
resultCode
M
返回结果码，数字类型。
0表示成功；其它表示失败。
resultDesc
O
返回结果描述
data
O
交易号
3.3出账结果上报
接口说明
接口描述
上报出账的到账结果
请求地址
/bank/paymentRecord/result
测试请求地址
请求参数
参数
限制
长度
注释
备注
bankId
M
FL8
接入编号
“信息平台”为银行分配的接入编号
transactionNo
M
VL32
交易号
请求的唯一交易号
specialAccount
M
VL25
“专用账户”号
state
M
FL1
到账结果状态
0：
已出账；1：
已到账；-1：
已退款
finishTime
M
FL17
到账结果反馈时间
北京时间精确到毫秒（yyyyMMddHHmmssSSS）
remarks
O
VL500
备注
备注
sign
M
FL32
签名
响应参数
参数
限制
说明
resultCode
M
返回结果码，数字类型。
0表示成功；其它表示失败。
resultDesc
O
返回结果描述
data
O
交易号
3.4获取班组信息
接口说明
接口描述
批量获取与指定的“专用账户”绑定的班组信息。
用于银行系统在提供给企业制作工资表时选择班组。
请求地址
/bank/team/list
测试请求地址
请求参数
参数
限制
长度
注释
备注
bankId
M
FL8
接入编号
“信息平台”为银行分配的接入编号
specialAccount
M
VL25
“专用账户”号
timestamp
M
FL17
时间戳
北京时间精确到毫秒（yyyyMMddHHmmssSSS）
sign
M
FL32
签名
响应参数
参数
限制
说明
resultCode
M
返回结果码，数字类型。
0表示成功；其它表示失败。
resultDesc
O
返回结果描述
data
O
班组列表。
格式为JSON对象：
[{
code:
‘班组编码’,
name:
‘班组名称’
}]
3.5获取工人实名信息
接口说明
接口描述
批量获取与指定的“专用账户”绑定的工人实名信息。
银行在提供给企业发放工资时可以获取此列表用于工资发放依据，不在此列表中的账户不能发放工资，工资发放数额不能超过未支付的工资数。
请求地址
/bank/teamBuilder/page
测试请求地址
请求参数
参数
限制
长度
注释
备注
bankId
M
FL8
接入编号
“信息平台”为银行分配的接入编号
specialAccount
M
VL25
“专用账户”号
teamCode
M
VL32
班组编码
项目内部的班组唯一编码，检查班组是否存在的依据
page
M
VL5
页码
获取的页码，从0开始
size
M
VL4
每页的数据条数
timestamp
M
FL17
时间戳
北京时间精确到毫秒（yyyyMMddHHmmssSSS）
sign
M
FL32
签名
响应参数
参数
限制
说明
resultCode
M
返回结果码，数字类型。
0表示成功；其它表示失败。
resultDesc
O
返回结果描述
data
O
工人列表。
格式为JSON对象：
{
number:
‘页码’,
size:
‘每页的数据条数’,
content:
[{
name:
‘工人姓名’,
idcard:
‘工人身份证号’,
cardCode:
‘工人银行卡号’,
bankCode:
‘工人银行卡开户行代码，参见附录4.3’,
cardChecked:
‘银行卡是否验证’
}]
}
3.6工资表上报
接口说明
接口描述
企业提交工资表给银行发放完工资后上报工资表数据。
请求地址
/bank/wage/save
测试请求地址
请求参数
参数
限制
长度
注释
备注
bankId
M
FL8
接入编号
“信息平台”为银行分配的接入编号
specialAccount
M
VL25
“专用账户”号
teamCode
M
VL32
班组编码
项目内部的班组唯一编码，检查班组是否存在的依据
month
M
FL6
工资月份
yyyyMM
builders
M
NL
工人工资列表
不参与签名。
json格式的数据：
{
idcard:
‘工人身份证号’,
shouldWages:
‘应发工资，非负整数并以分为单位’,
realWages:
‘实发工资，非负整数并以分为单位’,
transactionNo:
‘发放流水交易号’,
creatime:
‘交易时间，北京时间精确到秒（yyyyMMddHHmmss）’,
remarks:
‘备注’
}
timestamp
M
FL17
时间戳
北京时间精确到毫秒（yyyyMMddHHmmssSSS）
sign
M
FL32
签名
响应参数
参数
限制
说明
resultCode
M
返回结果码，数字类型。
0表示成功；其它表示失败。
resultDesc
O
返回结果描述
3.7工资款拨出验证
接口说明
接口描述
获取工资专用账户可拨出的账户。
用于企业在银行系统拨出工资款时选择可拨出的工资专用账户。
请求地址
/bank/incomeValidate/getSpecialAccount
测试请求地址
请求参数
参数
限制
长度
注释
备注
bankId
M
FL8
接入编号
“信息平台”为银行分配的接入编号
specialAccount
M
VL25
“专用账户”号
timestamp
M
FL17
时间戳
北京时间精确到毫秒（yyyyMMddHHmmssSSS）
sign
M
FL32
签名
响应参数
参数
限制
说明
resultCode
M
返回结果码，数字类型。
0表示成功；其它表示失败。
resultDesc
O
返回结果描述
data
O
可拨出的工资专用账户列表，格式为JSON对象：
[{
code:
‘企业编号’,
name:
‘企业名称’,
type:
‘企业类型。
数字，参见附录4.4’,
specialAccount:
‘工资专用账户号’,
bankCode:
‘开户行代码’,
accountName:
‘开户名’
}]
3.8工资款拨出上报
接口说明
接口描述
企业在银行系统拨出工资款时，银行系统上报拨出工资款信息。
请求地址
/bank/appropriationPay/save
测试请求地址
请求参数
参数
限制
长度
注释
备注
bankId
M
FL8
接入编号
“信息平台”为银行分配的接入编号
specialAccount
M
VL25
“专用账户”号
amount
M
VL16
拨出金额
非负整数，以分为单位
transactionNo
M
VL32
转账交易号
destAccountNo
M
VL20
拨出目标账户号
destName
M
VL30
拨出目标账户名
资金到达账户的拥有人的姓名
creatime
M
FL14
交易时间
北京时间精确到秒（yyyyMMddHHmmss）
remarks
O
VL500
备注
备注
timestamp
M
FL17
时间戳
北京时间精确到毫秒（yyyyMMddHHmmssSSS）
sign
M
FL32
签名
响应参数
参数
限制
说明
resultCode
M
返回结果码，数字类型。
0表示成功；其它表示失败。
resultDesc
O
返回结果描述
3.9工资专用账户开户验证
接口说明
接口描述
获取工程相关的施工企业（施工总包企业、专业分包企业、劳务分包企业），用于施工企业在银行系统新开通工资专用账户时的验证。
请求地址
/bank/specialAccount/getEnterprises
测试请求地址
请求参数
参数
限制
长度
注释
备注
bankId
M
FL8
接入编号
“信息平台”为银行分配的接入编号
projectCode
M
VL32
工程编码
type
M
FL1
开户类型
1：
新开户；2：
变更开户
timestamp
M
FL17
时间戳
北京时间精确到毫秒（yyyyMMddHHmmssSSS）
sign
M
FL32
签名
响应参数
参数
限制
说明
resultCode
M
返回结果码，数字类型。
0表示成功；其它表示失败。
resultDesc
O
返回结果描述
data
O
工程名称及企业列表，格式为JSON对象：
{
projectName:
‘工程名称’,
enterprises:
[{
code:
‘企业编号’,
name:
‘企业名称’,
type:
‘企业类型。
数字，参见附录4.4’,
enabled:
‘是否可开户’
}]
}
3.10工资专用账户开户上报
接口说明
接口描述
工资专用账户开户成功后上报开户信息给“信息平台”。
上报成功后平台返回建设单位、施工总包企业信息给银行系统用于开通相关人员账号。
请求地址
/bank/specialAccount/save
测试请求地址
请求参数
参数
限制
长度
注释
备注
bankId
M
FL8
接入编号
“信息平台”为银行分配的接入编号
projectCode
M
VL32
工程编码
enterpriseCode
M
VL32
企业编号
specialAccount
M
VL25
“专用账户”号
accountName
M
VL30
“专用账户”户名
type
M
FL1
开户类型
1：
新开户；2：
变更开户
balance
M
VL16
余额
“专用账户”余额
buildAppropriationName
O
VL30
建设单位拨付工资款的账户名称
施工总包企业开户时必填；
分包、建设单位开户时非必填；
agreeAppropriationAmount
O
VL16
合同约定建设单位工资拨付总额
施工总包企业开户时必填；
分包、建设单位开户时非必填；
handler
M
VL10
经办人姓名
handlerIdcard
M
VL18
经办人身份证号
procotolFile
M
VL400
开户协议ZIP压缩格式
URL路径，“信息平台”会自动抓取
creatime
M
FL14
开户时间
北京时间精确到秒（yyyyMMddHHmmss）
remarks
O
VL500
备注
备注
timestamp
M
FL17
时间戳
北京时间精确到毫秒（yyyyMMddHHmmssSSS）
sign
M
FL32
签名
响应参数
参数
限制
说明
resultCode
M
返回结果码，数字类型。
0表示成功；其它表示失败。
resultDesc
O
返回结果描述
data
O
上级企业列表，格式为JSON对象：
[{
code:
‘企业编号’,
name:
‘企业名称’,
type:
‘企业类型。
数字，参见附录4.4’
}]
3.11工资专用账户变更销户验证
接口说明
接口描述
获取待变更的工资专用账户号的新工资专用账户号。
用于施工企业在银行系统申请变更销户时验证已开通新的工资专用账户号，并将账户余额转入新的工资专用账户号。
请求地址
/bank/specialAccount/cancelAccount
测试请求地址
请求参数
参数
限制
长度
注释
备注
bankId
M
FL8
接入编号
“信息平台”为银行分配的接入编号
specialAccount
M
VL25
原银行“专用账户”号
timestamp
M
FL17
时间戳
北京时间精确到毫秒（yyyyMMddHHmmssSSS）
sign
M
FL32
签名
响应参数
参数
限制
说明
resultCode
M
返回结果码，数字类型。
0表示成功；其它表示失败。
resultDesc
O
返回结果描述
data
O
格式为JSON对象：
{
specialAccount:
‘新银行“专用账户”号’,
bankCode:
‘开户行代码’,
accountName:
‘开户名’
}
3.12工资专用账户销户验证
接口说明
接口描述
用于施工企业在银行系统申请撤销工资专用账户时的验证。
平台检查施工企业的分包企业是否已销户，且在“信息平台”的相关预警、警示是否处理完成，返回是否可以销户的结果给银行系统。
请求地址
/bank/specialAccountDestroy/checkCancle
测试请求地址
请求参数
参数
限制
长度
注释
备注
bankId
M
FL8
接入编号
“信息平台”为银行分配的接入编号
specialAccount
M
VL25
原银行“专用账户”号
timestamp
M
FL17
时间戳
北京时间精确到毫秒（yyyyMMddHHmmssSSS）
sign
M
FL32
签名
响应参数
参数
限制
说明
resultCode
M
返回结果码，数字类型。
0表示成功；其它表示失败。
resultDesc
O
返回结果描述
data
O
格式为JSON对象：
{
success:
true,//true：
可以销户；false：
不可销户
message:
‘不可销户原因’
}
3.13工资专用账户销户上报
接口说明
接口描述
“专用账户”销户时上报数据
请求地址
/bank/specialAccountDestroy/save
测试请求地址
请求参数
参数
限制
长度
注释
备注
bankId
M
FL8
接入编号
“信息平台”为银行分配的接入编号
specialAccount
M
VL25
“专用账户”号
type
M
FL1
销户类型
1：
销户；2：
变更销户
balance
O
VL16
结余资金
“专用账户”销户时的余额，非负整数并以分为单位
handler
M
VL10
经办人姓名
handlerIdcard
M
VL18
经办人身份证号
procotolFile
M
VL400
销户协议ZIP压缩格式
URL路径，“信息平台”会自动抓取
transactionNo
O
VL32
销户转账交易号
destAccount
O
VL20
提取账户号
升级会员 