HeatingPaymentsInvoker/doc/热力服务商接口说明.md

[TOC]

接口规则

协议规则

调用API必须遵循以下规则：

规则	说明
传输方式	HTTP/HTTPS
提交方式	采用POST方法提交
数据格式	提交和返回数据都为JSON格式: "Content-Type", "application/json"
字符编码	统一采用UTF-8字符编码
安全机制	签名或者IP白名单
签名算法	如安全机制未签名，RSA(2048)/和支付宝RAS2方式签名一样
签名要求	如安全机制未签名，请求和接收数据均需要校验签名

签名/验签规则

平台/商户将请求参数字段排序后序列化为键值对，并使用&链接成字符串

对字符串进行rsa2048签名

String toSignContent = "appid=" + x.getAppId() +
			"&billKey=" + x.getBillKey() +
			"&nonceStr=" + x.getNonceStr() + 
			"&timeStamp=" + x.getTimeStamp();

商户请自行使用平台提供的公钥以同样操作方式进行验签

注意: sign字段本身不参与验签

安全规范

签名工具

RAS密钥可以使用支付宝提供的工具计算 密钥生成工具 开发资源有限，目前只支持rsa，格式为pkcs8，长度为2048

接口说明

==平台发起调用==

商户收到调用信息并验证签名后返回对应的业务信息

查询缴费单

应用场景

通过该接口获取终端用户的预存与欠费情况

请求参数

| 参数 | 类型 | 必填 | 描述 | | --------- | ------ | -- | ------------ | | appId | String | 是 | 商户号,由平台提供,唯一 | | billKey | String | 是 | 终端用户机表号 | | nonceStr | String | 是 | 随机字符串 | | timeStamp | String | 是 | 请求发起的时间戳 | | sign | String | 是 | 签名 |

返回结果

变量名	类型	描述	示例值
appId	String	商户号,由平台提供,唯一,原样回传即可	1234567
respCode	String	调用结果,详见错误码	00000
respMsg	String	错误描述	success
timeStamp	String	请求返回的时间戳	1745393406
billKey	String	终端用户机表号	HC202110257
customerName	String	终端用户名称	XXX小区X栋XX户李XX
balance	long	用户预存金额(单位:分)	0
payAmount	long	用户本期欠费金额(单位:分)	100

错误码

错误码	描述
00000	成功
DEF0002	用户未欠费
DEF0005	超过缴费时间
DEF0010	用户不存在
DEF0012	该用户不支持网上缴费，请联系公共事业单位
DEF0006	其他异常

缴费单销账

应用场景

==平台发起调用==

用户在平台完成缴费，需要调用商户的系统进行销账。

请求参数

| 参数 | 类型 | 必填 | 描述 | | :--------- | :----- | :- | :-------------- | | appId | String | 是 | 商户号,由平台提供,唯一 | | billKey | String | 是 | 终端用户机表号 | | payDate | String | 是 | 缴费交易日期 yyyyMMdd | | bankBillNo | String | 是 | 缴费交易流水号 | | payAmount | String | 是 | 缴费金额,单位:分 | | nonceStr | String | 是 | 随机字符串 | | timeStamp | String | 是 | 请求发起的时间戳 | | sign | String | 是 | 签名 |

返回结果

变量名	类型	描述	示例值
appId	String	商户号,由平台提供,唯一,原样回传即可	1234567
respCode	String	调用结果,详见错误码	00000
respMsg	String	错误描述	success
timeStamp	String	请求返回的时间戳	1745393406

错误码

错误码	描述
00000	成功
DEF0002	用户未欠费
DEF0005	超过缴费时间
DEF0010	用户不存在
DEF0012	该用户不支持网上缴费，请联系公共事业单位
DEF0013	金额不符合规则
DEF0006	其他异常

下载对账单

应用场景

==商户发起调用==

商户可在交易次日向平台发起交易日账单下载请求

请求Header

| 参数 | 类型 | 必填 | 描述 | | :---- | :----- | :- | :----------- | | appId | String | 是 | 商户号,由平台提供,唯一 |

请求参数

| 参数 | 类型 | 必填 | 描述 | | :-------- | :----- | :- | :------------ | | payDate | String | 是 | 账单日期 yyyyMMdd | | nonceStr | String | 是 | 随机字符串 | | timeStamp | String | 是 | 请求发起的时间戳 | | sign | String | 是 | 签名 |

返回结果

变量名	类型	描述	示例值
appId	String	商户号,由平台提供,唯一,原样回传即可	1234567
respCode	String	调用结果,详见错误码	00000
respMsg	String	错误描述	success
fileKey	byte[]	使用==商户方提供的公钥==加密后的文件aes密钥.商户须自行使用私钥解密出文件aes密钥之后,再使用aes密钥对fileContent进行解密得到原始文件内容
fileContent	byte[]	使用文件aes密钥加密后的文件内容
timeStamp	String	请求返回的时间戳	1745393406

错误码

错误码	描述
00000	成功
DEF0020	该日期账单文件暂未生成
DEF0030	验签失败
DEF0010	用户不存在
DEF0006	其他异常