# 营收系统银行缴费接口文档

本目录包含营收系统与银行/第三方支付机构之间的接口 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。