Kaminari Ad Invoicing API

openapi: 3.2.0
info:
  title: Kaminari Ad Invoicing API
  description: 'REST API for Kaminari Ad, the ad quality and ad security platform for publishers, ad networks, SSPs and DSPs. Submit ad creatives, ad tags and landing pages for scanning, read verdicts with evidence, manage policies, alerts and webhooks.


    Authenticate with an API key as a Bearer token: https://kaminari.ad/docs/developers/authentication'
  contact:
    name: Kaminari Ad Support
    url: https://kaminari.ad/contact
    email: support@kaminari.ad
  version: 0.1.0
servers:
- url: https://app.kaminari.ad
tags:
- name: Invoicing
paths:
  /api/v1/invoices:
    get:
      tags:
      - Invoicing
      summary: List Invoices
      description: List caller-org invoices with optional filters + pagination.
      operationId: list_invoices_api_v1_invoices_get
      security:
      - HTTPBearer: []
      parameters:
      - name: type
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/InvoiceType'
          - type: 'null'
          title: Type
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/InvoiceStatus'
          - type: 'null'
          title: Status
      - name: organization_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Organization Id
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
          title: Page
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_InvoiceResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/invoices/{invoice_id}/pdf:
    get:
      tags:
      - Invoicing
      summary: Get Invoice Pdf
      description: 'Stream the invoice PDF bytes (404 until rendered).


        Bytes are proxied through the API — never a presigned S3 URL (see

        ``artifact-serving.mdc``).'
      operationId: get_invoice_pdf_api_v1_invoices__invoice_id__pdf_get
      security:
      - HTTPBearer: []
      parameters:
      - name: invoice_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Invoice Id
      responses:
        '200':
          description: Invoice PDF bytes
          content:
            application/pdf: {}
        '404':
          description: Invoice not found or PDF not yet rendered
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    InvoiceType:
      type: string
      enum:
      - proforma
      - final
      title: InvoiceType
      description: "Kind of invoice. Drives numbering sequence prefix + workflow.\n\n* ``PROFORMA`` — the single document for every top-up (bank +\n  crypto). Issued up front (status=ISSUED); on settlement it flips\n  to PAID and the paid proforma IS the receipt. Carries no VAT line\n  per the EU/Cyprus deposit-on-account rationale. Number prefix\n  ``PF-``.\n* ``FINAL`` — end-of-period statement. For PREPAID orgs it is\n  informational (status=PAID on issue). For POSTPAID orgs it is\n  the bill and remains ISSUED until payment confirmation. Number\n  prefix ``IN-``."
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PaginatedResponse_InvoiceResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/InvoiceResponse'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
        limit:
          type: integer
          title: Limit
        pages:
          type: integer
          title: Pages
      type: object
      required:
      - items
      - total
      - page
      - limit
      - pages
      title: PaginatedResponse[InvoiceResponse]
    InvoiceResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        number:
          type: string
          title: Number
        organization_id:
          type: string
          format: uuid
          title: Organization Id
        type:
          type: string
          title: Type
        status:
          type: string
          title: Status
        total_micros:
          type: integer
          title: Total Micros
        net_micros:
          type: integer
          title: Net Micros
        vat_micros:
          type: integer
          title: Vat Micros
        vat_rate:
          type: string
          title: Vat Rate
        vat_reason:
          type: string
          title: Vat Reason
        currency:
          type: string
          title: Currency
        period_start:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Period Start
        period_end:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Period End
        issued_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Issued At
        paid_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Paid At
        voided_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Voided At
        has_pdf:
          type: boolean
          title: Has Pdf
        description:
          type: string
          title: Description
        payment_method:
          type: string
          title: Payment Method
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - number
      - organization_id
      - type
      - status
      - total_micros
      - net_micros
      - vat_micros
      - vat_rate
      - vat_reason
      - currency
      - period_start
      - period_end
      - issued_at
      - paid_at
      - voided_at
      - has_pdf
      - description
      - payment_method
      - created_at
      title: InvoiceResponse
      description: Projection of an :class:`Invoice` for the API layer.
    InvoiceStatus:
      type: string
      enum:
      - draft
      - issued
      - paid
      - voided
      - overdue
      title: InvoiceStatus
      description: 'Lifecycle states of an :class:`Invoice`.


        Transitions:

        - ``DRAFT`` → ``ISSUED`` (on issuance; PDF render follows)

        - ``ISSUED`` → ``PAID`` (on admin payment confirmation or gateway webhook)

        - ``ISSUED`` → ``VOIDED`` (admin void with reason)

        - ``ISSUED`` → ``OVERDUE`` (scheduled: past due-date, still unpaid)'
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer