> ## 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.

# Get invoice PDF

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

Standard: Roh-PDF (`application/pdf`).

Mit Query `annotations=true`: JSON (`application/json`) mit Base64-PDF (`pdf_base64`),
Dateimetadaten (`metadata`: Rechnungs-ID, Dokument-ID, `file_id`) sowie `annotations` in derselben
Struktur wie `GET /invoices/{id}/items` (inkl. `positions` für PDF-Overlays).


By default returns raw PDF bytes. With `?annotations=true`, returns JSON: base64 PDF, `metadata` (invoice, document, file ids), and `annotations` matching `GET /invoices/{id}/items` (including `positions` for overlays).


## OpenAPI

````yaml GET /invoices/{id}/pdf
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/{id}/pdf:
    get:
      tags:
        - Invoices
      summary: Rechnungs-PDF abrufen
      description: >
        **Erforderliche Berechtigungen:** `invoices:read`


        Standard: Roh-PDF (`application/pdf`).


        Mit Query `annotations=true`: JSON (`application/json`) mit Base64-PDF
        (`pdf_base64`),

        Dateimetadaten (`metadata`: Rechnungs-ID, Dokument-ID, `file_id`) sowie
        `annotations` in derselben

        Struktur wie `GET /invoices/{id}/items` (inkl. `positions` für
        PDF-Overlays).
      operationId: getInvoicePdf
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: >
            Rechnungs-ID (Integer). 

            Hinweis: Die in Listenantworten zurückgegebene ID ist ein String
            (z.B. "123"), kann aber direkt im Pfadparameter verwendet werden.

            Die API parst den String automatisch zu einem Integer.
        - name: annotations
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: >
            Wenn `true`, ist die Antwort JSON mit `pdf_base64`, `metadata` und
            `annotations` (Zeilenpositionen).
      responses:
        '200':
          description: PDF-Bytes oder JSON-Bundle
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                $ref: '#/components/schemas/InvoicePdfWithAnnotationsResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Rechnung oder Dokument nicht gefunden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKey:
            - invoices:read
components:
  schemas:
    InvoicePdfWithAnnotationsResponse:
      type: object
      required:
        - file_name
        - pdf_base64
        - metadata
        - annotations
      properties:
        file_name:
          type: string
          description: Empfohlener Dateiname für das PDF
        pdf_base64:
          type: string
          description: PDF-Inhalt Base64-kodiert
        metadata:
          $ref: '#/components/schemas/InvoicePdfDocumentMetadata'
        annotations:
          $ref: '#/components/schemas/InvoiceItemsByInvoiceId'
    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
    InvoicePdfDocumentMetadata:
      type: object
      required:
        - invoice_id
      properties:
        invoice_id:
          type: string
          description: Rechnungs-ID
        document_id:
          type: string
          format: uuid
          nullable: true
          description: Verknüpfte Dokument-ID (falls gesetzt)
        file_id:
          type: string
          format: uuid
          nullable: true
          description: Datei-ID auf der Rechnung
    InvoiceItemsByInvoiceId:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceLineItem'
          description: Rechnungspositionen sortiert nach index
    InvoiceLineItem:
      type: object
      properties:
        index:
          type: integer
          description: Sortierindex der Position auf der Rechnung
          example: 0
        number:
          type: string
          nullable: true
          description: >-
            Die vom Lieferanten auf der Rechnung angegebene Positionsnummer (z.
            B. "10" oder "1.1"). Nicht mit dem technischen Sortierfeld `index`
            verwechseln.
          example: '10'
        id:
          type: integer
          description: Die Rechnungspositions-ID
        product_number:
          type: string
          description: Die Produktnummer
        title:
          type: string
          description: Der Titel des Produkts
        description:
          type: string
          description: Die Beschreibung des Produkts
        type:
          $ref: '#/components/schemas/ProductTypeKey'
          description: Der Typ des Produkts
        quantity:
          type: number
          format: double
          description: Die Menge
        unit:
          type: string
          description: Die Einheit
        unit_net_price:
          type: number
          format: double
          description: Der Nettoeinzelpreis
        net_price:
          type: number
          format: double
          description: Der Nettopreis
        deducted_quantity:
          type: number
          format: double
          nullable: true
          description: Die abgezogene Menge
        deducted_unit_net_price:
          type: number
          format: double
          nullable: true
          description: Der abgezogene Nettoeinzelpreis
        deducted_net_price:
          type: number
          format: double
          nullable: true
          description: Der abgezogene Nettopreis
        delivery_number:
          type: string
          description: Die Lieferscheinnummer
        delivery_date:
          type: string
          format: date
          description: Das Lieferdatum
        item_position:
          type: integer
          description: >-
            Position der manuell zugeordneten Lieferung, falls die
            Rechnungsposition mit einem Lieferschein abgeglichen wurde. Für die
            auf der Rechnung gedruckte Positionsnummer siehe `number`.
        matched_delivery_id:
          type: string
          format: uuid
          description: Die ID der zugeordneten Lieferung
        matched_product_id:
          type: string
          format: uuid
          description: Die ID des zugeordneten Produkts
        matched_price:
          type: boolean
          description: Ob der Preis zugeordnet wurde
        matched_quantity:
          type: boolean
          description: Ob die Menge zugeordnet wurde
        discount:
          type: number
          format: double
          description: Der Rabatt
        special_discount:
          type: number
          format: double
          description: Der Sonderrabatt
        comment:
          type: string
          description: Ein optionaler Kommentar
        account_id:
          type: string
          format: uuid
          nullable: true
          description: Verknüpftes Sachkonto (falls gesetzt)
        llm_factual_match_reason:
          type: string
          nullable: true
          description: Begründung der KI-gestützten sachlichen Positionsprüfung
        llm_factual_match_status:
          type: string
          nullable: true
          description: Status der KI-gestützten sachlichen Positionsprüfung
        positions:
          type: array
          description: Bounding-Boxen extrahierter Felder (JSON-Struktur)
          items:
            type: object
            additionalProperties: true
    ProductTypeKey:
      type: string
      enum:
        - REMOVAL
        - BITUMEN
        - CONCRETE
        - SINGLE_GOODS
        - REINFORCEMENT
        - BULK_GOODS
        - TRANSPORT
        - RENTAL
        - MASONRY
        - MODULAR
        - WOOD
        - FUEL
        - FEES
        - SERVICES
        - RETURNS
        - WAGES
        - PERSONNEL_COSTS
        - ASPHALT_PAVEMENT
        - EARTH_MATERIALS
        - STEEL_REINFORCEMENT
        - PREFAB_CONCRETE
        - REINFORCEMENT_ACCESSORIES
        - PIPING
        - CHEMICALS
        - BINDING_MATERIALS
        - STONES
        - INSULATION
        - WATERPROOFING
        - OTHER_MATERIALS
        - WASTE_REMOVAL
        - FORMWORK
        - SITE_SETUP
        - TOOLS
        - CLOTHING_SAFETY_EQUIPMENT
        - OFFICE_COSTS
        - OPERATING_MATERIALS
        - WATER
        - ELECTRICITY
      description: Schlüssel, der den Typ eines Produkts darstellt.
  responses:
    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.

````