Rechnungs-Integrationsmuster - comstruct API Dokumentation

Übersicht

comstruct bietet flexible Rechnungsverarbeitungsfunktionen, die verschiedene Integrationsmuster unterstützen. Dieser Leitfaden behandelt die häufigsten Integrationsszenarien und Best Practices für deren Implementierung.

Integrationsmuster

Direkter Upload

Lieferanten laden Rechnungen direkt zur KI-gestützten Verarbeitung in comstruct hoch.

E-Mail-Weiterleitung

Per E-Mail empfangene Rechnungen werden automatisch an comstruct weitergeleitet.

ERP-Export

Verarbeitete Rechnungen werden zur Buchung an ERP-Systeme exportiert.

SAP-Rückmeldung

Bidirektionale Synchronisation mit SAP für Rechnungsstatus-Aktualisierungen.

Muster 1: Direkter Lieferanten-Upload

Das häufigste Muster, bei dem Lieferanten Rechnungen direkt über die API hochladen.

Funktionsweise

Implementierung

curl -X POST "https://api.comstruct.com/v1/invoices/custom" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/pdf" \
  --data-binary @rechnung.pdf

Antwort

{
  "success": true,
  "data": {
    "id": "123",
    "external_id": "RE-2024-001",
    "invoice_number": "RE-2024-1234",
    "supplier_name": "Beispiel GmbH",
    "gross_amount": 1190.00,
    "net_amount": 1000.00,
    "tax_amount": 190.00,
    "status": "OPEN"
  }
}

Best Practices

Verwenden Sie PDF-Format für beste KI-Parsing-Ergebnisse
Verwenden Sie klare, lesbare Rechnungslayouts
Stellen Sie sicher, dass PDFs nicht passwortgeschützt sind
Maximale Dateigröße: 32MiB

Muster 2: E-Mail-basierte Verarbeitung

Per E-Mail empfangene Rechnungen können zur Verarbeitung an comstruct weitergeleitet werden.

Funktionsweise

Implementierung

curl -X POST "https://api.comstruct.com/v1/invoices/email" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @email_inhalt

E-Mail-Verarbeitungsfunktionen

Automatische Anhang-Extraktion
Unterstützung für mehrere Rechnungen pro E-Mail
Metadaten-Extraktion aus E-Mail-Headern
Absenderidentifikation für Lieferantenzuordnung

Muster 3: SAP-Integration

Vollständige bidirektionale Integration mit SAP für Rechnungsverarbeitung und Status-Synchronisation.

Rechnungsexport nach SAP

Nachdem Rechnungen in comstruct verarbeitet und freigegeben wurden, können sie nach SAP exportiert werden.

SAP-Rückmeldungs-Integration

SAP kann Status-Aktualisierungen an comstruct zurücksenden:

curl -X POST "https://api.comstruct.com/v1/invoices/callback" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "RE-2024-001",
    "success": true,
    "sap_document_number": "5100000123"
  }'

Rückmeldungs-Anfrageschema

Feld	Typ	Erforderlich	Beschreibung
`external_id`	string	Ja	Externe ID der Rechnung
`success`	boolean	Ja	Ob SAP-Verarbeitung erfolgreich war
`sap_document_number`	string	Nein	SAP-Belegnummer (bei Erfolg)
`error_message`	string	Nein	Fehlerdetails (bei Misserfolg)

Muster 4: Workflow-Integration (JobRouter)

Für Kunden, die Workflow-Systeme wie JobRouter für Rechnungsfreigabe verwenden.

Workflow-Verarbeitung

curl -X POST "https://api.comstruct.com/v1/workflows/trigger" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "RE-2024-001",
    "base64document": "JVBERi0xLjQK...",
    "project_number": "PRJ-001",
    "creditor_name": "Beispiel GmbH",
    "invoice_number": "RE-2024-1234",
    "invoice_date": "2024-01-15",
    "due_date": "2024-02-15",
    "receipt_date": "2024-01-16",
    "net_amount": 1000.00,
    "total_amount": 1190.00,
    "tenant": "tenant-123",
    "dimensions": [
      { "dimension_label": "Kostenstelle", "option_title": "Verwaltung" },
      { "dimension_label": "Abteilung", "option_title": "Einkauf" }
    ]
  }'

Das optionale receipt_date-Feld (Buchungsdatum) akzeptiert ein Datum im Format YYYY-MM-DD. Wird es nicht angegeben, verwendet comstruct das aktuelle Datum als Buchungsdatum. Das dimensions-Feld ist optional. Es akzeptiert ein Array von { dimension_label, option_title }-Paaren, die gegen die im Mandanten konfigurierten Rechnungsdimensionen und deren Optionen aufgelöst werden. Übergebene Dimensionswerte haben Vorrang vor KI-extrahierten Werten — analog zum bestehenden Verhalten bei vordefinierten Kontierungen (accounts).

Workflow-Status prüfen

curl -X GET "https://api.comstruct.com/v1/workflows/status/RE-2024-001" \
  -H "x-api-key: IHR_API_SCHLUESSEL"

Status-Antwort

{
  "success": true,
  "status": "PROCESSING",
  "url": "https://app.comstruct.com/invoices/123",
  "history": [
    {
      "created_at": "2024-01-15T10:30:00Z",
      "newStatus": "PROCESSING",
      "previousStatus": "NEW",
      "message": "Verarbeitung gestartet"
    }
  ]
}

Rechnungsstatus-Ablauf

Das Verständnis des Rechnungslebenszyklus hilft bei der Gestaltung von Integrationen:

Status-Definitionen

Status	Beschreibung
`OPEN`	Rechnung erstellt, wartet auf Verarbeitung
`PROCESSING`	Rechnung wird geprüft
`APPROVED`	Zur Zahlung freigegeben
`REJECTED`	Rechnung abgelehnt
`EXPORTED`	Zur Buchung an ERP gesendet
`BOOKED`	Erfolgreich im ERP gebucht

Rechnungen auflisten und filtern

Alle Rechnungen auflisten

curl -X GET "https://api.comstruct.com/v1/invoices?limit=25&offset=0" \
  -H "x-api-key: IHR_API_SCHLUESSEL"

Nach Status filtern

curl -X GET "https://api.comstruct.com/v1/invoices?status=OPEN" \
  -H "x-api-key: IHR_API_SCHLUESSEL"

Einzelne Rechnung abrufen

curl -X GET "https://api.comstruct.com/v1/invoices/123" \
  -H "x-api-key: IHR_API_SCHLUESSEL"

Die Antwort entspricht einem Listeneintrag (u. a. invoice_accounts, created_at, updated_at), ohne Verlauf und ohne Positionen.

Rechnungspositionen abrufen

curl -X GET "https://api.comstruct.com/v1/invoices/123/items" \
  -H "x-api-key: IHR_API_SCHLUESSEL"

Antwort: { "items": [ ... ] } (nach index sortiert).

Antwortformat

{
  "data": [
    {
      "id": "123",
      "external_id": "RE-2024-001",
      "invoice_number": "RE-2024-1234",
      "status": "OPEN",
      "gross_amount": 1190.00,
      "supplier_name": "Beispiel GmbH",
      "project_number": "PRJ-001",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-16T09:00:00Z"
    }
  ],
  "total": 150,
  "limit": 25,
  "offset": 0,
  "hasNext": true,
  "hasPrevious": false,
  "totalPages": 6,
  "currentPage": 0
}

Rechnungs-PDFs herunterladen

Originale PDF für eine Rechnung abrufen:

curl -X GET "https://api.comstruct.com/v1/invoices/123/pdf" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -o rechnung_123.pdf

Fehlerbehandlung

Häufige Fehler

Fehlercode	Beschreibung	Lösung
400	Ungültiges Rechnungsformat	PDF-Gültigkeit prüfen
401	Fehlende Berechtigung	`invoices:write` Berechtigung anfordern
404	Rechnung nicht gefunden	Rechnungs-ID überprüfen
500	Parsing fehlgeschlagen	Support mit Rechnung kontaktieren

Fehlerantwort

{
  "success": false,
  "error": "Failed to parse invoice: Invalid data format"
}

Wiederholungsstrategie

Für vorübergehende Fehler (5xx) implementieren Sie exponentielles Backoff:

import time
import requests

def rechnung_hochladen_mit_wiederholung(pdf_pfad, max_versuche=3):
    for versuch in range(max_versuche):
        try:
            with open(pdf_pfad, 'rb') as f:
                response = requests.post(
                    'https://api.comstruct.com/v1/invoices/custom',
                    headers={
                        'x-api-key': 'IHR_API_SCHLUESSEL',
                        'Content-Type': 'application/pdf'
                    },
                    data=f.read()
                )
            
            if response.status_code < 500:
                return response.json()
                
        except requests.exceptions.RequestException:
            pass
        
        time.sleep(2 ** versuch)  # Exponentielles Backoff
    
    raise Exception("Maximale Versuche überschritten")

Best Practices Zusammenfassung

Datenqualität

Verwenden Sie hochauflösende PDF-Scans (mindestens 300 DPI)
Stellen Sie sicher, dass Rechnungen nicht schief oder gedreht sind
Vermeiden Sie passwortgeschützte PDFs
Verwenden Sie nach Möglichkeit standardisierte Rechnungslayouts

Integrationsdesign

Implementieren Sie idempotente Uploads mit externen IDs
Speichern Sie API-Antworten für Debugging
Verwenden Sie Webhooks oder Polling für Status-Aktualisierungen
Implementieren Sie ordnungsgemäße Fehlerbehandlung und Wiederholungslogik

Performance

Bündeln Sie Uploads außerhalb der Spitzenzeiten
Komprimieren Sie PDFs, um die Upload-Zeit zu reduzieren
Verwenden Sie Connection-Pooling für mehrere Anfragen
Überwachen Sie API-Antwortzeiten

Sicherheit

Speichern Sie API-Schlüssel sicher
Verwenden Sie HTTPS für alle Anfragen
Validieren Sie Antworten vor der Verarbeitung
Implementieren Sie Audit-Logging

Support

Für Integrationsunterstützung:

Kontaktieren Sie Ihren Customer Success Manager
E-Mail: support@comstruct.com
API-Referenz für Endpunkt-Details

Einführung

Integrationsleitfäden

Documentation Index

​Übersicht

​Integrationsmuster

Direkter Upload

E-Mail-Weiterleitung

ERP-Export

SAP-Rückmeldung

​Muster 1: Direkter Lieferanten-Upload

​Funktionsweise

​Implementierung

​Antwort

​Best Practices

​Muster 2: E-Mail-basierte Verarbeitung

​Funktionsweise

​Implementierung

​E-Mail-Verarbeitungsfunktionen

​Muster 3: SAP-Integration

​Rechnungsexport nach SAP

​SAP-Rückmeldungs-Integration

​Rückmeldungs-Anfrageschema

​Muster 4: Workflow-Integration (JobRouter)

​Workflow-Verarbeitung

​Workflow-Status prüfen

​Status-Antwort

​Rechnungsstatus-Ablauf

​Status-Definitionen

​Rechnungen auflisten und filtern

​Alle Rechnungen auflisten

​Nach Status filtern

​Einzelne Rechnung abrufen

​Rechnungspositionen abrufen

​Antwortformat

​Rechnungs-PDFs herunterladen

​Fehlerbehandlung

​Häufige Fehler

​Fehlerantwort

​Wiederholungsstrategie

​Best Practices Zusammenfassung

​Support

Übersicht

Integrationsmuster

Muster 1: Direkter Lieferanten-Upload

Funktionsweise

Implementierung

Antwort

Best Practices

Muster 2: E-Mail-basierte Verarbeitung

Funktionsweise

Implementierung

E-Mail-Verarbeitungsfunktionen

Muster 3: SAP-Integration

Rechnungsexport nach SAP

SAP-Rückmeldungs-Integration

Rückmeldungs-Anfrageschema

Muster 4: Workflow-Integration (JobRouter)

Workflow-Verarbeitung

Workflow-Status prüfen

Status-Antwort

Rechnungsstatus-Ablauf

Status-Definitionen

Rechnungen auflisten und filtern

Alle Rechnungen auflisten

Nach Status filtern

Einzelne Rechnung abrufen

Rechnungspositionen abrufen

Antwortformat

Rechnungs-PDFs herunterladen

Fehlerbehandlung

Häufige Fehler

Fehlerantwort

Wiederholungsstrategie

Best Practices Zusammenfassung

Support