第四章 接口参数(2) - 结算流程
## 结算状态流程图
## 2.结算接口
## 2.1 查询商户可开票列表、主体接口
>d 通过该接口可获取公司的可开发票列表，以及所拥有主体列表,无需频繁请求。请求到之后保存自己库即可。当签署主体信息有变更。或者发票内容有调整重新请求接口即可。
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/company/queryInvoices
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|是否必填|参数备注|
|-|-|-|-|
|无参数|||该接口无需参数|
#### 响应参数说明：
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|name| 主体名称| String|是|主体名称|
|mainstayId| 主体ID|int| 是|主体ID|
|taxRate| 税率|BigDecimal| 是||
|invoiceOpResponseList| 发票列表| 是|发票列表为List数组|
|invoiceCode| 发票列表里面属性值发票编码|String| 是|invoiceOpResponseList里面属性|
|name| 发票列表里面属性值发票名称|String| 是|invoiceOpResponseList里面属性|
解密结果示例如下：
```json
[{
"invoiceOpResponseList": [{
"invoiceCode": "XXJSFWJSFWF1", //发票编码
"name": "信息技术服务,技术服务费" //发票内容
}, {
"invoiceCode": "XXJSFWJSZXFWF2",
"name": "信息技术服务,技术咨询服务费"
}],
"mainstayId": 1, //主体ID
"name": "xxx" //主体名称
}, {
"invoiceOpResponseList": [{
"invoiceCode": "JZZXFWZXFWF19",
"name": "鉴证咨询服务,咨询服务费"
}, {
"invoiceCode": "JZZXFWQYGLZXF20",
"name": "鉴证咨询服务,企业管理咨询费"
}],
"mainstayId": 2,
"name": "xxx",
"taxRate" : 0.050
}]
```
## 2.2 结算订单提交接口
>d 备注：该接口所生成订单超过五天未确认发放，系统会默认清除
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/bill/submitBill
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|payeeName|收款人姓名||是||
|wxAppId|微信appId|String|否|仅限微信结算，1.非必填 2.传入的微信的AppId与个人的OpenId需要一一对应；3. 不传默认取商户配置AppId|
|payeeAccount|收款人账号||是|根据支付类型对应不同参数， 0.银行卡对应的是银行卡信息 1.支付宝对应支付宝账号 2.微信对应个人的openID|
|payeeIdCard|收款人身份证号码||是||
|amount |收款金额||是|元。精确到分，比如：10.01 代表的是 十元零一分|
|thirdOrderId|商户订单号||是|商户自己生成，不可重复提交|
|payeePhone|收款人手机号||否|该参数用于用户接收到款短信|
|payeeBankName|收款账户开户银行||否||
|payeeBankNo|收款账户开户银行联行号||否||
|thirdBizOrderId|第三方业务订单ID||否|该参数为商户自己的业务订单号，通过该订单号能够查询该笔金额来源明细|
|payType|支付类型||是|支付类型该参数值填写支付类型对应数字即可 0:银行卡 1:支付宝 2:微信
|batchNo|批次号||否|由第三方自己控制哪些订单为同一个批次号，开票的时候可根据批次号开票|
|transName|转账附言||否|备注字数不可超过20个字符|||
#### 注意：
转账附言字段：如需要配置请联系相关商务人员申请配置；
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义| 数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|billId| 结算平台订单号| int|是||
|thirdOrderNo| 商户提交时的订单号|String| 是||
|transNo|交易号|String| 是||
|checkStatus| 检测状态 |String|是|-1：检测失败 1：检测成功|
|reason| 失败原因|String| 是||
## 2.3 确认结算接口
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/bill/sureGrant
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|是否必填|参数备注|
|-|-|-|-|
|billId|订单ID|是|该值由提交订单接口返回|
|mainstayId|主体ID|是|该参数由[2.1查询商户可开票列表，以及所拥有的主体接口](https://easydoc.xyz/doc/98778187/o4ecqJ51/iwji44Kk)可获的|
|invoiceCode|发票编号|是|该参数由[2.1查询商户可开票列表，以及所拥有的主体接口](https://easydoc.xyz/doc/98778187/o4ecqJ51/iwji44Kk)可获的|
>d mainstayId 由签约合同的时候决定使用什么主体，签约成功新增账户后主体ID通过接口公司可开票类型，主体查询接口可获得
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|thirdOrderNo| 第三方订单号|String| 是|生成订单接口的thirdOrderId字段的值|
|transNo|交易单号|String|是|支付平台交易单号|
|status| 结算结果状态|String| 是|详情请参考[发放结果状态码](https://easydoc.xyz/doc/98778187/o4ecqJ51/GiTKQ3py)|
|returnMsg| 返回信息|String|是| ||
## 2.4 结算订单结果查询接口
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/bill/queryResult
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|是否必填|参数备注|
|-|-|-|-|
|无参数名称|需要查询的商户订单号|是|例如：[商户订单号1,商户订单号2]|
>d 该接口参数无需参数名称只需将商户订单号拼接处json数组即可
示例：String data = [\"orderNo1\",\"orderNo2\"... ,\"orderNo10\"];
一次性最多查询10条记录
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|thirdOrderNo| 商户订单号|String |是||
|status| 结果状态|int| 是|详情请参考[发放结果状态码](https://easydoc.xyz/doc/98778187/o4ecqJ51/GiTKQ3py)|
|reason| 失败原因|String|是| |支付失败才会有该值|
>d该发放结果data解密后为List 集合json字符串。
结果示例
[{"thirdOrderNo":"orderNo1","status":"xx","reason":"xxxx"},
{"thirdOrderNo":"orderNo2","status":"xx","reason":"xxxx"}]
## 2.5 结算发放成功异步回调
>d 该接口需要第三方自行编写提供接口到发放平台回调成功必须返回success不然会重复回调
#### 请求方式：POST
解密结果示例如下：
```json
{"itemStatus":"2","amount":"12.01","thirdOrderNo":"xxxxx","paymentTime":"2019-07-05 23:41:45","reason":""}";
```
|参数名称| 参数含义| 是否必有| 参数备注|
|-|-|-|-|
|itemStatus| 订单状态| 是|0等待发放 1正在发放 2发放成功 -1发放失败 -2转账退款 -3发放终止 -4 格式检查失败|
|amount| 结算发放的金额| 是|实际结算发放的金额|
|thirdOrderNo| 结算发放订单号| 是||
|paymentTime| 结算发放时间| 是||
|reason| 失败原因| 是||
#### 接口示例：
>d 该接口需要第三方自行编写提供接口到发放平台 接口编写示例如下。
#### 请求方式：POST
```java
@PostMapping("signCallBack")
@ResponseBody
public String signCallBack(HttpServletRequest request, @RequestBody String data){
String publicKey = "该公钥由发放平台提供发放到贵司邮箱";
//解密
String decode = RSAHelper.decryptByPublicKey(data, publicKey);
/*贵公司处理业务逻辑*/
return "success";
}
```
解密工具类在 [JAVA_DEMO](https://gitee.com/xinfudblog/lxapi_java_demo) 的 RSAHelper 类中
>d 贵司写完后提供到接口url给发放平台即可。回调成功需返回success，不然回重复回调，至多重试5次，每次的间隔时间是2 的 n 次方分钟
postman中模拟接口是否正常接收数据如下操作
## 2.6 获取对账单接口
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/bill/companyReconciliation
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|是否必填|参数备注|
|-|-|-|-|
|date|需要对账的日期|是|该参数为String类型 yyyy-MM-dd,例如 “2019-07-20”。|
示例：
```java
String paramsJson= "{\"date\":\"2019-07-20\"}";
String data = RSAHelper.encryptByPublicKey(paramsJson, publicKey);
```
>d 备注：系统每天9.30点生成前一天的对账单。建议每天10点后拉取对前一天的对账单
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义| 是否必有| 参数备注|
|-|-|-|-|
|fileUrl|对账文件URL|是|查询的某一天的对账单文件链接，通过该链接可下载对账单内容(该链接有效期为30分钟，30分钟后获取则需要重新调用接口生成新的链接)|
解密结果示例
>d `{"fileUrl":"https://qiniu.lx-rhino.com/3c59dc048e8850243be8079a5c74d079/2019-07-20.csv"}`
## 2.7 取消订单接口
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/bill/cancel
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|是否必填|参数备注|
|-|-|-|-|
|billId|平台返回的订单ID|是||
|reason|取消原因(30字)|否||
#### 接口响应参数data字段解密后的参数说明：
>d 该接口响应参数中无响应data字段 ,success 等于true代表取消成功，false 代表失败 errorMessage中有错误信息反馈
## 2.8 查询用户每月可发放金额数
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/available/credit
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|是否必填|参数备注|
|-|-|-|-|
|idCards|需要查询的身份证号码集合|是|例如：[身份证1,身份证2,身份证3]|
|mainstayId|主体ID|是||
>d 备注说明:idCards最大长度查询100条记录
```java
//示例
String data = {"idCards":["xxxx","xxxx"],"mainstayId":"1"};
```
#### 响应参数说明：
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|idCard| 身份证号|Srting| 是||
|availableAmount| 可发放金额|BigDecimal| 是||
## 2.9 获取电子回单接口
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/bill/queryVoucherUrl
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|是否必填|参数备注|
|-|-|-|-|
|thirdOrderId|第三方订单ID|是||
#### 接口响应参数data字段解密后的参数说明：
>d 该接口解密后的data字段即为电子回单的url
结果示例
“https://xxxxxx”
如果 data字段为空则代表未取得回单
#### 接口响应参数data字段解密后的参数说明：
>d 该接口响应参数中无响应data字段 ,success 等于true代表取消成功，false 代表失败 errorMessage中有错误信息反馈