parameters:
  - name: id
    in: path
    required: true
    description: Invoice primary key.
    schema:
      type: string
      format: uuid
    example: 88888888-8888-4888-8888-888888888888
get:
  tags: [Invoices]
  summary: Get an invoice
  description: Returns one invoice and its coding lines.
  operationId: get-api-invoices-id
  responses:
    "200":
      description: Invoice.
      content:
        application/json:
          schema:
            $ref: ../components/schemas.yaml#/Invoice
    "400":
      description: Invalid id.
      content:
        application/json:
          schema:
            $ref: ../components/schemas.yaml#/Error
    "401":
      description: Missing session.
      content:
        application/json:
          schema:
            $ref: ../components/schemas.yaml#/Error
    "404":
      description: Invoice not found.
      content:
        application/json:
          schema:
            $ref: ../components/schemas.yaml#/Error
patch:
  tags: [Invoices]
  summary: Update an invoice
  description: Patch header fields. Duplicate active vendor plus invoice number is a conflict.
  operationId: patch-api-invoices-id
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          properties:
            vendorId:
              type: string
              format: uuid
              example: 55555555-5555-4555-8555-555555555555
            invoiceNumber:
              type: string
              example: INV-1001
            amount:
              type: string
              example: "1250.00"
            dueDate:
              type: string
              example: "2026-09-01"
            status:
              type: string
              enum: [void]
              description: The only status PATCH may set. Approval and payment statuses go through decision routes.
              example: void
            paymentMethod:
              type: string
              enum: [check, ach]
              example: ach
            memo:
              type: string
              example: Updated memo
  responses:
    "200":
      description: Updated invoice.
      content:
        application/json:
          schema:
            $ref: ../components/schemas.yaml#/Invoice
    "400":
      description: Validation failed.
      content:
        application/json:
          schema:
            $ref: ../components/schemas.yaml#/Error
    "403":
      description: Caller lacks write:invoices.
      content:
        application/json:
          schema:
            $ref: ../components/schemas.yaml#/Error
    "404":
      description: Invoice not found.
      content:
        application/json:
          schema:
            $ref: ../components/schemas.yaml#/Error
    "409":
      description: Active vendor and invoice number already exist.
      content:
        application/json:
          schema:
            $ref: ../components/schemas.yaml#/Error