Workflow-Automatisierung mit der ZUGFeRD API: Scanner, OCR-Ordner und Pipelines

Warum Workflow-Automatisierung bei Rechnungen Sinn ergibt

In vielen Unternehmen durchlaufen Eingangsrechnungen eine Kette von Schritten: Eingang (E-Mail, Scanner, Portal) → Erfassung → Prüfung → Freigabe → Buchung → Archivierung. Jeder manuelle Schritt in dieser Kette ist eine potenzielle Fehlerquelle und ein Zeitfresser.

Die Vellonode API lässt sich an jeder Stelle in diese Kette einbauen — überall dort, wo ein PDF in strukturierte Daten oder ein validiertes E-Rechnungsformat überführt werden muss.

Typische Trigger: Woher kommen die PDFs?

1. Netzwerk-Scanner

Multifunktionsgeräte von Ricoh, Konica Minolta, Canon oder Kyocera können Scans direkt in einen Netzwerkordner legen. Von dort übernimmt ein Automatisierungs-Script.

2. Überwachter Eingangsordner

Mitarbeiter legen PDFs manuell in einen Ordner — oder ein anderes System (E-Mail-Client, Download-Script) legt sie dort ab.

3. Cloud-Speicher

Neue Dateien in Google Drive, Dropbox, OneDrive oder Nextcloud triggern einen Workflow.

4. Dokumenten-Pipeline

In größeren Setups durchlaufen Dokumente eine Pipeline: Klassifikation → Extraktion → Validierung → Routing. Die API übernimmt den Extraktions- und Validierungsschritt.

Variante 1: Shell-Script mit inotifywait (Linux)

Das einfachste Setup für einen überwachten Ordner unter Linux:

#!/bin/bash
WATCH_DIR="/srv/scanner/eingang"
OUTPUT_DIR="/srv/rechnungen/verarbeitet"
API_KEY="vk_live_IhrKeyHier"
# organizationId ist ein Pflichtparameter – abrufbar über GET /api/v1/organizations
API_URL="https://vellonode.de/api/v1/invoices/convert?organizationId=IHRE_ORG_ID"

mkdir -p "$OUTPUT_DIR"

echo "Überwache $WATCH_DIR..."

inotifywait -m -e close_write --format '%f' "$WATCH_DIR" | \
while read -r FILENAME; do
  # Nur PDFs verarbeiten
  if [[ ! "$FILENAME" =~ \.pdf$ ]]; then
    continue
  fi

  FILEPATH="$WATCH_DIR/$FILENAME"
  echo "Verarbeite: $FILENAME"

  # API aufrufen
  RESPONSE=$(curl -s -w "\n%{http_code}" \
    -X POST "$API_URL" \
    -H "Authorization: Bearer $API_KEY" \
    -F "file=@$FILEPATH" \
    -F "format=zugferd,json")

  HTTP_CODE=$(echo "$RESPONSE" | tail -1)
  BODY=$(echo "$RESPONSE" | sed '$d')

  if [ "$HTTP_CODE" = "200" ]; then
    # JSON speichern
    BASENAME="${FILENAME%.pdf}"
    echo "$BODY" | jq '.' > \
      "$OUTPUT_DIR/${BASENAME}.json"

    # ZUGFeRD-XML herunterladen
    XML_URL=$(echo "$BODY" | \
      jq -r '.files.zugferd.url // empty')
    if [ -n "$XML_URL" ]; then
      curl -s -o "$OUTPUT_DIR/${BASENAME}.xml" \
        "$XML_URL"
    fi

    # Original verschieben
    mv "$FILEPATH" "$OUTPUT_DIR/${FILENAME}"
    echo "  OK: $(echo "$BODY" | \
      jq -r '.data.invoiceNumber')"
  elif [ "$HTTP_CODE" = "429" ]; then
    RETRY=$(echo "$BODY" | \
      jq -r '.error.message' | grep -oP '\d+')
    echo "  Rate-Limit, warte ${RETRY}s..."
    sleep "$RETRY"
  else
    echo "  Fehler $HTTP_CODE: $(echo "$BODY" | \
      jq -r '.error.message')"
    mv "$FILEPATH" "$OUTPUT_DIR/fehler_${FILENAME}"
  fi
done

Variante 2: n8n-Workflow mit Ordner-Trigger

Für Teams, die lieber visuell arbeiten, bietet n8n einen dateibasierten Trigger:

1. Local File Trigger — überwacht einen Ordner auf neue PDF-Dateien

2. HTTP Request Node — sendet das PDF an die Vellonode API:

• Method: POST
• URL: https://vellonode.de/api/v1/invoices/convert?organizationId=IHRE_ORG_ID
• Authentication: Header Auth (Authorization: Bearer vk_live_...)
• Body: Form-Data mit dem Dateiinhalt als file und format=zugferd,json

3. Switch Node — Verzweigung nach Validierungsergebnis:

• result.validation.valid === true → automatisch weiterverarbeiten
• result.validation.valid === false → in Prüf-Queue legen

4. Aktion-Nodes:

• Gültige Rechnungen: Daten in Google Sheets/Datenbank schreiben, ZUGFeRD-XML in Archivordner legen, Slack-Benachrichtigung
• Ungültige Rechnungen: E-Mail an Buchhaltung mit den Validierungsfehlern

Besonderheit: Validierung als Qualitäts-Gate

Die API validiert jede Rechnung gegen EN16931. Das können Sie als automatisches Qualitäts-Gate nutzen:

Variante 3: Zapier-Integration

Zapier hat keinen nativen File-Watch-Trigger, funktioniert aber gut mit Cloud-Speichern:

Trigger: Neue Datei in Google Drive / Dropbox / OneDrive

Action 1: Webhooks by Zapier → Custom Request

• Method: POST
• URL: https://vellonode.de/api/v1/invoices/convert?organizationId=IHRE_ORG_ID
• Headers: Authorization: Bearer vk_live_...
• File: Dateiinhalt aus dem Trigger-Step

Action 2: Daten parsen und weiterleiten (Google Sheets, Slack, E-Mail, CRM)

Praxisbeispiel: Bauunternehmen mit Scanner-Workflow

Ein mittelständisches Bauunternehmen (80 Mitarbeiter, 5 Standorte) verarbeitet monatlich rund 400 Eingangsrechnungen. An jedem Standort steht ein Multifunktionsgerät, das Scans in einen zentralen Netzwerkordner legt.

Ausgangslage:

• Scans landen als PDF in \\server\scans\rechnungen\
• Ein Mitarbeiter öffnet jedes PDF, tippt Rechnungsdaten in Sage 50 ab
• Fehlerquote: 3–4% (besonders bei handschriftlichen Ergänzungen auf Rechnungen)
• Durchlaufzeit: 2–3 Tage vom Scan bis zur Buchung

Nach der Automatisierung:

• Das Shell-Script auf dem Linux-Server überwacht den Scan-Ordner per inotifywait
• Jedes PDF wird innerhalb von Sekunden an die API gesendet
• Die JSON-Response wird in eine PostgreSQL-Datenbank geschrieben
• Ein einfaches Web-Dashboard zeigt neue Rechnungen mit Ampel-Status (grün/gelb/rot)
• Nur gelbe und rote Rechnungen (ca. 15%) werden manuell geprüft
• Grüne Rechnungen werden direkt als DATEV-Export bereitgestellt

Ergebnis:

• Durchlaufzeit: von 2–3 Tagen auf unter 1 Stunde
• Manuelle Erfassung: von 30 auf 5 Stunden pro Monat
• Fehlerquote: unter 0,5% (nur noch bei Scans mit sehr schlechter Qualität)

Pipeline-Architektur für größere Setups

Für Unternehmen mit hohem Belegvolumen empfiehlt sich eine Message-Queue-basierte Architektur:

Scanner/E-Mail/Upload
        │
        ▼
   Message Queue (Redis/RabbitMQ)
        │
        ▼
   Worker-Pool (3-5 Worker)
   ├── PDF aus Queue nehmen
   ├── API aufrufen
   ├── Ergebnis in DB schreiben
   └── Dateien archivieren
        │
        ▼
   Dashboard / Notification

Vorteile:

• Puffer für Lastspitzen (z.B. Monatsanfang)
• Automatisches Retry bei Fehlern
• Skalierbar: mehr Worker = höherer Durchsatz
• Rate-Limit der API wird automatisch eingehalten (30 req/min)

Nächste Schritte

1. Konto erstellen unter vellonode.de/auth/register
2. API-Key generieren unter Einstellungen → API
3. Eingangskanal identifizieren — Scanner, Ordner oder Cloud-Speicher?
4. Script/Workflow aufsetzen — Shell, n8n oder Zapier als Startpunkt
5. Testen mit 10 echten Belegen, Ergebnisse im JSON prüfen

Die vollständige API-Spezifikation finden Sie unter /api/v1/openapi.