openapi: 3.1.0
info:
  title: Finance API
  version: "1.0.0"
  description: |
    Invoices and departmental cost reports. Read-only.
    Data classification: sensitive. Apps must surface the sensitive-data banner.
servers:
  - url: /apis/finance

paths:
  /invoices:
    get:
      summary: List invoices
      operationId: listInvoices
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [draft, sent, paid, overdue, cancelled]
        - name: department
          in: query
          schema: { type: string }
        - name: limit
          in: query
          schema: { type: integer, default: 25, minimum: 1, maximum: 200 }
      responses:
        '200':
          description: Invoices
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Invoice' }
              examples:
                default:
                  value:
                    - id: INV-2026-0142
                      vendor: Cloudwerks ApS
                      department: IT
                      amount: 18450.00
                      currency: DKK
                      status: overdue
                      dueDate: "2026-04-30"
                      issuedAt: "2026-03-30"
                    - id: INV-2026-0141
                      vendor: Designstudio Nord
                      department: Marketing
                      amount: 7250.50
                      currency: DKK
                      status: overdue
                      dueDate: "2026-04-15"
                      issuedAt: "2026-03-15"
                    - id: INV-2026-0140
                      vendor: Kontorforsyning A/S
                      department: HR
                      amount: 1290.00
                      currency: DKK
                      status: paid
                      dueDate: "2026-04-10"
                      issuedAt: "2026-03-10"

  /costs/by-department:
    get:
      summary: Cost roll-up by department
      operationId: costsByDepartment
      parameters:
        - name: period
          in: query
          description: ISO-month (YYYY-MM) or quarter (YYYY-Qn) or year (YYYY)
          schema: { type: string }
          example: "2026-Q1"
      responses:
        '200':
          description: Per-department costs
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/DepartmentCost' }
              examples:
                default:
                  value:
                    - department: IT
                      period: "2026-Q1"
                      amount: 412300.00
                      currency: DKK
                    - department: HR
                      period: "2026-Q1"
                      amount: 88100.00
                      currency: DKK
                    - department: Marketing
                      period: "2026-Q1"
                      amount: 173600.00
                      currency: DKK

components:
  schemas:
    Invoice:
      type: object
      required: [id, vendor, department, amount, currency, status, dueDate, issuedAt]
      properties:
        id: { type: string }
        vendor: { type: string }
        department: { type: string }
        amount: { type: number }
        currency: { type: string, example: DKK }
        status:
          type: string
          enum: [draft, sent, paid, overdue, cancelled]
        dueDate: { type: string, format: date }
        issuedAt: { type: string, format: date }
    DepartmentCost:
      type: object
      required: [department, period, amount, currency]
      properties:
        department: { type: string }
        period: { type: string }
        amount: { type: number }
        currency: { type: string, example: DKK }