Dokumentenprüfung: API, Webhooks und ERP

Dokumentenprüfung sollte niemals als isoliertes Silo betrieben werden. Wenn ein Sachbearbeiter manuell Dateien in ein eigenständiges Tool hochlädt, Ergebnisse in ein CRM kopiert und dann ein ERP aktualisiert, führt jeder Schritt zu Verzögerung, Fehlerrisiko und unterbrochenen Prüfpfaden. Für Organisationen, die Hunderte von Akten pro Monat verarbeiten, wird dieser manuelle Workflow zu einem echten Engpass.

Dieser Artikel beschreibt drei Integrationsmuster, die CheckFile direkt mit Ihrem Informationssystem verbinden – ob das SAP, Salesforce, ein eigenes CRM oder eine interne Workflow-Engine ist. Sie finden Architekturdiagramme, funktionsfähige Codebeispiele und Best Practices aus realen Implementierungen. Falls Sie zuerst die Endpunkt-Referenz suchen, lesen Sie den API-Leitfaden.

Warum Dokumentenprüfung kein eigenständiges Tool bleiben darf

Ein Prüftool, das außerhalb Ihrer Kernsysteme lebt, erzeugt drei strukturelle Probleme.

Workflow-Unterbrechung. Der Sachbearbeiter verlässt seine primäre Arbeitsumgebung (CRM, ERP, internes Portal), um ein separates Tool zu nutzen. Jeder Wechsel kostet 2 bis 5 Minuten pro Akte. Bei 500 Akten pro Monat summiert sich das auf 25 bis 40 verlorene Stunden.

Unterbrochene Prüfpfade. Prüfergebnisse sind nicht mit dem Kundendatensatz im Referenzsystem verknüpft. Bei einem Audit muss die Kette manuell rekonstruiert werden: Wer hat was validiert, wann, mit welchem Ergebnis.

Übertragungsfehler. Wenn ein Sachbearbeiter manuell einen Dokumentenstatus vom Prüftool ins CRM kopiert, liegt die Fehlerquote zwischen 2 und 5 Prozent. Bei 10.000 Akten pro Jahr bedeutet das 200 bis 500 Datensätze mit inkonsistentem Status.

Direkte Integration eliminiert alle drei Probleme. Der Rest dieses Artikels erklärt die Umsetzung.

Drei Integrationsmuster

Das richtige Muster hängt vom Dokumentenvolumen, der akzeptablen Latenz und der technischen Reife Ihres Teams ab.

Muster 1 – Batch-Upload

Batch-Upload eignet sich, wenn Latenz nicht kritisch ist: Migration eines Dokumentenarchivs, periodische Wiederverarbeitung oder nächtliche Data-Warehouse-Feeds.

Das Prinzip ist einfach: Eine Reihe von Dateien über den Batch-Endpunkt einreichen, dann Ergebnisse abrufen, sobald die Verarbeitung abgeschlossen ist.

# Batch von 3 Dokumenten hochladen
curl -X POST https://api.checkfile.ai/api/v1/files/batch \
  -H "X-API-Key: ck_live_ihr_schluessel" \
  -F "files[]=@rechnung_001.pdf" \
  -F "files[]=@handelsregisterauszug.pdf" \
  -F "files[]=@bankverbindung.pdf" \
  -F "dossier_id=DOS-2026-0042" \
  -F "callback_url=https://ihre-app.de/webhooks/checkfile"

Der Server gibt sofort eine Batch-Kennung zurück:

{
  "batch_id": "bat_7f3a9c2e",
  "file_count": 3,
  "status": "queued",
  "estimated_completion": "2026-02-21T14:35:00Z"
}

Sie können dann den Batch-Status abfragen oder auf den Abschluss-Webhook warten.

Muster 2 – Echtzeit-API

Das häufigste Muster für interaktive Anwendungen: Ein Benutzer lädt ein Dokument hoch, Ihre Anwendung sendet es an CheckFile, wartet auf das Ergebnis und zeigt es an. Die vollständige Endpunkt-Referenz wird im API-Leitfaden behandelt.

# Einzelnes Dokument hochladen
curl -X POST https://api.checkfile.ai/api/v1/files \
  -H "X-API-Key: ck_live_ihr_schluessel" \
  -H "Idempotency-Key: upload-dos042-hr-auszug" \
  -F "file=@handelsregisterauszug.pdf" \
  -F "document_type=company_registration" \
  -F "rules=freshness_90d,company_number_match"

Muster 3 – Eventgesteuerte Webhooks

Webhooks kehren den Fluss um: Statt die API abzufragen, benachrichtigt CheckFile Ihr System, sobald die Verarbeitung abgeschlossen ist. Dies ist das empfohlene Muster für automatisierte Pipelines und ERP-Integrationen.

Der Vorteil ist zweifach: minimale Latenz (Push-Benachrichtigung innerhalb von Sekunden) und null verschwendeter Polling-Traffic.

Webhook-Architektur im Detail

Registrierung eines Webhook-Endpunkts

curl -X POST https://api.checkfile.ai/api/v1/webhooks \
  -H "X-API-Key: ck_live_ihr_schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://ihre-app.de/webhooks/checkfile",
    "events": ["file.validated", "file.rejected", "batch.completed"],
    "secret": "whsec_ihr_signierungsgeheimnis"
  }'

Webhook-Payload: Dokument validiert

Wenn ein Dokument alle Prüfregeln besteht, sendet CheckFile einen POST an Ihren Endpunkt mit folgendem Payload:

{
  "event": "file.validated",
  "timestamp": "2026-02-21T14:22:18Z",
  "data": {
    "file_id": "fil_8b2c4d1e",
    "dossier_id": "DOS-2026-0042",
    "document_type": "company_registration",
    "status": "validated",
    "confidence_score": 0.97,
    "extracted_fields": {
      "company_name": "Mustermann Industrie GmbH",
      "company_number": "HRB 123456",
      "incorporation_date": "2019-03-15",
      "registered_address": "Musterstraße 42, 60329 Frankfurt am Main",
      "director": "Max Mustermann",
      "document_date": "2026-01-28"
    },
    "rules_results": [
      {
        "rule": "freshness_90d",
        "status": "passed",
        "detail": "Dokument vom 28.01.2026, gültig bis 28.04.2026"
      },
      {
        "rule": "company_number_match",
        "status": "passed",
        "detail": "HRB-Nummer HRB 123456 stimmt mit Aktendaten überein"
      }
    ],
    "processing_time_ms": 3420
  }
}

Webhook-Payload: Dokument abgelehnt

{
  "event": "file.rejected",
  "timestamp": "2026-02-21T14:23:05Z",
  "data": {
    "file_id": "fil_9c3d5e2f",
    "dossier_id": "DOS-2026-0042",
    "document_type": "bank_statement",
    "status": "rejected",
    "confidence_score": 0.42,
    "rejection_reasons": [
      {
        "rule": "iban_valid",
        "status": "failed",
        "detail": "IBAN DE89 3704 0044 0532 ... : Prüfziffern ungültig"
      },
      {
        "rule": "account_holder_match",
        "status": "failed",
        "detail": "Kontoinhaber 'Eichenholz Immobilien GmbH' stimmt nicht mit 'Mustermann Industrie GmbH' überein"
      }
    ],
    "processing_time_ms": 2180
  }
}

Webhook-Verarbeitung in Python

from flask import Flask, request, abort
import hmac
import hashlib

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_ihr_signierungsgeheimnis"

def verify_signature(payload: bytes, signature: str) -> bool:
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

@app.route("/webhooks/checkfile", methods=["POST"])
def handle_webhook():
    # 1. Signatur prüfen
    signature = request.headers.get("X-CheckFile-Signature", "")
    if not verify_signature(request.data, signature):
        abort(401)

    event = request.json
    event_type = event["event"]
    data = event["data"]

    # 2. Nach Eventtyp weiterleiten
    if event_type == "file.validated":
        update_crm_document_status(
            dossier_id=data["dossier_id"],
            document_type=data["document_type"],
            status="validated",
            extracted_fields=data["extracted_fields"]
        )
    elif event_type == "file.rejected":
        trigger_operator_alert(
            dossier_id=data["dossier_id"],
            reasons=data["rejection_reasons"]
        )
    elif event_type == "batch.completed":
        finalize_dossier(data["batch_id"])

    # 3. Schnell 200 antworten
    return {"received": True}, 200

Webhook-Verarbeitung in Node.js

const express = require("express");
const crypto = require("crypto");

const app = express();
const WEBHOOK_SECRET = "whsec_ihr_signierungsgeheimnis";

app.post("/webhooks/checkfile", express.raw({ type: "application/json" }), (req, res) => {
  // Signatur prüfen
  const signature = req.headers["x-checkfile-signature"] || "";
  const expected = `sha256=${crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex")}`;

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send("Ungültige Signatur");
  }

  const event = JSON.parse(req.body);

  switch (event.event) {
    case "file.validated":
      updateCrmStatus(event.data);
      break;
    case "file.rejected":
      notifyOperator(event.data);
      break;
    case "batch.completed":
      finalizeDossier(event.data);
      break;
  }

  res.json({ received: true });
});

ERP-Integrationsmuster nach Plattform

SAP

Für SAP S/4HANA oder SAP Business One existieren zwei Ansätze:

Via SAP Integration Suite (ehemals CPI). Ein iFlow empfängt den Webhook, transformiert den Payload in ein IDoc oder eine OData-Entität und injiziert ihn in SAP. Dieser Ansatz wird von SAP-Basis-Teams bevorzugt, weil er im SAP-Ökosystem bleibt.

Via generische Middleware. Ein Python- oder Node.js-Connector empfängt den Webhook und ruft die SAP-OData-API direkt auf. Schneller einzurichten, erfordert aber die Verwaltung der SAP-Authentifizierung (OAuth oder Basic Auth mit Client-Zertifikaten).

Salesforce

Die häufigste Salesforce-Integration nutzt einen Apex Trigger oder Flow, ausgelöst durch den CheckFile-Webhook:

1. Leichtgewichtige Middleware (Heroku, AWS Lambda oder MuleSoft) empfängt den CheckFile-Webhook.
2. Die Middleware ruft die Salesforce-REST-API auf, um das Document__c- oder ContentVersion-Objekt zu aktualisieren.
3. Ein Salesforce Flow reagiert auf das Update und löst nachgelagerte Geschäftslogik aus.

DATEV und deutsche Buchhaltungssoftware

Für DATEV-Integration gibt es zwei Pfade: Die DATEV-Schnittstelle via DATEVconnect online für den automatisierten Belegaustausch, oder eine direkte API-Anbindung über Middleware, die Prüfergebnisse in die DATEV-kompatible Struktur transformiert.

Für Lexware, sevDesk oder andere deutsche Buchhaltungslösungen empfiehlt sich die Webhook-basierte Integration, bei der Prüfergebnisse automatisch in die jeweilige Software geschrieben werden.

Eigenes CRM oder internes Tool

Für interne Tools ist der Webhook die direkteste Methode. Ihr Backend empfängt den Payload, extrahiert relevante Felder und aktualisiert Ihre Datenbank. Keine zusätzliche Middleware nötig.

# Beispiel: Direktes Datenbank-Update nach Webhook-Empfang
def update_crm_document_status(dossier_id, document_type, status, extracted_fields):
    db.execute(
        """
        UPDATE documents
        SET validation_status = %s,
            extracted_data = %s,
            validated_at = NOW()
        WHERE dossier_id = %s AND document_type = %s
        """,
        (status, json.dumps(extracted_fields), dossier_id, document_type)
    )

    # Prüfen ob alle Dokumente im Vorgang validiert sind
    pending = db.fetchone(
        "SELECT COUNT(*) FROM documents WHERE dossier_id = %s AND validation_status = 'pending'",
        (dossier_id,)
    )
    if pending[0] == 0:
        mark_dossier_complete(dossier_id)

Authentifizierung und Sicherheit

API-Integration innerhalb eines Unternehmens-IT-Systems erfordert stärkere Sicherheitsgarantien als ein Prototyp.

API-Schlüssel Best Practices

• Ein Schlüssel pro Umgebung. Entwicklung (ck_test_), Staging, Produktion (ck_live_). Niemals einen Schlüssel über Umgebungen teilen.
• Regelmäßige Rotation. Schlüssel alle 90 Tage rotieren. Die API unterstützt zwei gleichzeitig aktive Schlüssel für ausfallfreie Rotation.
• Sichere Speicherung. Vault (HashiCorp), AWS Secrets Manager oder Azure Key Vault verwenden. Niemals Schlüssel im Klartext im Quellcode oder in einer eingecheckten .env-Datei speichern. OWASP API Security Best Practices für Schlüsselverwaltung und Transportsicherheit befolgen.

Webhook-Verifizierung

Jeder Webhook ist mit Ihrem Geheimnis (whsec_...) signiert. Immer die HMAC-SHA256-Signatur prüfen, bevor der Payload verarbeitet wird. Die Codebeispiele oben zeigen die Implementierung in Python und Node.js.

Fehlerbehandlung und Retry-Strategien

Transiente Fehler (5xx, Timeout)

CheckFile wiederholt Webhooks automatisch bei Fehlern. Der Retry-Zeitplan folgt exponentiellem Backoff:

Nach 5 Fehlschlägen wird der Webhook als „fehlgeschlagen" markiert und eine E-Mail-Warnung gesendet.

Idempotenz

Ihr Webhook-Endpunkt muss idempotent sein. CheckFile kann dasselbe Event bei einem Netzwerk-Timeout erneut senden. Verwenden Sie das file_id-Feld als Idempotenz-Schlüssel:

if db.exists("SELECT 1 FROM webhook_events WHERE file_id = %s", (data["file_id"],)):
    return {"received": True}, 200  # Bereits verarbeitet, überspringen

db.insert("webhook_events", file_id=data["file_id"], processed_at=now())
# ... normale Verarbeitung

Migrationspfad: Vom manuellen Upload zur vollautomatisierten Pipeline

Stufe 1 – Web-Oberfläche (Woche 1). Das CheckFile-Dashboard nutzen, um erste Dokumente manuell zu validieren. Ziel: Geschäftsregeln und Dokumententypen bestätigen.

Stufe 2 – Echtzeit-API (Woche 2–3). Die Upload-API in Ihre Anwendung integrieren. Sachbearbeiter verlassen nicht mehr ihr primäres Tool, aber der Prozess wird noch manuell ausgelöst.

Stufe 3 – Webhooks (Woche 4–5). Webhooks aktivieren, um Ergebnisse automatisch zu empfangen. Ihr CRM/ERP wird ohne menschliches Eingreifen aktualisiert. Sachbearbeiter arbeiten nur noch abgelehnte Akten ab.

Stufe 4 – Vollautomatisierte Pipeline (Woche 6–8). Dokumente werden automatisch beim Eingang hochgeladen (E-Mail-Parser, Kundenportal, Scanner). Webhooks speisen das ERP. Sachbearbeiter behandeln nur noch Ausnahmen.

Auf jeder Stufe können Sie Zeiteinsparungen und Fehlerquotenreduktion messen, um die Investition in den nächsten Schritt zu rechtfertigen. Wenn Sie abwägen, ob Sie eine eigene Prüflösung bauen oder eine bestehende Plattform nutzen, lesen Sie unsere Eigenentwicklung-vs.-Kauflösung-Analyse.

Häufig gestellte Fragen

Welches Integrationsmuster ist für kleine Teams mit wenig technischem Know-how am besten geeignet?

Für Teams ohne dedizierte Entwicklerressourcen ist das Batch-Upload-Muster der einfachste Einstieg: Dokumente werden per curl-Befehl oder über einen einfachen Skript-Wrapper hochgeladen, und die Ergebnisse werden zu einem festgelegten Zeitpunkt abgerufen. Dieser Ansatz erfordert keine Webhook-Infrastruktur und liefert in wenigen Stunden erste Ergebnisse. Sobald das Team mit den Prüfergebnissen vertraut ist, kann in einem zweiten Schritt auf Echtzeit-API oder Webhooks umgestellt werden.

Wie wird sichergestellt, dass ein Webhook nicht zweimal denselben Datensatz aktualisiert?

Webhook-Endpunkte müssen idempotent implementiert werden, da CheckFile dasselbe Event bei Netzwerk-Timeouts mehrfach senden kann. Die empfohlene Methode ist, das file_id-Feld als Idempotenz-Schlüssel zu verwenden und vor jeder Verarbeitung zu prüfen, ob dieses Event bereits in der Datenbank gespeichert ist. Nur wenn kein Eintrag gefunden wird, sollte die Verarbeitung fortgesetzt werden.

Welche Besonderheiten sind bei der DATEV-Integration zu beachten?

Für DATEV-Integrationen stehen zwei Pfade zur Verfügung: die DATEV-Schnittstelle via DATEVconnect online für den automatisierten Belegaustausch oder eine direkte API-Anbindung über Middleware, die Prüfergebnisse in die DATEV-kompatible Struktur transformiert. CheckFile liefert strukturierte Extraktionsdaten im Format, das DATEV-Systeme erwarten, einschließlich Buchungssatzentwürfen mit USt-Schlüsseln und Stammdatenabgleich. Die Integration ist typischerweise in 2 bis 3 Entwicklertagen abgeschlossen.

Wie lange dauert es, von manuellen Uploads zur vollautomatisierten Pipeline zu gelangen?

Der empfohlene Migrationspfad verläuft in vier Stufen über 6 bis 8 Wochen: Dashboard-Nutzung in Woche 1, API-Integration in Wochen 2 bis 3, Webhook-Aktivierung in Wochen 4 bis 5 und vollautomatisierte Pipeline in Wochen 6 bis 8. Auf jeder Stufe sind Zeiteinsparungen und Fehlerquotenreduktion messbar, was die Investition in den nächsten Schritt rechtfertigt. Für Teams mit 200 oder mehr Akten pro Monat liegt der Return on Investment der vollständigen Integration typischerweise unter 3 Monaten.

Fazit: Integration als Produktivitätsmultiplikator

Dokumentenprüfung entfaltet ihren vollen Wert erst, wenn sie in den bestehenden Workflow eingebettet ist. Eine gut konzipierte REST-API, zuverlässige Webhooks und auf Ihr ERP zugeschnittene Integrationsmuster verwandeln ein Prüftool in eine native Komponente Ihres Informationssystems.

Die konkreten Gewinne: Eliminierung manueller Übertragung, vollständige Prüfpfade, Echtzeitverarbeitung und messbare Fehlerquotenreduktion. Für Teams, die mehr als 200 Akten pro Monat verarbeiten, liefert die Integration typischerweise einen Return on Investment in unter 3 Monaten.

Bereit, die Dokumentenprüfung an Ihr IT-System anzubinden? Erkunden Sie die CheckFile-API-Dokumentation oder kontaktieren Sie unser technisches Team für maßgeschneiderte Beratung. Die Preise beinhalten API-Zugang auf allen Plänen, mit einer Sandbox-Umgebung zum Testen Ihrer Integration vor dem Go-Live.