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

# Rechnung verarbeiten (eigenes Format)

> **Erforderliche Berechtigungen:** `invoices:write`

Verarbeitet ein benutzerdefiniertes Rechnungsformat mittels GPT/KI-Parsing.
Akzeptiert PDF- oder TIFF-Dateien bis zu 32MiB und verarbeitet sie mittels generativer KI zur Rechnungsdatenextraktion.

Optionale Request-Header können vordefinierte Werte für Lieferant, Projekt und externe Dokument-ID
übergeben und damit die von der KI extrahierten Felder überschreiben.

Der API-Schlüssel muss mit einem Lieferanten verknüpft sein.

Akzeptiert entweder einen einzelnen rohen PDF-/TIFF-Body (Legacy) oder `multipart/form-data`
mit optionalem `xml`-Teil und einem oder mehreren `pdf`-Teilen. Bei XML laufen die
automatisierten Prüfungen auf dem XML; die PDF(s) dienen der Visualisierung (mehrere PDFs werden gemerged).


## Übersicht

Verarbeitet Rechnungen als PDF- oder TIFF-Datei mit KI-gestützter Datenextraktion. Optionale Request-Header können vordefinierte Werte für Lieferant, Projekt und externe Dokument-ID übergeben und damit die von der KI extrahierten Felder überschreiben.

Akzeptiert entweder einen einzelnen rohen PDF-/TIFF-Body (Legacy) oder `multipart/form-data` mit optionalem `xml`-Teil und einem oder mehreren `pdf`-Teilen. Bei XML laufen die automatisierten Prüfungen auf dem XML; die PDF(s) dienen der Visualisierung (mehrere PDFs werden gemerged).

## Berechtigungen

| Scope            | Tenant-Typ                  |
| ---------------- | --------------------------- |
| `invoices:write` | Lieferant (`SUPPLIER_ONLY`) |

Der API-Schlüssel muss mit einem Lieferanten verknüpft sein.

## Header

| Header           | Pflicht | Beschreibung                                                                                                               |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `x-api-key`      | Ja      | API-Schlüssel mit Scope `invoices:write`                                                                                   |
| `Content-Type`   | Ja      | `application/pdf`, `application/tiff` oder `multipart/form-data`                                                           |
| `kreditorname`   | Nein    | Lieferantenname; überschreibt den von der KI extrahierten Lieferantennamen                                                 |
| `archivdocument` | Nein    | Externe Dokument-ID für Archivierungszwecke; wird als `external_id` der Rechnung gespeichert                               |
| `projekt`        | Nein    | Projektnummer; überschreibt die von der KI extrahierte Projektzuordnung                                                    |
| `buchungskreis`  | Nein    | Buchungskreis (juristische Einheit); Fallback für die Projektnummer, wenn `projekt` leer ist — Format `HQ-{buchungskreis}` |

## Verhalten der Preset-Header

* `kreditorname` setzt `supplier_name` in der Rechnungsverarbeitung.
* `projekt` setzt `project_number`. Wenn `projekt` fehlt oder leer ist, wird stattdessen `HQ-{buchungskreis}` verwendet (sofern `buchungskreis` gesetzt ist).
* `archivdocument` wird als externe Rechnungs-ID (`external_id`) gespeichert.

## Beispiel (Legacy PDF-Body)

```bash theme={null}
curl -X POST "https://api.comstruct.com/v1/invoices/custom" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/pdf" \
  -H "kreditorname: Beispiel Lieferant GmbH" \
  -H "archivdocument: ARCH-2024-001" \
  -H "projekt: PRJ-001" \
  --data-binary @rechnung.pdf
```

## Beispiel (multipart mit XML + PDF)

```bash theme={null}
curl -X POST "https://api.comstruct.com/v1/invoices/custom" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "kreditorname: Beispiel Lieferant GmbH" \
  -H "archivdocument: ARCH-2024-001" \
  -H "projekt: PRJ-001" \
  -F "xml=@rechnung.xml" \
  -F "pdf=@visualisierung.pdf"
```


## OpenAPI

````yaml POST /invoices/custom
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` und IDS-Endpunkte unter `/ids` liegen
    **ohne** `/v1`-Präfix (Basis-URL `https://api.comstruct.com`). Kalender
    verwenden Token-basierte Authentifizierung; IDS ist ein öffentlicher
    Callback ohne API-Schlüssel.


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

    - Asynchroner Lieferschein-PDF-Upload (`POST /deliveries/pdf`): 16MiB

    - 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.10
  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/custom:
    post:
      tags:
        - Invoices (Supplier)
        - Invoices
      summary: Rechnung im benutzerdefinierten Format verarbeiten
      description: >
        **Erforderliche Berechtigungen:** `invoices:write`


        Verarbeitet ein benutzerdefiniertes Rechnungsformat mittels
        GPT/KI-Parsing.

        Akzeptiert PDF- oder TIFF-Dateien bis zu 32MiB und verarbeitet sie
        mittels generativer KI zur Rechnungsdatenextraktion.


        Optionale Request-Header können vordefinierte Werte für Lieferant,
        Projekt und externe Dokument-ID

        übergeben und damit die von der KI extrahierten Felder überschreiben.


        Der API-Schlüssel muss mit einem Lieferanten verknüpft sein.


        Akzeptiert entweder einen einzelnen rohen PDF-/TIFF-Body (Legacy) oder
        `multipart/form-data`

        mit optionalem `xml`-Teil und einem oder mehreren `pdf`-Teilen. Bei XML
        laufen die

        automatisierten Prüfungen auf dem XML; die PDF(s) dienen der
        Visualisierung (mehrere PDFs werden gemerged).
      operationId: createInvoiceFromCustom
      parameters:
        - name: kreditorname
          in: header
          required: false
          schema:
            type: string
          description: >-
            Lieferantenname; überschreibt den von der KI extrahierten
            Lieferantennamen
          example: Beispiel Lieferant GmbH
        - name: archivdocument
          in: header
          required: false
          schema:
            type: string
          description: >-
            Externe Dokument-ID für Archivierungszwecke; wird als `external_id`
            der Rechnung gespeichert
          example: ARCH-2024-001
        - name: projekt
          in: header
          required: false
          schema:
            type: string
          description: >-
            Projektnummer; überschreibt die von der KI extrahierte
            Projektzuordnung
          example: PRJ-001
        - name: buchungskreis
          in: header
          required: false
          schema:
            type: string
          description: >-
            Buchungskreis (juristische Einheit); Fallback für die Projektnummer,
            wenn `projekt` leer ist (`HQ-{buchungskreis}`)
          example: '1000'
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - NEW
              - PROCESSING
              - FACTUAL_CHECKING
              - PRICE_CHECKING
              - POSITIONS_CHECK
              - CHECKED
              - CANCELLED
              - ERROR
              - OPEN
          description: >
            Initialer Rechnungsstatus. Wird nur für Mandanten ohne
            Invoice-Workflows-Feature ausgewertet; sonst ignoriert.
      requestBody:
        required: true
        content:
          application/pdf:
            schema:
              type: string
              format: binary
              description: Rohe PDF-Rechnungsdaten (Legacy, bis zu 32MiB)
          application/tiff:
            schema:
              type: string
              format: binary
              description: Rohe TIFF-Rechnungsdaten (Legacy, bis zu 32MiB)
          multipart/form-data:
            schema:
              type: object
              properties:
                xml:
                  type: string
                  format: binary
                  description: Rechtsverbindliches eInvoice-XML (XRechnung)
                pdf:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: >-
                    Visualisierungs-PDF(s); ZUGFeRD-PDFs werden über
                    eingebettetes XML erkannt
      responses:
        '201':
          description: >-
            Rechnung erfolgreich verarbeitet und zur Hintergrundverarbeitung
            eingereiht
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoiceId:
                    type: string
                    description: Eindeutige ID der erstellten Rechnung
                    example: invoice-abc123def456
                  jobId:
                    type: string
                    description: Job-ID zur Nachverfolgung der Hintergrundverarbeitung
                    example: job-789xyz012
                  success:
                    type: boolean
                    example: true
                required:
                  - invoiceId
                  - success
        '400':
          description: Ungültige PDF-/TIFF-Datei oder fehlgeschlagene Header-Validierung
        '401':
          description: >-
            Nicht autorisiert - Fehlende Berechtigung oder Schlüssel nicht mit
            Lieferant verknüpft
        '500':
          description: Rechnung konnte nicht verarbeitet werden
      security:
        - ApiKey:
            - invoices:write
components:
  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.

````