openapi: 3.1.0
info:
  title: Logynfra Financial OS API
  version: "v1"
  description: >
    Institutional Grade Financial Infrastructure for Global Trade. 
    Handles multi-currency wallets, automated tax calculations, and freight factoring.
servers:
  - url: https://finance.logynfra.com/v1
    description: Production Environment

paths:
  /wallets:
    post:
      summary: Create a virtual freight wallet
      operationId: createWallet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ownerId: { type: string }
                currency: { type: string, default: 'USD' }
      responses:
        '201':
          description: Wallet created
  
  /wallets/{walletId}/balance:
    get:
      summary: Get multi-currency balances
      operationId: getBalance
      parameters:
        - name: walletId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Current balances across currencies

  /taxes/calculate:
    post:
      summary: Calculate Landed Cost (Duties & Taxes)
      description: Returns VAT, Excise, and Import Duties for target countries.
      operationId: calculateLandedCost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxCalculationRequest'
      responses:
        '200':
          description: Detailed tax breakdown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxCalculationResponse'

  /settle/payout:
    post:
      summary: Escrow settlement (Release on Delivery)
      description: Settles freight costs once POD is verified.
      operationId: settlePayout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                shipmentId: { type: string }
                walletId: { type: string }
      responses:
        '200':
          description: Funds released from escrow

  /lending/factor-invoice:
    post:
      summary: Request freight factoring
      description: Carriers can request early payment against active shipments.
      operationId: factorInvoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                shipmentId: { type: string }
                requestedAmount: { type: number }
      responses:
        '200':
          description: Factoring request processed

components:
  schemas:
    TaxCalculationRequest:
      type: object
      properties:
        originCountry: { type: string }
        destinationCountry: { type: string }
        items:
          type: array
          items:
            type: object
            properties:
              description: { type: string }
              hsCode: { type: string }
              value: { type: number }
              currency: { type: string }
    TaxCalculationResponse:
      type: object
      properties:
        totalDuties: { type: number }
        totalVat: { type: number }
        localCurrency: { type: string }
        exchangeRate: { type: number }
        breakdown: { type: object }
