openapi: 3.0.3
info:
  title: TaxTask Public API
  description: |
    REST API for third-party developers. Authenticate with an API key (Bearer or X-API-Key).
    Keys and scopes are managed in your TaxTask dashboard (Settings → API).
  version: 1.0.0
  contact:
    name: TaxTask

servers:
  - url: https://api.taxtask.com/v1
    description: Production
  - url: http://localhost:3000/api/v1
    description: Local

security:
  - ApiKeyAuth: []

paths:
  /health:
    get:
      summary: Health check
      description: Returns API health (no authentication required).
      security: []
      responses:
        '200':
          description: Service healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, example: healthy }
                  version: { type: string }
                  timestamp: { type: string, format: date-time }
                  service: { type: string }

  /transactions:
    get:
      summary: List transactions
      description: List transactions for the authenticated tenant. Requires scope `read:transactions` or `admin:all`.
      parameters:
        - name: page
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 50, default: 20 }
        - name: status
          in: query
          schema: { type: string, enum: [pending, categorized, approved, validated, flagged, rejected, filed] }
      responses:
        '200':
          description: Paginated list of transactions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/TransactionSummary' } }
                  meta:
                    type: object
                    properties:
                      page: { type: integer }
                      limit: { type: integer }
                      total: { type: integer }
                      total_pages: { type: integer }
        '401':
          description: Invalid or missing API key
        '403':
          description: Insufficient scope

  /invoices:
    get:
      summary: List invoices
      description: List invoices for the authenticated tenant. Requires scope `read:invoices` or `admin:all`.
      parameters:
        - name: page
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 50, default: 20 }
        - name: status
          in: query
          schema: { type: string, enum: [draft, pending, submitted, approved, rejected, cancelled] }
      responses:
        '200':
          description: Paginated list of invoices
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/InvoiceSummary' } }
                  meta:
                    type: object
                    properties:
                      page: { type: integer }
                      limit: { type: integer }
                      total: { type: integer }
                      total_pages: { type: integer }
        '401':
          description: Invalid or missing API key
        '403':
          description: Insufficient scope

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Bearer token (e.g. "Bearer tt_xxxxxxxx") or use X-API-Key header

  schemas:
    TransactionSummary:
      type: object
      properties:
        id: { type: string, format: uuid }
        branch_id: { type: string, format: uuid }
        type: { type: string, enum: [sale, purchase, expense, refund] }
        source: { type: string }
        status: { type: string }
        amount: { type: number }
        currency: { type: string }
        description: { type: string }
        reference: { type: string }
        transaction_date: { type: string, format: date }
        created_at: { type: string, format: date-time }

    InvoiceSummary:
      type: object
      properties:
        id: { type: string, format: uuid }
        branch_id: { type: string, format: uuid }
        invoice_number: { type: string }
        status: { type: string }
        payment_status: { type: string }
        total_amount: { type: number }
        currency: { type: string }
        issue_date: { type: string, format: date }
        created_at: { type: string, format: date-time }