[TOC]

# 接口规则

## 协议规则

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

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

## 签名/验签规则

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

对字符串进行rsa2048签名

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

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

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

## 安全规范

### 签名工具

RAS密钥可以使用支付宝提供的工具计算 [密钥生成工具](http://p.tb.cn/rmsportal_6680_secret_key_tools_RSA_win.zip) ![image](https://gw.alipayobjects.com/os/skylark-tools/public/files/15563f1b8da9cf77618487750d3fb2ff.png%26originHeight%3D1750%26originWidth%3D3533%26size%3D451811%26status%3Ddone%26width%3D746) 开发资源有限，目前只支持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 | 其他异常        |