> ## 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. # Custom invoice upload > **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. ## Overview Processes invoices as PDF or TIFF files with AI-assisted data extraction. Optional request headers can supply preset values for supplier, project, and external document ID, overriding fields extracted by the AI parser. ## Permissions | Scope | Tenant type | | ---------------- | -------------------------- | | `invoices:write` | Supplier (`SUPPLIER_ONLY`) | The API key must be linked to a supplier. ## Headers | Header | Required | Description | | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | `x-api-key` | Yes | API key with scope `invoices:write` | | `Content-Type` | Yes | `application/pdf` or `application/tiff` | | `kreditorname` | No | Supplier name; overrides the supplier name extracted by the AI parser | | `archivdocument` | No | External document ID for archival purposes; stored as the invoice `external_id` | | `projekt` | No | Project number; overrides the project assignment extracted by the AI parser | | `buchungskreis` | No | Company code (legal entity); fallback for the project number when `projekt` is empty — format `HQ-{buchungskreis}` | ## Preset header behavior * `kreditorname` sets `supplier_name` during invoice processing. * `projekt` sets `project_number`. If `projekt` is missing or empty, `HQ-{buchungskreis}` is used instead (when `buchungskreis` is set). * `archivdocument` is stored as the invoice external ID (`external_id`). ## Example ```bash theme={null} curl -X POST "https://api.comstruct.com/v1/invoices/custom" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/pdf" \ -H "kreditorname: Example Supplier GmbH" \ -H "archivdocument: ARCH-2024-001" \ -H "projekt: PRJ-001" \ --data-binary @invoice.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` 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/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. 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' requestBody: required: true content: '*/*': schema: type: string format: binary description: Rohe Rechnungsdaten (bis zu 32MiB) 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. ````