97 lines
3.5 KiB
Markdown
97 lines
3.5 KiB
Markdown
# 营收系统银行缴费接口文档
|
||
|
||
本目录包含营收系统与银行/第三方支付机构之间的接口 OpenAPI 规范文档。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
docs/api/openapi/
|
||
├── main/
|
||
│ ├── openapi.yaml # OpenAPI 3.0.3 主文档入口
|
||
│ ├── components/ # 可复用组件定义
|
||
│ │ ├── schemas.yaml # 数据模型定义
|
||
│ │ ├── responses.yaml # 响应定义
|
||
│ │ ├── parameters.yaml # 参数定义
|
||
│ │ ├── headers.yaml # 头部定义
|
||
│ │ ├── security.yaml # 安全定义
|
||
│ │ └── index.yaml # 组件索引
|
||
│ └── paths/ # API 路径定义
|
||
│ ├── bill-query.yaml # 账单查询
|
||
│ ├── bill-pay.yaml # 账单缴费
|
||
│ ├── pay-invalid.yaml # 账单红冲
|
||
│ ├── withholding-signing.yaml # 代扣签约
|
||
│ ├── withholding-termination.yaml # 代扣解约
|
||
│ ├── withholding-send-disc.yaml # 代扣送盘
|
||
│ └── withholding-back-disc.yaml # 代扣回盘
|
||
├── generated/ # 生成的代码（保留参考）
|
||
├── validate.js # 文档验证脚本
|
||
└── serve.js # 本地预览服务器
|
||
|
||
scripts/api-tools/
|
||
└── validate-all.js # 批量验证工具
|
||
```
|
||
|
||
## 接口清单
|
||
|
||
| 接口名称 | 路径 | 交易码 | 描述 |
|
||
|---------|------|--------|------|
|
||
| 账单查询 | `/api/app/payCeb/getChargeSearch` | Query/QueryRes | 查询客户账单信息 |
|
||
| 账单缴费 | `/api/app/payCeb/getChargeOffs` | Pay/PayRes | 处理账单缴费 |
|
||
| 账单红冲 | `/api/app/payInvalid/payInvalid` | PayInvalid/PayInvalidRes | 红冲缴费记录 |
|
||
| 代扣签约 | `/api/app/bankWithholding/signing` | Signing/SigningRes | 银行代扣签约 |
|
||
| 代扣解约 | `/api/app/bankWithholding/termination` | Termination/TerminationRes | 银行代扣解约 |
|
||
| 代扣送盘 | `/api/app/bankWithholding/sendDisc` | SendDisc/SendDiscRes | 批量代扣送盘 |
|
||
| 代扣回盘 | `/api/app/bankWithholding/backDisc` | BackDisc/BackDiscRes | 接收银行回盘 |
|
||
|
||
## 核心特性
|
||
|
||
### 数据格式支持
|
||
- **XML格式**：GBK编码，符合传统银行系统规范
|
||
- **JSON格式**：UTF-8编码，适合现代化系统集成
|
||
- **双格式支持**：同时支持XML和JSON请求响应
|
||
|
||
### 安全加密
|
||
- **3DES加密**：ECB模式，PKCS7填充（默认）
|
||
- **SM2加密**：支持C1C3C2和C1C2C3模式
|
||
- **SM4加密**：支持ECB和CBC模式
|
||
- **Base64编码**：加密后数据进行Base64编码传输
|
||
|
||
## 使用指南
|
||
|
||
### 1. 验证文档
|
||
|
||
```bash
|
||
cd docs/api/openapi
|
||
node validate.js
|
||
```
|
||
|
||
### 2. 启动本地预览服务
|
||
|
||
```bash
|
||
cd docs/api/openapi
|
||
node serve.js
|
||
```
|
||
|
||
访问 http://localhost:3000 查看 API 文档
|
||
|
||
### 3. 导入到开发工具
|
||
|
||
#### Swagger Editor
|
||
1. 打开 [Swagger Editor](https://editor.swagger.io/)
|
||
2. 导入 `docs/api/openapi/main/openapi.yaml` 文件
|
||
|
||
#### Postman
|
||
1. 打开 Postman
|
||
2. 点击 Import
|
||
3. 选择 `docs/api/openapi/main/openapi.yaml` 文件导入
|
||
|
||
## 相关文档
|
||
|
||
- [接口规范设计文档](../../design/04_Appendix/Archive/银行缴费接口规范设计文档.md)
|
||
- [接口说明文档](../../design/04_Appendix/Archive/银行缴费接口说明.md)
|
||
- [主接口设计文档](../../design/03_Technical_Design/03_Interface_Design.md)
|
||
|
||
## 来源
|
||
|
||
本文档从 `water-bank-api-doc` 仓库迁移而来，原始文档基于营收系统缴费接口规范 v1.5。
|