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: []