> ## Documentation Index
> Fetch the complete documentation index at: https://developer.comstruct.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List invoices

> **Erforderliche Berechtigungen:** `invoices:read`

Gibt eine paginierte Liste von Rechnungen zurück, sortiert nach `created_at` in absteigender Reihenfolge.
Enthält `invoice_accounts`, aber keinen Verlauf (`invoice_history`) und keine Rechnungspositionen.
Rechnungspositionen: `GET /invoices/{id}/items`. Verlauf: `GET /invoices/{id}/history`. Jede Rechnung enthält `created_at` und `updated_at` (letzte Änderung, serverseitig gepflegt).
Kann nach Status gefiltert werden.




## OpenAPI

````yaml GET /invoices
openapi: 3.0.3
info:
  title: comstruct Public API
  description: >
    Die comstruct API ist eine umfassende und flexible Lösung zur Optimierung
    des Materialbeschaffungsprozesses für Unternehmen. Diese API bietet eine
    einfache Schnittstelle für Entwickler, um auf Materialbeschaffungsdaten
    zuzugreifen und diese zu verwalten, einschließlich Lieferanteninformationen,
    Lieferungen und Projekte.


    ## Erste Schritte

    Um Zugang zur comstruct API zu erhalten, wenden Sie sich bitte an Ihren
    zuständigen Customer Success Manager. Unser Expertenteam steht Ihnen mit
    erstklassigem Support zur Verfügung, um Ihnen zu helfen, das Beste aus
    unserer API herauszuholen.


    ## Authentifizierung

    Alle API-Endpunkte unter `/v1` erfordern eine Authentifizierung mittels
    API-Schlüssel im `x-api-key`-Header. Jeder API-Schlüssel hat spezifische
    Berechtigungen (Scopes), die bestimmen, welche Endpunkte und Operationen
    verfügbar sind. Die Authentifizierung wird durch Middleware durchgesetzt,
    die den API-Schlüssel und die Berechtigungen für jede Anfrage validiert.


    Kalender-Endpunkte unter `/calendars` verwenden Token-basierte
    Authentifizierung anstelle von API-Schlüsseln.


    ## Datenformate

    - Alle Zeitstempel sind im ISO 8601-Format (UTC)

    - Geldbeträge werden als Dezimalzahlen dargestellt

    - IDs sind UUIDs, sofern nicht anders angegeben


    ## Anfragegrößenbeschränkungen

    - PDF-Rechnungsverarbeitung, benutzerdefinierte Rechnungsverarbeitung und
    Workflow-Verarbeitung: 32MiB

    - Alle anderen Endpunkte: 10MiB


    ## Fehlerbehandlung

    Die API verwendet Standard-HTTP-Statuscodes und gibt detaillierte
    Fehlermeldungen im JSON-Format zurück. Weitere Details finden Sie in den
    Fehlerschemas.


    ## Integrationsmuster

    - **SAP-Integration**: Spezialisierte Endpunkte für SAP-ERP-Systeme

    - **Projektverwaltung**: Vollständiges Projektlebenszyklusmanagement mit
    Benutzerrollen

    - **Lieferverfolgung**: Unterstützung mehrerer Lieferscheinformate
    (OpenTrans, PAHM, Q-Point, benutzerdefiniert)

    - **Rechnungsverarbeitung**: Automatisierte Rechnungsanalyse und
    -validierung mit KI/GPT-Unterstützung

    - **Auftragsverwaltung**: IDS-Auftragsverarbeitung mit XML-Parsing und
    Projektkalenderintegration

    - **Kalenderintegration**: Separate Kalender-Endpunkte für
    iCalendar-Abonnement-Feeds
  version: 1.0.9
  license:
    name: Proprietary
    url: https://comstruct.com
  contact:
    name: comstruct ICT GmbH
    url: https://comstruct.com
    email: support@comstruct.com
  termsOfService: https://comstruct.com/datenschutzerklarung/
  x-logo:
    url: https://app.comstruct.com/logo-light-text.png
    altText: comstruct logo
servers:
  - url: https://api.comstruct.com/v1
    description: Haupt-API-Endpunkte (erfordert API-Schlüssel-Authentifizierung)
    variables: {}
  - url: https://api.comstruct.com
    description: Basisserver für Kalender- und IDS-Endpunkte (andere Authentifizierung)
    variables: {}
security:
  - ApiKey: []
tags:
  - name: Projects
    description: Endpunkte für Projekte.
  - name: Projects (SAP)
    description: SAP-spezifische Projekt-Endpunkte.
  - name: Project Regions
    description: Endpunkte für die Verwaltung von Projektregionen.
  - name: Deliveries
    description: Endpunkte für Lieferungen.
  - name: Deliveries (Supplier)
    description: Lieferantenspezifische Liefer-Endpunkte.
  - name: Accounts
    description: Endpunkte für die Verwaltung von Sachkonten.
  - name: Payment Terms
    description: Endpunkte für die Verwaltung von Zahlungsbedingungen.
  - name: Tax Codes
    description: Endpunkte für die Verwaltung von Steuercodes.
  - name: Company Codes
    description: Endpunkte für die Verwaltung von Buchungskreisen (juristische Einheiten).
  - name: Suppliers
    description: Endpunkte für die Verwaltung von Lieferanten.
  - name: Purchase Orders
    description: Endpunkte für Bestellungen.
  - name: Purchase Orders (SAP)
    description: SAP-spezifische Bestellungs-Endpunkte.
  - name: Orders (Supplier)
    description: >-
      Lieferantenspezifische Bestellungs-Endpunkte (Bestätigung, Ablehnung,
      Bearbeitung).
  - name: Suppliers (SAP)
    description: SAP-spezifische Lieferanten-Endpunkte.
  - name: Invoices
    description: Endpunkte für Rechnungen.
  - name: Invoices (Supplier)
    description: Lieferantenspezifische Rechnungs-Endpunkte.
  - name: Invoices (SAP)
    description: SAP-spezifische Rechnungs-Endpunkte.
  - name: Invoice Dimensions
    description: >
      Rechnungs-Dimensionen (benutzerdefinierte Eigenschaften) und Zuweisungen
      auf Rechnung (`header`), Position (`line_item`) oder Kontierung
      (`account`).


      Dimensionen haben den Typ `option` (vordefinierte Werte) oder `text`
      (Freitext über `dimension_id` + `text_value`). Bulk-Konto-POST
      (`/assignments/account/bulk`) unterstützt nur Options-Zuweisungen über
      `option_ids`; Freitext auf Kontoebene über Einzel-POST, PATCH-Bulk oder
      Positions-Bulk.
  - name: Workflows
    description: Endpunkte für Workflow- und Prozessmanagement.
  - name: Calendar
    description: Kalender-Abonnement-Endpunkte mit separater Authentifizierung.
  - name: Orders
    description: Endpunkte für Auftragsverarbeitung und -verwaltung.
paths:
  /invoices:
    get:
      tags:
        - Invoices
      summary: Rechnungen auflisten
      description: >
        **Erforderliche Berechtigungen:** `invoices:read`


        Gibt eine paginierte Liste von Rechnungen zurück, sortiert nach
        `created_at` in absteigender Reihenfolge.

        Enthält `invoice_accounts`, aber keinen Verlauf (`invoice_history`) und
        keine Rechnungspositionen.

        Rechnungspositionen: `GET /invoices/{id}/items`. Verlauf: `GET
        /invoices/{id}/history`. Jede Rechnung enthält `created_at` und
        `updated_at` (letzte Änderung, serverseitig gepflegt).

        Kann nach Status gefiltert werden.
      operationId: listInvoices
      parameters:
        - name: limit
          in: query
          description: Anzahl der Einträge pro Seite (max. 500, Standard 25)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 25
            example: 25
        - name: offset
          in: query
          description: Anzahl der zu überspringenden Einträge für die Paginierung
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            example: 0
        - name: status
          in: query
          description: Nach Rechnungsstatus filtern
          required: false
          schema:
            type: string
            enum:
              - NEW
              - PROCESSING
              - FACTUAL_CHECKING
              - PRICE_CHECKING
              - CHECKED
              - CANCELLED
              - ERROR
              - OPEN
      responses:
        '200':
          description: Erfolgreich
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Invoice'
                    description: Array von Rechnungen
                  total:
                    type: integer
                    description: Gesamtanzahl der Rechnungen
                    example: 150
                  limit:
                    type: integer
                    nullable: true
                    description: Anzahl der Einträge pro Seite
                    example: 25
                  offset:
                    type: integer
                    description: Anzahl der übersprungenen Einträge
                    example: 0
                  hasNext:
                    type: boolean
                    description: Ob weitere Seiten verfügbar sind
                    example: true
                  hasPrevious:
                    type: boolean
                    description: Ob vorherige Seiten verfügbar sind
                    example: false
                  totalPages:
                    type: integer
                    description: Gesamtanzahl der Seiten
                    example: 6
                  currentPage:
                    type: integer
                    description: Aktuelle Seitennummer (0-basiert)
                    example: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
      security:
        - ApiKey:
            - invoices:read
components:
  schemas:
    Invoice:
      type: object
      readOnly: true
      properties:
        id:
          type: string
          description: >-
            Die eindeutige Kennung der Rechnung (numerischer String, der eine
            Integer-ID darstellt)
          example: '123'
          pattern: ^[0-9]+$
        external_id:
          type: string
          description: Die externe Kennung der Rechnung
          example: EXT-123
        invoice_number:
          type: string
          description: Die Rechnungsnummer
          example: INV-2024-001
        invoice_date:
          type: string
          format: date
          description: Das Rechnungsdatum
          example: '2024-01-15'
        due_date:
          type: string
          format: date
          description: Das Fälligkeitsdatum der Rechnung
          example: '2024-02-15'
        receipt_date:
          type: string
          format: date-time
          description: Das Eingangsdatum der Rechnung
        project_id:
          type: string
          format: uuid
          description: Die Projektkennung
        project_number:
          type: string
          description: Die Projektnummer
          example: PRJ-2024-001
        supplier_id:
          type: string
          format: uuid
          nullable: true
          description: Die Lieferantenkennung
        supplier_name:
          type: string
          description: Der Name des Lieferanten
          example: ABC Supplies Ltd.
        supplier_tax_id:
          type: string
          description: Die Steuer-ID des Lieferanten
        supplier_iban:
          type: string
          description: Die IBAN des Lieferanten
        customer_id:
          type: string
          format: uuid
          description: Die Kundenkennung
        currency:
          type: string
          description: Die Rechnungswährung (ISO 4217-Code)
          example: EUR
        net_amount:
          type: number
          format: double
          description: Der Nettobetrag der Rechnung
          example: 1000
        total_tax_amount:
          type: number
          format: double
          description: Der Gesamtsteuerbetrag der Rechnung
          example: 190
        total_amount:
          type: number
          format: double
          description: Der Gesamtbetrag der Rechnung
          example: 1190
        deducted_net_amount:
          type: number
          format: double
          nullable: true
          description: Der abgezogene Nettobetrag der Rechnung
          example: 800
        deducted_total_tax_amount:
          type: number
          format: double
          nullable: true
          description: Der abgezogene Gesamtsteuerbetrag der Rechnung
          example: 152
        deducted_total_amount:
          type: number
          format: double
          nullable: true
          description: Der abgezogene Gesamtbetrag (brutto) der Rechnung
          example: 952
        tax_rate:
          type: number
          format: double
          description: Der Steuersatz der Rechnung
        status:
          type: string
          enum:
            - NEW
            - PROCESSING
            - FACTUAL_CHECKING
            - PRICE_CHECKING
            - CHECKED
            - CANCELLED
            - ERROR
            - OPEN
          description: Der Rechnungsstatus
          example: NEW
        document_type:
          type: string
          description: Dokumenttyp (z.B. INVOICE, CREDIT_NOTE)
          example: INVOICE
        electronic_invoice_type:
          type: string
          enum:
            - ZUGFERD
            - XRECHNUNG
            - FACTURX
          description: Typ der elektronischen Rechnung (falls zutreffend)
          example: ZUGFERD
        down_payment_number:
          type: number
          description: Abschlagszahlungsnummer
        payment_reference:
          type: string
          description: Zahlungsreferenz (z.B. Schweizer QR-Rechnung Referenz)
          example: RF18539007547034
        reference_type:
          type: string
          enum:
            - QRR
            - SCOR
            - NON
          description: Typ der Zahlungsreferenz
          example: QRR
        payment_term:
          type: object
          nullable: true
          properties:
            number:
              type: string
            title:
              type: string
          description: Zahlungsbedingungsdetails
        region_id:
          type: string
          format: uuid
          description: Die Regionskennung
        legal_entity_id:
          type: string
          format: uuid
          description: Die Gesellschaftskennung
        project_region:
          type: object
          nullable: true
          properties:
            id:
              type: string
            title:
              type: string
            number:
              type: string
          description: Projektregion-Informationen
        legal_entity:
          type: object
          nullable: true
          properties:
            id:
              type: string
            title:
              type: string
            number:
              type: string
          description: Gesellschaftsinformationen
        supplier:
          type: object
          nullable: true
          properties:
            id:
              type: string
            title:
              type: string
            external_id:
              type: string
            legal_uid:
              type: string
          description: Lieferanteninformationen
        project:
          type: object
          nullable: true
          properties:
            id:
              type: string
            title:
              type: string
            project_number:
              type: string
            description:
              type: string
            project_region:
              type: object
              properties:
                number:
                  type: string
                title:
                  type: string
            legal_entity:
              type: object
              properties:
                number:
                  type: string
                title:
                  type: string
          description: Projektinformationen
        invoice_accounts:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceAccount'
          description: Rechnungskonten
        document:
          type: object
          nullable: true
          properties:
            id:
              type: string
            title:
              type: string
          description: Dokumentinformationen
        comment:
          type: string
          description: Ein optionaler Kommentar
        payment_terms:
          type: string
          description: Die Zahlungsbedingungen (Freitext)
        payment_term_id:
          type: string
          format: uuid
          nullable: true
          description: Die Zahlungsbedingungskennung
        discount_rate:
          type: number
          format: double
          description: Der Skontosatz
        discount_date:
          type: string
          format: date
          description: Das Skontodatum
        file_id:
          type: string
          format: uuid
          description: Die Dateikennung für das Rechnungsdokument
        created_at:
          type: string
          format: date-time
          description: Der Erstellungszeitstempel der Rechnung
          example: '2024-01-15T10:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: Zeitstempel der letzten Aktualisierung der Rechnung (serverseitig)
          example: '2024-01-16T14:30:00Z'
        assignee_id:
          type: string
          format: uuid
          nullable: true
          description: Die ID des für die Rechnungsprüfung verantwortlichen Benutzers
    InvoiceAccount:
      type: object
      properties:
        net_amount:
          type: number
          format: double
          description: Nettobetrag
          example: 1000
        gross_amount:
          type: number
          format: double
          description: Bruttobetrag
          example: 1190
        tax_amount:
          type: number
          format: double
          description: Steuerbetrag
          example: 190
        account_type:
          type: string
          enum:
            - DEBIT
            - CREDIT
          description: Kontoart (Soll/Haben)
          example: DEBIT
        comment:
          type: string
          description: Kommentar
        quantity:
          type: number
          format: double
          description: Menge
          example: 10
        unit:
          type: string
          description: Einheit
          example: Stück
        project_id:
          type: string
          format: uuid
          description: Projektkennung
        project:
          type: object
          nullable: true
          properties:
            id:
              type: string
            title:
              type: string
            project_number:
              type: string
          description: Projektinformationen
        account:
          type: object
          nullable: true
          properties:
            id:
              type: string
            number:
              type: string
            title:
              type: string
          description: Sachkonto-Informationen
        tax_code:
          type: object
          nullable: true
          properties:
            id:
              type: string
            number:
              type: string
            title:
              type: string
          description: Steuercode-Informationen
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Fehlermeldung, die beschreibt, was schiefgelaufen ist
        message:
          type: string
          description: Zusätzliche Fehlerdetails oder benutzerfreundliche Nachricht
        success:
          type: boolean
          description: Zeigt Fehlschlag an, wenn in Fehlerantworten vorhanden
      anyOf:
        - required:
            - error
        - required:
            - message
        - required:
            - success
      example:
        error: Validation failed
        message: The provided data did not pass validation checks
  responses:
    BadRequest:
      description: Ungültige Anfrage - Ungültige Eingabe oder Validierung fehlgeschlagen
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            validation_error:
              summary: Feldvalidierungsfehler
              value:
                error: Validation failed for field external_id
            array_expected:
              summary: Array erwartet
              value:
                error: Invalid request body. Expected an array of purchase orders.
    Forbidden:
      description: Verboten - Ungültige oder fehlende Berechtigung
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalid_scope:
              summary: Ungültige Berechtigung
              value:
                message: Invalid scope.
            missing_scope:
              summary: Fehlende spezifische Berechtigung
              value:
                error: 'Unauthorized. Missing scope: projects:write'
            missing_invoices_scope:
              summary: Fehlende Rechnungsberechtigung
              value:
                error: 'Unauthorized. Missing scope: invoices:write'
            missing_suppliers_scope:
              summary: Fehlende Lieferantenberechtigung
              value:
                error: 'Unauthorized. Missing scope: suppliers:write'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >
        API-Schlüssel zur Authentifizierung. Kontaktieren Sie Ihren Customer
        Success Manager, um einen API-Schlüssel zu erhalten.


        Jeder Endpunkt erfordert spezifische Berechtigungen (Scopes); die
        erforderlichen Scopes werden pro Endpunkt angezeigt.

````