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

# Trigger workflow

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

Löst den Rechnungsverarbeitungs-Workflow für die JobRouter-Integration aus.

Dieser Endpunkt ermöglicht es, eine Rechnung mit umfassenden Daten (Lieferant, Beträge, Daten und Metadaten) zur Verarbeitung einzureichen.
Die Rechnung wird asynchron im Hintergrund verarbeitet.
API-Schlüssel muss mit einem Kunden verknüpft sein.


Submit invoices from external systems (e.g. JobRouter) for asynchronous processing in comstruct.

Use the `external_id` later with the [Workflow status endpoint](/en/api-reference/workflows-status) to check processing status.

### Dimension assignments

The optional `dimensions` field lets external systems pass dimension values as `{ dimension_label, option_title }` pairs. These are resolved against the tenant's configured invoice dimensions and assigned to the created invoice. Workflow-provided dimension values take priority over AI-extracted values.


## OpenAPI

````yaml POST /workflows/trigger
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:
  /workflows/trigger:
    post:
      tags:
        - Workflows
      summary: Workflow-Verarbeitung auslösen
      description: >
        **Erforderliche Berechtigungen:** `invoices:write`


        Löst den Rechnungsverarbeitungs-Workflow für die JobRouter-Integration
        aus.


        Dieser Endpunkt ermöglicht es, eine Rechnung mit umfassenden Daten
        (Lieferant, Beträge, Daten und Metadaten) zur Verarbeitung einzureichen.

        Die Rechnung wird asynchron im Hintergrund verarbeitet.

        API-Schlüssel muss mit einem Kunden verknüpft sein.
      operationId: triggerWorkflow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobRouterInvoiceRequest'
            example:
              external_id: INV-2024-001
              base64document: JVBERi0xLjQKJcOkw7zDtsO...
              project_number: PRJ-2024-001
              creditor_number: CR-001
              creditor_name: ABC Supplies Ltd.
              invoice_number: INV-2024-001
              invoice_date: '2024-01-15'
              due_date: '2024-02-15'
              currency: EUR
              net_amount: 1000
              total_amount: 1190
              total_tax_amount: 190
              tenant: tenant-123
              comment: Spezielle Handhabung erforderlich
              document_type: INVOICE
              assignee: john.doe@example.com
              accounts:
                - account_number: '1000'
                  project_number: PRJ-2024-001
                  quantity: 10
                  net_amount: 1000
                  gross_amount: 1190
                  tax_amount: 190
              dimensions:
                - dimension_label: Kostenstelle
                  option_title: Verwaltung
      responses:
        '201':
          description: Workflow erfolgreich ausgelöst
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobRouterInvoiceResponse'
              example:
                success: true
                external_id: INV-2024-001
                invoiceId: '123'
                jobId: job-789xyz012
        '400':
          description: Ungültige Anfrage - Fehlende Pflichtfelder oder ungültiges Format
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                example:
                  success: false
                  error: 'Validierungsfehler: external_id ist erforderlich'
        '401':
          description: Nicht autorisiert - Ungültiger API-Schlüssel
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          description: Interner Serverfehler bei der Verarbeitung
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                  logPath:
                    type: string
                example:
                  success: false
                  error: Failed to process invoice
                  logPath: >-
                    customer-id-error-invoice-2024-01-01-12:00:00.000Z-abc123.json
      security:
        - ApiKey:
            - invoices:write
components:
  schemas:
    JobRouterInvoiceRequest:
      type: object
      required:
        - external_id
        - base64document
        - project_number
        - creditor_name
        - invoice_number
        - invoice_date
        - net_amount
        - total_amount
        - tenant
      properties:
        external_id:
          type: string
          description: Externe Kennung für die Rechnung (zur späteren Statusabfrage)
          example: INV-2024-001
        base64document:
          type: string
          format: byte
          description: Base64-kodiertes PDF-Dokument
          example: JVBERi0xLjQKJcOkw7zDtsO...
        project_number:
          type: string
          description: Projektnummer
          example: PRJ-2024-001
        creditor_number:
          type: string
          description: Kreditorennummer (optional)
          example: CR-001
        creditor_name:
          type: string
          description: Name des Kreditors/Lieferanten
          example: ABC Supplies Ltd.
        invoice_number:
          type: string
          description: Rechnungsnummer
          example: INV-2024-001
        invoice_date:
          type: string
          format: date
          description: Rechnungsdatum im Format YYYY-MM-DD
          example: '2024-01-15'
        due_date:
          type: string
          format: date
          description: Fälligkeitsdatum im Format YYYY-MM-DD (optional)
          example: '2024-02-15'
        receipt_date:
          type: string
          format: date
          description: >-
            Buchungsdatum im Format YYYY-MM-DD (optional). Wenn nicht angegeben,
            wird das aktuelle Datum verwendet.
          example: '2024-01-16'
        currency:
          type: string
          description: Währungscode (ISO-4217)
          example: EUR
          default: EUR
        net_amount:
          type: number
          format: double
          description: Nettobetrag
          example: 1000
        total_amount:
          type: number
          format: double
          description: Gesamtbetrag (brutto)
          example: 1190
        tenant:
          type: string
          description: Mandanten-Kennung
          example: tenant-123
        comment:
          type: string
          description: Kommentar (optional)
          example: Spezielle Handhabung erforderlich
        document_type:
          type: string
          enum:
            - INVOICE
            - CREDIT_NOTE
          description: Dokumenttyp
          example: INVOICE
          default: INVOICE
        total_tax_amount:
          type: number
          format: double
          description: Gesamter Steuerbetrag (optional)
          example: 190
        assignee:
          type: string
          format: email
          description: >-
            E-Mail-Adresse des Benutzers, dem die Rechnung zugewiesen werden
            soll (optional)
          example: john.doe@example.com
        accounts:
          type: array
          description: >-
            Vordefinierte Rechnungskontierungen mit Kontonummern, Mengen und
            Projektnummern (optional). Hat Vorrang vor der Comstruct-Kontierung.
          items:
            type: object
            required:
              - account_number
              - net_amount
              - gross_amount
              - tax_amount
            properties:
              account_number:
                type: string
                description: Kontonummer zur Zuordnung
                example: '1000'
              project_number:
                type: string
                description: >-
                  Projektnummer zur Zuordnung (optional, verwendet die
                  Rechnungs-Projektnummer wenn nicht angegeben)
                example: PRJ-001
              quantity:
                type: number
                description: Menge für diese Kontierung
                example: 10
              net_amount:
                type: number
                format: double
                description: Nettobetrag für diese Kontierung
                example: 1000
              gross_amount:
                type: number
                format: double
                description: Bruttobetrag für diese Kontierung
                example: 1190
              tax_amount:
                type: number
                format: double
                description: Steuerbetrag für diese Kontierung
                example: 190
          example:
            - account_number: '1000'
              project_number: PRJ-001
              quantity: 10
              net_amount: 1000
              gross_amount: 1190
              tax_amount: 190
        dimensions:
          type: array
          description: >
            Optionale Dimensionszuweisungen als Label/Titel-Paare (z.B.
            Kostenstelle, Abteilung).

            Werden anhand des Labels gegen die konfigurierten
            Rechnungsdimensionen und des Titels gegen die

            Dimensionsoptionen des Mandanten aufgelöst. Hat Vorrang vor
            KI-extrahierten Dimensionswerten.
          items:
            type: object
            required:
              - dimension_label
              - option_title
            properties:
              dimension_label:
                type: string
                description: >-
                  Label der Dimension (muss mit einer konfigurierten
                  Rechnungsdimension übereinstimmen)
                example: Kostenstelle
              option_title:
                type: string
                description: >-
                  Titel der Dimensionsoption (muss mit einer aktiven Option der
                  Dimension übereinstimmen)
                example: Verwaltung
          example:
            - dimension_label: Kostenstelle
              option_title: Verwaltung
            - dimension_label: Abteilung
              option_title: Einkauf
    JobRouterInvoiceResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Gibt an, ob der Workflow erfolgreich ausgelöst wurde
          example: true
        external_id:
          type: string
          description: Externe Kennung der verarbeiteten Rechnung
          example: INV-2024-001
        invoiceId:
          type: string
          description: Interne Rechnungs-ID
          example: '123'
        jobId:
          type: string
          description: Hintergrund-Job-ID zur Verfolgung des Verarbeitungsstatus
          example: job-789xyz012
    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:
    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.

````