Zum Hauptinhalt springen

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.

​
Übersicht

comstruct kann E-Mails mit Rechnungen empfangen und deren Anhänge automatisch extrahieren, klassifizieren und verarbeiten. Dies ermöglicht einen vollständig automatisierten Workflow: Leiten Sie Lieferantenrechnungen an eine dedizierte Adresse weiter und comstruct erledigt den Rest. Der E-Mail-Verarbeitungsendpunkt unterstützt zwei Hauptszenarien:

Standard-E-Mail-Weiterleitung

Leiten Sie Rechnungen an comstruct weiter. Anhänge werden extrahiert, per KI klassifiziert und als Rechnungen angelegt.

Stapelscan-Verarbeitung

Senden Sie gescannte Mehrfach-Rechnungs-PDFs. comstruct segmentiert diese mithilfe KI-basierter Seitenerkennung in einzelne Rechnungen.

​
Funktionsweise

Wenn eine E-Mail am Verarbeitungsendpunkt eingeht, durchläuft comstruct folgende Pipeline:

​
Schritt für Schritt

  1. E-Mail-Parsing — Die Roh-E-Mail (MIME/RFC 822) wird geparst. Inline-Bilder (Signaturen, Logos) werden herausgefiltert. Anhänge werden in unterstützte und nicht unterstützte Kategorien aufgeteilt.
  2. Formatkonvertierung — TIFF-Anhänge werden automatisch in PDF konvertiert. Fehlgeschlagene Konvertierungen werden als zusätzliche Dokumente beibehalten.
  3. Routing — Basierend auf Anzahl und Typ der unterstützten Anhänge wählt comstruct den effizientesten Verarbeitungspfad (siehe Verarbeitungsmodi).
  4. Rechnungserstellung — Jede identifizierte Rechnung durchläuft die Standard-comstruct-Pipeline: KI-gestützte Datenextraktion, Lieferantenzuordnung und Freigabe-Workflows.

​
Unterstützte Dokumentformate

​
Rechnungsdokumente (werden als Rechnungen verarbeitet)

FormatMIME-TypenHinweise
PDFapplication/pdfPrimärformat; beste KI-Extraktionsergebnisse
XMLapplication/xml, text/xmlWird als XRechnung verarbeitet, wenn gültiges elektronisches Rechnungs-XML erkannt wird
TIFFimage/tiff, image/tifWird vor der Verarbeitung automatisch in PDF konvertiert
PDFs werden auch durch Inhaltsprüfung erkannt — eine Datei mit falschem MIME-Typ aber gültigem PDF-Inhalt wird trotzdem korrekt verarbeitet.

​
Zusätzliche Dokumente (werden der Rechnung beigelegt)

Nicht-Rechnungsanhänge werden hochgeladen und als Referenzdokumente mit der resultierenden Rechnung verknüpft:
FormatBeispiele
Office-Dokumente.doc, .docx, .xls, .xlsx
Bilder.jpg, .png, .bmp, .webp, .gif
Archive.zip
Weitergeleitete E-Mails.eml, message/rfc822
Anhänge, die weder Rechnungsdokumente noch hochladbare Referenzdokumente sind, werden protokolliert und übersprungen.

​
Verarbeitungsmodi

​
Standard-E-Mail-Verarbeitung

Die Standardverarbeitung bestimmt den besten Pfad anhand der Anzahl und des Typs der unterstützten Anhänge:
Der häufigste Fall. Das PDF wird direkt an die Rechnungsverarbeitungs-Pipeline gesendet — keine Klassifizierung erforderlich.Ergebnis: Eine Rechnung wird sofort erstellt.
Wenn eine E-Mail mehr als ein unterstütztes Dokument enthält oder eine Mischung aus PDFs und anderen Typen, werden alle Anhänge an die KI-Klassifizierungswarteschlange gesendet.Der Klassifizierer gruppiert Dokumente in:
  • Rechnungsdokumente — jede Gruppe wird zu einer separaten Rechnung
  • Begleitdokumente — werden den relevanten Rechnungen zugeordnet
XML-Anhänge werden durch Vergleich normalisierter Rechnungsnummern mit PDF-Rechnungen abgeglichen.
Wenn die E-Mail ausschließlich XML-Anhänge mit gültigem elektronischen Rechnungsinhalt (XRechnung / EN 16931) enthält, führt comstruct folgende Schritte aus:
  1. Validierung der XML als anerkanntes elektronisches Rechnungsformat
  2. Generierung eines lesbaren PDFs aus den strukturierten Daten
  3. Erstellung einer Rechnung mit sowohl dem PDF als auch dem Original-XML als Anhang
Wenn die XML keine gültige elektronische Rechnung ist, wird eine Platzhalter-Rechnung erstellt und die XML als zusätzliches Dokument beibehalten.
Wenn eine E-Mail keine verarbeitbaren Anhänge enthält (z. B. nur Bilder oder Office-Dateien), erstellt comstruct dennoch eine Platzhalter-Rechnung, damit die E-Mail nicht verloren geht:
  • Ein Platzhalter-PDF wird generiert
  • Alle hochladbaren Anhänge werden als zusätzliche Dokumente verknüpft
  • Der E-Mail-Inhalt (Absender, Betreff, Datum, Text) wird als separates PDF gerendert und angehängt
So wird sichergestellt, dass jede weitergeleitete E-Mail erfasst wird und manuell überprüft werden kann.

​
Stapelscan-Verarbeitung

Der Stapelscan-Modus ist für Scan-Workflows konzipiert, bei denen mehrere Papierrechnungen in einem Durchgang gescannt werden und ein einzelnes mehrseitiges PDF erzeugen. Wenn der Stapelscan-Modus aktiv ist:
  1. Nur PDF-Anhänge werden verarbeitet (andere unterstützte Dokumenttypen werden ignoriert)
  2. Jedes PDF wird per KI analysiert, um Seitengrenzen zwischen einzelnen Rechnungen zu erkennen
  3. Das PDF wird in Segmente aufgeteilt — eines pro erkannter Rechnung
  4. Jedes Segment wird direkt an die Rechnungsverarbeitung gesendet (Klassifizierung wird übersprungen, da alle Seiten als Rechnungen bekannt sind)
Stapelscan-Modus aktivieren: Setzen Sie den Header x-staple-scan: true in der Anfrage. Fallback: Wenn die Segmentierung fehlschlägt oder das PDF nur eine Seite hat, wird das gesamte PDF als einzelne Rechnung behandelt.

​
Erhaltung von E-Mail-Metadaten

comstruct extrahiert Metadaten aus der Original-E-Mail und nutzt diese während der gesamten Verarbeitung:
MetadatenfeldVerwendung
Absender (From)Absenderidentifikation; unterstützt die Lieferantenzuordnung
Betreff (Subject)Wird zur Referenz und Durchsuchbarkeit gespeichert
Datum (Date)Originaler E-Mail-Zeitstempel
E-Mail-Text (Body)Wenn keine Rechnungsanhänge gefunden werden, wird der E-Mail-Text als PDF gerendert und der Platzhalter-Rechnung angehängt

​
KI-gestützte Klassifizierung

Wenn eine E-Mail mehrere Anhänge enthält, nutzt comstruct KI (Gemini), um diese intelligent zu gruppieren und zu klassifizieren:
  • Rechnung vs. Begleitdokument — Der Klassifizierer bestimmt, welche Dokumente tatsächliche Rechnungen sind und welche ergänzend sind (z. B. Lieferscheine, Anschreiben, Spezifikationen)
  • Gruppierung — Mehrere Seiten oder Dateien, die zur selben Rechnung gehören, werden zusammengefasst
  • XML–PDF-Zuordnung — Wenn sowohl XML- (XRechnung) als auch PDF-Versionen einer Rechnung vorliegen, werden sie anhand normalisierter Rechnungsnummern abgeglichen und als einzelne Rechnung verknüpft
  • Duplikaterkennung — Wenn ein Dokument bereits verarbeitet wurde (anhand der Dokument-ID erkannt), wird es übersprungen, um doppelte Rechnungen zu vermeiden

​
Fallback-Verhalten

Falls die KI-Klassifizierung aus irgendeinem Grund fehlschlägt, greift comstruct auf eine sichere Standardverarbeitung zurück: Jeder PDF-Anhang wird als separate Rechnung verarbeitet, wobei XML- und nicht unterstützte Dokumente an alle resultierenden Rechnungen angehängt werden. So geht keine Rechnung verloren.

​
Warteschlange und Wiederholungsverhalten

Die E-Mail-Verarbeitung nutzt eine Job-Warteschlange, um die Klassifizierung bei Bedarf asynchron zu verarbeiten:
EinstellungWert
Max. Versuche5
Backoff-StrategieExponentiell, beginnend bei 10 Sekunden
ParallelitätKonfigurierbar (Standard: 1 Worker)
Die nachgelagerte Rechnungsverarbeitungs-Pipeline (Datenextraktion, OCR, Zuordnung) läuft auf einer separaten Warteschlange mit eigener Wiederholungslogik (10 Versuche, 15 Sekunden initialer Backoff).

​
Integration mit SendGrid

Der E-Mail-Verarbeitungsendpunkt ist für den Empfang von SendGrid Inbound Parse-Webhook-Payloads konzipiert. SendGrid leitet eingehende E-Mails als Multipart-Formulardaten weiter, und comstruct extrahiert den rohen E-Mail-Inhalt aus dem email-Feld.

​
Einrichtung

  1. Konfigurieren Sie einen SendGrid Inbound Parse Webhook, der auf Ihre comstruct-Instanz zeigt
  2. Setzen Sie die MX-Einträge Ihrer Weiterleitungsdomain auf SendGrid
  3. Fügen Sie Authentifizierungs-Header (x-api-key) in der Webhook-Konfiguration hinzu
  4. Setzen Sie optional x-staple-scan: true für scan-dedizierte Adressen

​
Anfrageformat

Der Endpunkt akzeptiert einen rohen Body (bis zu 32 MB) mit Multipart-Formulardaten. Das email-Feld muss die vollständige Roh-E-Mail im RFC-822-/MIME-Format enthalten.

​
Best Practices

  • Verwenden Sie eine dedizierte E-Mail-Adresse pro Weiterleitungszweck (z. B. eine für reguläre Rechnungen, eine für Stapelscans)
  • Konfigurieren Sie E-Mail-Regeln zur automatischen Weiterleitung — vermeiden Sie manuelle Weiterleitung, wo möglich
  • Stellen Sie sicher, dass die Weiterleitung originale Anhänge beibehält (vermeiden Sie Inline-Weiterleitung)
  • PDF liefert die besten KI-Extraktionsergebnisse — bevorzugen Sie es gegenüber gescannten Bildern
  • Verwenden Sie mindestens 300 DPI für gescannte Dokumente
  • Stellen Sie sicher, dass Dokumente nicht passwortgeschützt sind
  • Vermeiden Sie extrem große Anhänge — der Endpunkt akzeptiert bis zu 32 MB insgesamt
  • Führen Sie Rechnungen in der richtigen Reihenfolge ein — comstruct erkennt Grenzen, behält aber die Seitenreihenfolge bei
  • Verwenden Sie klare Seitentrennungen zwischen Rechnungen
  • Einseitige Rechnungen funktionieren am besten; mehrseitige Rechnungen innerhalb eines Stapelscans werden ebenfalls unterstützt
  • Senden Sie XML-Dateien als Standard-Anhänge (nicht inline)
  • Wenn Sie sowohl PDF- als auch XML-Versionen senden, verwenden Sie übereinstimmende Rechnungsnummern, damit comstruct sie automatisch verknüpfen kann
  • Unterstützte Formate: XRechnung (EN 16931-konform)

​
Verwandte Endpunkte

Einzelrechnung hochladen

Ein einzelnes Rechnungs-PDF direkt per API hochladen.

E-Mail-Rechnung

Ein einzelnes PDF mit E-Mail-artigen Headern (Projekt, Mandant) hochladen.

Rechnungsliste

Verarbeitete Rechnungen abfragen und filtern.

Rechnungs-Callback

Status-Aktualisierungen von ERP-Systemen empfangen.