381 lines
9.8 KiB
YAML
381 lines
9.8 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: 营收系统接口API
|
||
description: |
|
||
营收系统与银行/第三方支付机构之间的接口交互API文档
|
||
|
||
## 特性
|
||
- 支持账单查询、缴费、红冲等核心功能
|
||
- 支持银行代扣签约、解约、送盘、回盘
|
||
- 支持XML和JSON两种数据格式
|
||
- 支持多种加密算法（3DES、SM2、SM4）
|
||
- 统一错误码和响应格式
|
||
|
||
## 安全认证
|
||
本API使用多种加密方式保证数据安全传输：
|
||
- 数据加密后Base64编码传输
|
||
- 支持3DES、SM2、SM4等加密算法
|
||
- 通过请求头指定加密类型和模式
|
||
|
||
version: 1.0.0
|
||
contact:
|
||
name: 营收系统API支持
|
||
email: support@billing-system.com
|
||
license:
|
||
name: 专有许可证
|
||
|
||
servers:
|
||
- url: https://api.billing-system.com
|
||
description: 生产环境
|
||
- url: https://test-api.billing-system.com
|
||
description: 测试环境
|
||
- url: https://dev-api.billing-system.com
|
||
description: 开发环境
|
||
|
||
tags:
|
||
- name: 账单管理
|
||
description: 账单查询、缴费、红冲相关接口
|
||
- name: 代扣管理
|
||
description: 银行代扣签约、解约、送盘、回盘相关接口
|
||
|
||
paths:
|
||
# 账单查询
|
||
/api/app/payCeb/getChargeSearch:
|
||
$ref: './paths/bill-query.yaml#/BillQuery'
|
||
|
||
# 账单缴费
|
||
/api/app/payCeb/getChargeOffs:
|
||
$ref: './paths/bill-pay.yaml#/BillPay'
|
||
|
||
# 账单红冲
|
||
/api/app/payInvalid/payInvalid:
|
||
$ref: './paths/pay-invalid.yaml#/PayInvalid'
|
||
|
||
# 代扣签约
|
||
/api/app/bankWithholding/signing:
|
||
$ref: './paths/withholding-signing.yaml#/WithholdingSigning'
|
||
|
||
# 代扣解约
|
||
/api/app/bankWithholding/termination:
|
||
$ref: './paths/withholding-termination.yaml#/WithholdingTermination'
|
||
|
||
# 代扣送盘
|
||
/api/app/bankWithholding/sendDisc:
|
||
$ref: './paths/withholding-send-disc.yaml#/WithholdingSendDisc'
|
||
|
||
# 代扣回盘
|
||
/api/app/bankWithholding/backDisc:
|
||
$ref: './paths/withholding-back-disc.yaml#/WithholdingBackDisc'
|
||
|
||
# 对账接口
|
||
/api/app/payCeb/paymentCheck:
|
||
$ref: './paths/payment-check.yaml#/PaymentCheck'
|
||
|
||
# 取消代扣交易
|
||
/api/app/bankWithholding/cancelDisc:
|
||
$ref: './paths/withholding-cancel-disc.yaml#/WithholdingCancelDisc'
|
||
|
||
# 代扣送盘状态查询
|
||
/api/app/bankWithholding/sendDiscCheck:
|
||
$ref: './paths/withholding-send-disc-check.yaml#/WithholdingSendDiscCheck'
|
||
|
||
# 代扣回盘状态查询
|
||
/api/app/bankWithholding/backDiscCheck:
|
||
$ref: './paths/withholding-back-disc-check.yaml#/WithholdingBackDiscCheck'
|
||
|
||
# 客户基本信息查询
|
||
/api/app/customer/check:
|
||
$ref: './paths/customer-check.yaml#/CustomerCheck'
|
||
|
||
components:
|
||
# 数据模型
|
||
schemas:
|
||
# 基础请求模型
|
||
BaseRequest:
|
||
type: object
|
||
required:
|
||
- Version
|
||
- InstId
|
||
- TranCode
|
||
- TranDate
|
||
- TranSeq
|
||
properties:
|
||
Version:
|
||
type: string
|
||
description: 版本号
|
||
example: "1.0.1"
|
||
InstId:
|
||
type: string
|
||
description: 机构编码
|
||
example: "00001"
|
||
maxLength: 30
|
||
TranCode:
|
||
type: string
|
||
description: 交易码
|
||
example: "Query"
|
||
maxLength: 20
|
||
TranDate:
|
||
type: string
|
||
description: 交易日期
|
||
pattern: '^\d{8}$'
|
||
example: "20240101"
|
||
TranSeq:
|
||
type: string
|
||
description: 交易流水号（银行生成的唯一标识）
|
||
example: "123456789012"
|
||
maxLength: 40
|
||
|
||
# 基础响应模型
|
||
BaseResponse:
|
||
type: object
|
||
required:
|
||
- Version
|
||
- InstId
|
||
- TranCode
|
||
- TranDate
|
||
- TranSeq
|
||
- RespCode
|
||
- RespMessage
|
||
properties:
|
||
Version:
|
||
type: string
|
||
description: 版本号
|
||
example: "1.0.1"
|
||
InstId:
|
||
type: string
|
||
description: 机构编码
|
||
example: "00001"
|
||
TranCode:
|
||
type: string
|
||
description: 交易码
|
||
example: "QueryRes"
|
||
TranDate:
|
||
type: string
|
||
description: 交易日期
|
||
pattern: '^\d{8}$'
|
||
example: "20240101"
|
||
TranSeq:
|
||
type: string
|
||
description: 交易流水号
|
||
example: "123456789012"
|
||
RespCode:
|
||
type: string
|
||
description: 返回码
|
||
enum:
|
||
- "AAAAAAA" # 成功
|
||
- "DEF0001" # 无相应记录
|
||
- "DEF0002" # 缴费金额不匹配
|
||
- "SYS1001" # 系统异常
|
||
- "SEC2001" # 加密错误
|
||
example: "AAAAAAA"
|
||
RespMessage:
|
||
type: string
|
||
description: 返回消息
|
||
example: "成功"
|
||
maxLength: 60
|
||
|
||
# 错误详情
|
||
ErrorDetail:
|
||
type: object
|
||
properties:
|
||
ErrorCode:
|
||
type: string
|
||
description: 错误码
|
||
example: "DEF0001"
|
||
ErrorMsg:
|
||
type: string
|
||
description: 错误消息
|
||
example: "用户编号123456不存在"
|
||
ErrorTime:
|
||
type: string
|
||
format: date-time
|
||
description: 错误时间
|
||
example: "2024-01-01T12:00:00.000Z"
|
||
|
||
# 其他数据模型引用原有文件
|
||
BillQueryRequest:
|
||
$ref: './components/schemas.yaml#/components/schemas/BillQueryRequest'
|
||
|
||
BillQueryResponse:
|
||
$ref: './components/schemas.yaml#/components/schemas/BillQueryResponse'
|
||
|
||
BillPayRequest:
|
||
$ref: './components/schemas.yaml#/components/schemas/BillPayRequest'
|
||
|
||
BillPayResponse:
|
||
$ref: './components/schemas.yaml#/components/schemas/BillPayResponse'
|
||
|
||
# 响应组件
|
||
responses:
|
||
# 业务错误响应
|
||
BusinessError:
|
||
description: 业务处理错误
|
||
content:
|
||
application/xml:
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BaseResponse'
|
||
- type: object
|
||
properties:
|
||
ErrorDetail:
|
||
$ref: '#/components/schemas/ErrorDetail'
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BaseResponse'
|
||
- type: object
|
||
properties:
|
||
ErrorDetail:
|
||
$ref: '#/components/schemas/ErrorDetail'
|
||
|
||
# 系统错误响应
|
||
SystemError:
|
||
description: 系统异常错误
|
||
content:
|
||
application/xml:
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BaseResponse'
|
||
- type: object
|
||
properties:
|
||
ErrorDetail:
|
||
$ref: '#/components/schemas/ErrorDetail'
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BaseResponse'
|
||
- type: object
|
||
properties:
|
||
ErrorDetail:
|
||
$ref: '#/components/schemas/ErrorDetail'
|
||
|
||
# 安全错误响应
|
||
SecurityError:
|
||
description: 安全验证错误
|
||
content:
|
||
application/xml:
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BaseResponse'
|
||
- type: object
|
||
properties:
|
||
ErrorDetail:
|
||
$ref: '#/components/schemas/ErrorDetail'
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BaseResponse'
|
||
- type: object
|
||
properties:
|
||
ErrorDetail:
|
||
$ref: '#/components/schemas/ErrorDetail'
|
||
|
||
# 网络错误响应
|
||
NetworkError:
|
||
description: 网络通信错误
|
||
content:
|
||
application/xml:
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BaseResponse'
|
||
- type: object
|
||
properties:
|
||
ErrorDetail:
|
||
$ref: '#/components/schemas/ErrorDetail'
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BaseResponse'
|
||
- type: object
|
||
properties:
|
||
ErrorDetail:
|
||
$ref: '#/components/schemas/ErrorDetail'
|
||
|
||
# 参数组件
|
||
parameters:
|
||
ContentTypeHeader:
|
||
name: Content-Type
|
||
in: header
|
||
required: true
|
||
description: 请求内容类型
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- application/xml
|
||
- application/json
|
||
example: "application/xml"
|
||
|
||
EncryptTypeHeader:
|
||
name: X-Encrypt-Type
|
||
in: header
|
||
required: false
|
||
description: 加密算法类型
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- "3DES"
|
||
- "SM2"
|
||
- "SM4"
|
||
example: "3DES"
|
||
|
||
EncryptModeHeader:
|
||
name: X-Encrypt-Mode
|
||
in: header
|
||
required: false
|
||
description: 加密模式
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- "ECB"
|
||
- "CBC"
|
||
example: "ECB"
|
||
|
||
DataTypeHeader:
|
||
name: X-Data-Type
|
||
in: header
|
||
required: false
|
||
description: 数据格式类型
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- "XML"
|
||
- "JSON"
|
||
example: "XML"
|
||
|
||
# 响应头组件
|
||
headers:
|
||
ContentType:
|
||
description: 响应内容类型
|
||
schema:
|
||
type: string
|
||
example: "application/xml; charset=GBK"
|
||
|
||
ResponseTime:
|
||
description: 响应时间（毫秒）
|
||
schema:
|
||
type: integer
|
||
example: 150
|
||
|
||
RequestId:
|
||
description: 请求唯一标识
|
||
schema:
|
||
type: string
|
||
example: "req-123456789012"
|
||
|
||
# 安全认证组件
|
||
securitySchemes:
|
||
ApiKeyAuth:
|
||
type: apiKey
|
||
in: header
|
||
name: X-API-Key
|
||
description: API密钥认证
|
||
|
||
EncryptedData:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: encrypted
|
||
description: 加密数据传输认证
|
||
|
||
security:
|
||
- ApiKeyAuth: []
|
||
- EncryptedData: [] |