广州建设领域管理应用信息平台Word文档格式.docx
《广州建设领域管理应用信息平台Word文档格式.docx》由会员分享，可在线阅读，更多相关《广州建设领域管理应用信息平台Word文档格式.docx（27页珍藏版）》请在冰豆网上搜索。
为实现广州市建设领域管理应用信息平台对工人工资支付分账专用账户的监督管理，及时对工人工资支付分账专用账户的异常情况进行预警，需要银行配合将工人工资支付分账专用账户的动账明细数据上报，特编写本接口文档以供银行相关技术人员对接。
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&
param2=val2…。
●参数组装顺序规则：
参数名的字典顺序。
●密钥拼接方式为传输参数直接连接密钥，如只有param1和param2两参数，值分别为val1和val2，密钥为key，拼接结果为：
param2=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"
}}
处理失败：
1,"
签名错误"
●返回结果码对照见附录4.2结果码对照表。
3.1进账上报
接口说明
接口描述
发生导致“专用账户”余额增加的交易时上报数据
请求地址
/bank/incomeRecord/save
测试请求地址
请求参数
参数
限制
长度
注释
备注
bankId
M
FL8
接入编号
“信息平台”为银行分配的接入编号
transactionNo
VL32
交易号
请求的唯一交易号
transactionTime
FL17
交易记账时间
北京时间精确到毫秒（yyyyMMddHHmmssSSS）
specialAccount
VL25
“专用账户”号
amount
VL16
交易金额
交易金额，非负整数并以分为单位
balance
余额
“专用账户”余额，非负整数并以分为单位
srcAccount
O
VL20
资金来源账户号
为空表示现金入账
srcName
VL200
资金来源账户名
remarks
VL500
sign
FL32
签名
响应参数
说明
resultCode
返回结果码，数字类型。
0表示成功；
其它表示失败。
resultDesc
返回结果描述
data
3.2出账上报
发生导致“专用账户”余额减少的交易时上报数据
/bank/paymentRecord/save
destAccount
资金到达账户号
destIdcard
VL18
账户身份证号
资金到达账户的拥有人的身份证号
destName
VL30
账户名
资金到达账户的拥有人的姓名
state
FL1
到账结果状态
0：
已出账；
1：
已到账；
-1：
已退款
3.3出账结果上报
上报出账的到账结果
/bank/paymentRecord/result
finishTime
到账结果反馈时间
3.4获取班组信息
批量获取与指定的“专用账户”绑定的班组信息。
用于银行系统在提供给企业制作工资表时选择班组。
/bank/team/list
timestamp
时间戳
班组列表。
格式为JSON对象：
[{
code:
‘班组编码’,
name:
‘班组名称’
}]
3.5获取工人实名信息
批量获取与指定的“专用账户”绑定的工人实名信息。
银行在提供给企业发放工资时可以获取此列表用于工资发放依据，不在此列表中的账户不能发放工资，工资发放数额不能超过未支付的工资数。
/bank/teamBuilder/page
teamCode
班组编码
项目内部的班组唯一编码，检查班组是否存在的依据
page
VL5
页码
获取的页码，从0开始
size
VL4
每页的数据条数
工人列表。
{
number:
‘页码’,
size:
‘每页的数据条数’,
content:
[{
name:
‘工人姓名’,
idcard:
‘工人身份证号’,
cardCode:
‘工人银行卡号’,
bankCode:
‘工人银行卡开户行代码，参见附录4.3’,
cardChecked:
‘银行卡是否验证’
}]
}
3.6工资表上报
企业提交工资表给银行发放完工资后上报工资表数据。
/bank/wage/save
month
FL6
工资月份
yyyyMM
builders
NL
工人工资列表
不参与签名。
json格式的数据：
shouldWages:
‘应发工资，非负整数并以分为单位’,
realWages:
‘实发工资，非负整数并以分为单位’,
transactionNo:
‘发放流水交易号’,
creatime:
‘交易时间，北京时间精确到秒（yyyyMMddHHmmss）’,
remarks:
‘备注’
3.7工资款拨出验证
获取工资专用账户可拨出的账户。
用于企业在银行系统拨出工资款时选择可拨出的工资专用账户。
/bank/incomeValidate/getSpecialAccount
可拨出的工资专用账户列表，格式为JSON对象：
code:
‘企业编号’,
name:
‘企业名称’,
type:
‘企业类型。
数字，参见附录4.4’,
specialAccount:
‘工资专用账户号’,
bankCode:
‘开户行代码’,
accountName:
‘开户名’
3.8工资款拨出上报
企业在银行系统拨出工资款时，银行系统上报拨出工资款信息。
/bank/appropriationPay/save
拨出金额
非负整数，以分为单位
转账交易号
destAccountNo
拨出目标账户号
拨出目标账户名
creatime
FL14
交易时间
北京时间精确到秒（yyyyMMddHHmmss）
3.9工资专用账户开户验证
获取工程相关的施工企业（施工总包企业、专业分包企业、劳务分包企业），用于施工企业在银行系统新开通工资专用账户时的验证。
/bank/specialAccount/getEnterprises
projectCode
工程编码
type
开户类型
新开户；
2：
变更开户
工程名称及企业列表，格式为JSON对象：
projectName:
‘工程名称’,
enterprises:
type:
enabled:
‘是否可开户’
3.10工资专用账户开户上报
工资专用账户开户成功后上报开户信息给“信息平台”。
上报成功后平台返回建设单位、施工总包企业信息给银行系统用于开通相关人员账号。
/bank/specialAccount/save
enterpriseCode
企业编号
accountName
“专用账户”户名
“专用账户”余额
buildAppropriationName
建设单位拨付工资款的账户名称
施工总包企业开户时必填；
分包、建设单位开户时非必填；
agreeAppropriationAmount
合同约定建设单位工资拨付总额
handler
VL10
经办人姓名
handlerIdcard
经办人身份证号
procotolFile
VL400
开户协议ZIP压缩格式
URL路径，“信息平台”会自动抓取
开户时间
上级企业列表，格式为JSON对象：
数字，参见附录4.4’
3.11工资专用账户变更销户验证
获取待变更的工资专用账户号的新工资专用账户号。
用于施工企业在银行系统申请变更销户时验证已开通新的工资专用账户号，并将账户余额转入新的工资专用账户号。
/bank/specialAccount/cancelAccount
原银行“专用账户”号
specialAccount:
‘新银行“专用账户”号’,
3.12工资专用账户销户验证
用于施工企业在银行系统申请撤销工资专用账户时的验证。
平台检查施工企业的分包企业是否已销户，且在“信息平台”的相关预警、警示是否处理完成，返回是否可以销户的结果给银行系统。
/bank/specialAccountDestroy/checkCancle
success:
true,//true：
可以销户；
false：
不可销户
message:
‘不可销户原因’
3.13工资专用账户销户上报
“专用账户”销户时上报数据
/bank/specialAccountDestroy/save
销户类型
销户；
变更销户
结余资金
“专用账户”销户时的余额，非负整数并以分为单位
销户协议ZIP压缩格式
销户转账交易号
提取账户号
升级会员 