openapi: 3.0.3
info:
  title: NVC Banking Platform - ISO 20022 JSON API
  description: |
    RESTful API for ISO 20022 financial messaging in JSON format.
    Compliant with ISO.org API guidelines (June 2025) and JSON Schema Draft 2020-12.
    
    ## Authentication
    All endpoints require authentication via one of:
    - **JWT Token**: `Authorization: Bearer <token>`
    - **API Key**: `X-API-Key: <api_key>`
    
    ## Supported Message Types
    - **pain.001.001.03** - Customer Credit Transfer Initiation
    - **pacs.008.001.02** - FI to FI Credit Transfer  
    - **camt.053.001.02** - Bank to Customer Statement
    
    ## Features
    - Bidirectional XML \u2194 JSON conversion
    - JSON Schema validation
    - ISO 20022 compliant message generation
  version: 1.0.0
  contact:
    name: NVC Fund API Support
    url: https://nvcfund.com
    email: api@nvcfund.com
  license:
    name: Proprietary
servers:
  - url: https://nvcfund.com/api/v1
    description: Production server
  - url: http://localhost:5000/api/v1
    description: Development server
    
security:
  - bearerAuth: []
  - apiKeyAuth: []

tags:
  - name: Health
    description: API health check endpoints
  - name: Schemas
    description: JSON Schema management
  - name: Payments
    description: Payment message creation
  - name: Conversion
    description: XML \u2194 JSON conversion
  - name: Validation
    description: Message validation

paths:
  /iso20022/health:
    get:
      tags:
        - Health
      summary: Health check
      description: Check API service health status
      security: []
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: healthy
                  service:
                    type: string
                    example: ISO 20022 JSON API
                  version:
                    type: string
                    example: 1.0.0
                  timestamp:
                    type: string
                    format: date-time
  
  /iso20022/schemas:
    get:
      tags:
        - Schemas
      summary: List available schemas
      description: Get list of all available JSON schemas for ISO 20022 messages
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  schemas:
                    type: array
                    items:
                      type: string
                    example:
                      - pain.001.001.03
                      - pacs.008.001.02
                      - camt.053.001.02
                  count:
                    type: integer
                    example: 3
  
  /iso20022/schemas/{message_type}:
    get:
      tags:
        - Schemas
      summary: Get JSON schema
      description: Retrieve JSON Schema for specific ISO 20022 message type
      parameters:
        - name: message_type
          in: path
          required: true
          schema:
            type: string
            enum:
              - pain.001.001.03
              - pacs.008.001.02
              - camt.053.001.02
          example: pain.001.001.03
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message_type:
                    type: string
                  schema:
                    type: object
        '404':
          description: Message type not found
  
  /iso20022/payments/credit-transfer:
    post:
      tags:
        - Payments
      summary: Create credit transfer (pain.001)
      description: Create Customer Credit Transfer Initiation message in JSON format
      parameters:
        - name: format
          in: query
          schema:
            type: string
            enum: [json, xml]
            default: json
          description: Response format (json or xml)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - creditor
                - amount
                - currency
              properties:
                debtor:
                  type: object
                  properties:
                    name:
                      type: string
                      example: NVC Fund
                    iban:
                      type: string
                      example: US33NVCT000000000001
                    country:
                      type: string
                      example: US
                creditor:
                  type: object
                  required:
                    - name
                  properties:
                    name:
                      type: string
                      example: Beneficiary Name
                    iban:
                      type: string
                      example: US88XXXXXXXXXXXX
                    account_number:
                      type: string
                    country:
                      type: string
                      example: US
                amount:
                  type: string
                  example: "1000.00"
                currency:
                  type: string
                  example: USD
                  pattern: "^[A-Z]{3}$"
                remittance_info:
                  type: string
                  example: Payment for services
                purpose_code:
                  type: string
                  example: SUPP
      responses:
        '201':
          description: Payment created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message_type:
                    type: string
                    example: pain.001.001.03
                  instruction_id:
                    type: string
                  end_to_end_id:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  message:
                    type: object
        '400':
          description: Invalid request
        '401':
          description: Authentication required
  
  /iso20022/payments/interbank-transfer:
    post:
      tags:
        - Payments
      summary: Create interbank transfer (pacs.008)
      description: Create FI to FI Credit Transfer message in JSON format
      parameters:
        - name: format
          in: query
          schema:
            type: string
            enum: [json, xml]
            default: json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - debtor
                - creditor
              properties:
                transaction_id:
                  type: string
                  example: TXN20250101001
                amount:
                  type: string
                  example: "1000000.00"
                settlement_date:
                  type: string
                  format: date
                  example: "2025-01-15"
                settlement_method:
                  type: string
                  enum: [INDA, INGA, COVE, CLRG]
                  default: INDA
                debtor:
                  type: object
                  properties:
                    name:
                      type: string
                    iban:
                      type: string
                creditor:
                  type: object
                  properties:
                    name:
                      type: string
                    iban:
                      type: string
                    bank_name:
                      type: string
                    bank_bic:
                      type: string
                remittance_info:
                  type: string
                purpose_code:
                  type: string
                  example: INTC
      responses:
        '201':
          description: Interbank transfer created
        '400':
          description: Invalid request
  
  /iso20022/convert/xml-to-json:
    post:
      tags:
        - Conversion
      summary: Convert XML to JSON
      description: Convert ISO 20022 XML message to JSON format
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: string
          text/xml:
            schema:
              type: string
      responses:
        '200':
          description: Conversion successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  format:
                    type: string
                    example: json
                  timestamp:
                    type: string
                    format: date-time
                  data:
                    type: object
        '400':
          description: Invalid XML
  
  /iso20022/convert/json-to-xml:
    post:
      tags:
        - Conversion
      summary: Convert JSON to XML
      description: Convert JSON message to ISO 20022 XML format
      parameters:
        - name: message_type
          in: query
          required: true
          schema:
            type: string
            example: pain.001
          description: Message type for XML namespace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Conversion successful
          content:
            application/xml:
              schema:
                type: string
        '400':
          description: Invalid JSON
  
  /iso20022/validate:
    post:
      tags:
        - Validation
      summary: Validate message
      description: Validate ISO 20022 message against JSON schema
      parameters:
        - name: message_type
          in: query
          required: true
          schema:
            type: string
          example: pain.001.001.03
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_valid:
                    type: boolean
                  message_type:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
        '400':
          description: Invalid request

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token authentication
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key authentication
  
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
