openapi: 3.1.0
info:
  title: Flomisma Settlement Ledger API
  version: 0.1.0
  description: >
    Immutable ledger entries, settlement fee calculation, contract state machine,
    encrypted vault, and invoice generation. Software/API layer only — no fund custody.
    Your money moves through your own Stripe or bank rails; Flomisma records the entries.
paths:
  /api/v1/ledger/entries:
    post:
      summary: Append an immutable ledger entry
      security: [{ LedgerApiKey: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [tenantId, debit_account, credit_account, transaction_type, amount]
              properties:
                tenantId: { type: string }
                debit_account: { type: string }
                credit_account: { type: string }
                transaction_type:
                  type: string
                  enum: [SETTLEMENT, REVENUE, REFUND, FEE, INTERNAL_SETTLEMENT, WORK_PROOF, INCENTIVE, RESERVE_DEPOSIT, RESERVE_WITHDRAWAL, VERIFICATION_REWARD, SLASHING_PENALTY]
                amount: { type: number }
                reference_id: { type: string }
                metadata_json: { type: object }
      responses:
        '201':
          description: Entry created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      entryId: { type: string }
    get:
      summary: List ledger entries
      security: [{ LedgerApiKey: [] }]
      parameters:
        - name: tenantId
          in: query
          required: true
          schema: { type: string }
        - name: limit
          in: query
          schema: { type: integer, default: 50 }
        - name: offset
          in: query
          schema: { type: integer, default: 0 }
      responses:
        '200':
          description: List of entries
  /api/v1/ledger/calculate-settlement:
    post:
      summary: Preview settlement fee calculation
      security: [{ LedgerApiKey: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [contractId, tenantId, amount, partyAId]
              properties:
                amount: { type: number }
                currency: { type: string, default: USD }
                settlementMethod: { type: string, enum: [FIAT], default: FIAT }
                feeBasisPoints: { type: integer, default: 25 }
                isMicroTask: { type: boolean, default: false }
                isRevenueEnabled: { type: boolean, default: true }
      responses:
        '200':
          description: Settlement preview
  /api/v1/ledger/contracts:
    post:
      summary: Create a ledger contract
      security: [{ LedgerApiKey: [] }]
      responses:
        '201':
          description: Contract created
    get:
      summary: List contracts
      security: [{ LedgerApiKey: [] }]
      responses:
        '200':
          description: List of contracts
  /api/v1/ledger/contracts/{id}:
    get:
      summary: Get contract detail
      security: [{ LedgerApiKey: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Contract detail
  /api/v1/ledger/contracts/{id}/release:
    post:
      summary: Record a release
      security: [{ LedgerApiKey: [] }]
      responses:
        '200':
          description: Release recorded
  /api/v1/ledger/vault:
    post:
      summary: Store an encrypted secret
      security: [{ LedgerApiKey: [] }]
      responses:
        '201':
          description: Secret stored
    get:
      summary: List vault keys
      security: [{ LedgerApiKey: [] }]
      responses:
        '200':
          description: List of keys
  /api/v1/ledger/vault/{key}:
    get:
      summary: Retrieve a decrypted secret
      security: [{ LedgerApiKey: [] }]
      responses:
        '200':
          description: Decrypted secret
    delete:
      summary: Delete a secret
      security: [{ LedgerApiKey: [] }]
      responses:
        '200':
          description: Secret deleted
  /api/v1/ledger/invoices:
    post:
      summary: Generate a PDF invoice
      security: [{ LedgerApiKey: [] }]
      responses:
        '201':
          description: Invoice generated
  /api/v1/ledger/invoices/{contractId}:
    get:
      summary: Download invoice PDF
      security: [{ LedgerApiKey: [] }]
      responses:
        '200':
          description: PDF binary
components:
  securitySchemes:
    LedgerApiKey:
      type: apiKey
      in: header
      name: x-ledger-api-key
