tangweijie/fujian_water_biz_doc
1
0
Fork 0
Code Issues Pull Requests 12 Actions Packages Projects Releases 1 Wiki Activity
fujian_water_biz_doc/docs/api/openapi
History

README.md

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

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

cd docs/api/openapi
node validate.js

2. 启动本地预览服务

cd docs/api/openapi
node serve.js

访问 http://localhost:3000 查看 API 文档

3. 导入到开发工具

Swagger Editor

  1. 打开 Swagger Editor
  2. 导入 docs/api/openapi/main/openapi.yaml 文件

Postman

  1. 打开 Postman
  2. 点击 Import
  3. 选择 docs/api/openapi/main/openapi.yaml 文件导入

相关文档

来源

本文档从 water-bank-api-doc 仓库迁移而来，原始文档基于营收系统缴费接口规范 v1.5。