Dokumentenprüfungs-API: Entwickler-Leitfaden

Die CheckFile-API verarbeitet Dokumentenprüfungen asynchron über REST, liefert strukturierte Validierungsergebnisse in 2–45 Sekunden und entspricht den Anforderungen der Datenschutz-Grundverordnung (DSGVO, Verordnung (EU) 2016/679) sowie dem Bundesdatenschutzgesetz (BDSG). Ob Sie einen Kunden-Onboarding-Flow, eine Compliance-Pipeline oder ein Back-Office-Automatisierungstool bauen: Die CheckFile-API gibt Ihnen programmatischen Zugriff auf dieselbe KI-gestützte Prüf-Engine, die in der Plattform verwendet wird. Dieser Leitfaden deckt Authentifizierung, Kern-Endpunkte, Codebeispiele in Python und Node.js, Webhook-Payloads, Fehlerbehandlungsstrategien und Integrationsmuster ab.

Architekturüberblick

Die CheckFile-API folgt einem Standard-Async-Verarbeitungsmodell. Dokumente werden via REST hochgeladen, für die KI-Analyse in eine Warteschlange eingereiht, und Ergebnisse werden über Polling oder Webhook-Callbacks geliefert.

Die Bundesanstalt für Finanzdienstleistungsaufsicht (BaFin) verhängte 2024 Bußgelder von insgesamt über 1 Million Euro gegen Institute, die keine angemessenen Datenverarbeitungssysteme zur Geldwäschegesetz (GwG)-Einhaltung betrieben — darunter 600.000 Euro gegen die KT Bank AG (§ 56 GwG, rechtskräftig ab 20. Dezember 2024). (BaFin GwG-Maßnahmen 2024)

Drei zentrale Designentscheidungen prägen diese Architektur. Die eIDAS-Verordnung (EU) Nr. 910/2014, in Kraft seit September 2014, legt für elektronische Identifizierungs- und Vertrauensdienste Sicherheitsanforderungen fest, die API-Integrationen in regulierten Sektoren berücksichtigen müssen. (EUR-Lex eIDAS)

1. Asynchron als Standard. Dokumentenprüfung umfasst OCR, Betrugserkennung, Kreuzreferenzierung und Regelbewertung. Diese Operationen dauern 2–15 Sekunden. Die API akzeptiert Uploads sofort und verarbeitet sie im Hintergrund.

2. Duale Zustellung. Sie können den Status-Endpunkt abfragen oder einen Webhook registrieren. Polling funktioniert für einfache Integrationen; Webhooks sind der empfohlene Ansatz für Produktionssysteme.

3. Idempotente Uploads. Jeder Upload gibt eine eindeutige file_id zurück. Erneutes Hochladen desselben Dokuments mit demselben Idempotenz-Schlüssel gibt das bestehende Ergebnis zurück.

Authentifizierung und Sicherheit

API-Schlüssel-Authentifizierung

Für Server-zu-Server-Integrationen übergeben Sie Ihren API-Schlüssel im X-API-Key-Header:

curl -H "X-API-Key: ck_live_abc123..." \
     https://api.checkfile.ai/v1/files

API-Schlüssel sind Ihrer Organisation zugeordnet. Schlüssel mit Präfix ck_test_ nutzen die Sandbox; Schlüssel mit Präfix ck_live_ die Produktionsumgebung.

Rate Limits

Transportsicherheit

Gesamter Datenverkehr ist mit TLS 1.3 verschlüsselt. Alle hochgeladenen Dokumente werden im Ruhezustand mit AES-256 verschlüsselt und nach Ablauf der konfigurierten Aufbewahrungsfrist automatisch gelöscht — gemäß DSGVO Art. 5 Abs. 1 lit. e (Speicherbegrenzung) und BDSG § 64. Mehr über unsere Sicherheitspraktiken.

Das Bundesamt für Sicherheit in der Informationstechnik (BSI) empfiehlt für Systeme, die personenbezogene Daten verarbeiten, TLS 1.3 und AES-256 als Mindeststandard gemäß BSI TR-02102-2 (aktualisiert Februar 2024). (BSI Technische Richtlinien)

Kern-Endpunkte

Die CheckFile-API stellt sechs primäre REST-Endpunkte bereit, die den vollständigen Dokumentenprüfungs-Lebenszyklus abdecken — von Upload bis Ergebnisabruf.

Basis-URL ist https://api.checkfile.ai. Aktuelle stabile Version ist v1.

Upload und Validierung – Schritt für Schritt

Python (requests)

import requests
import time

API_KEY = "ck_live_abc123..."
BASE_URL = "https://api.checkfile.ai/v1"
HEADERS = {"X-API-Key": API_KEY}

# Schritt 1: Batch von Dokumenten als Akte hochladen
response = requests.post(
    f"{BASE_URL}/files/batch",
    headers=HEADERS,
    files=[
        ("files", ("vertrag.pdf", open("vertrag.pdf", "rb"), "application/pdf")),
        ("files", ("vereinbarung.pdf", open("vereinbarung.pdf", "rb"), "application/pdf")),
        ("files", ("hr-auszug.pdf", open("hr-auszug.pdf", "rb"), "application/pdf")),
    ],
    data={"rule_set": "equipment-leasing"}
)
response.raise_for_status()
file_id = response.json()["id"]
print(f"Akte hochgeladen: {file_id}")

# Schritt 2: Auf Abschluss warten
while True:
    status_resp = requests.get(f"{BASE_URL}/files/{file_id}/status", headers=HEADERS)
    status = status_resp.json()["status"]
    if status in ("completed", "failed"):
        break
    time.sleep(2)

# Schritt 3: Ergebnisse abrufen
results = requests.get(f"{BASE_URL}/files/{file_id}/results", headers=HEADERS).json()

for doc in results["documents"]:
    print(f"{doc['filename']}: {doc['verdict']} (Konfidenz: {doc['confidence']})")
    if doc["alerts"]:
        for alert in doc["alerts"]:
            print(f"  - {alert['severity']}: {alert['message']}")

Node.js (fetch + FormData)

import fs from 'node:fs';

const API_KEY = process.env.CHECKFILE_API_KEY;
const BASE_URL = 'https://api.checkfile.ai/v1';

// Schritt 1: Batch hochladen
const form = new FormData();
form.append('files', new Blob([fs.readFileSync('vertrag.pdf')]), 'vertrag.pdf');
form.append('files', new Blob([fs.readFileSync('vereinbarung.pdf')]), 'vereinbarung.pdf');
form.append('files', new Blob([fs.readFileSync('hr-auszug.pdf')]), 'hr-auszug.pdf');
form.append('rule_set', 'equipment-leasing');

const uploadRes = await fetch(`${BASE_URL}/files/batch`, {
  method: 'POST',
  headers: { 'X-API-Key': API_KEY },
  body: form,
});
const { id: fileId } = await uploadRes.json();

// Schritt 2: Auf Abschluss warten
let status = 'processing';
while (status !== 'completed' && status !== 'failed') {
  await new Promise((r) => setTimeout(r, 2000));
  const statusRes = await fetch(`${BASE_URL}/files/${fileId}/status`, {
    headers: { 'X-API-Key': API_KEY },
  });
  ({ status } = await statusRes.json());
}

// Schritt 3: Ergebnisse abrufen
const results = await fetch(`${BASE_URL}/files/${fileId}/results`, {
  headers: { 'X-API-Key': API_KEY },
}).then((r) => r.json());

for (const doc of results.documents) {
  console.log(`${doc.filename}: ${doc.verdict} (Konfidenz: ${doc.confidence})`);
  for (const alert of doc.alerts) {
    console.log(`  - ${alert.severity}: ${alert.message}`);
  }
}

Webhook-Payloads

Validierung-abgeschlossen-Event

{
  "event": "validation.completed",
  "timestamp": "2026-02-09T14:32:08Z",
  "data": {
    "file_id": "dossier_8f3a2b1c",
    "rule_set": "equipment-leasing",
    "verdict": "approved",
    "processing_time_ms": 4280,
    "documents": [
      {
        "filename": "vertrag.pdf",
        "type": "contract",
        "verdict": "valid",
        "confidence": 0.97,
        "alerts": []
      }
    ]
  }
}

Signaturprüfung

import hmac
import hashlib

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

Fehlerbehandlung

HTTP-Statuscodes 4xx signalisieren Clientfehler, die behoben werden müssen; 5xx-Codes erfordern exponentielle Wiederholungsversuche mit maximal 5 Versuchen und einer Anfangsverzögerung von 1 Sekunde.

Performance-Benchmarks

Einzelne Ausweisdokumente werden im Median in 2,1 Sekunden verarbeitet; komplexe Compliance-Akten mit 15–20 Dokumenten benötigen im Median 22 Sekunden.

Erste Schritte

Eine funktionsfähige Integration ist in fünf Schritten ab dem ersten API-Schlüssel erreichbar — mit vollständiger Testabdeckung innerhalb eines Werktages.

Der schnellste Weg von Null zur funktionierenden Integration:

1. Konto erstellen und Test-API-Schlüssel (ck_test_-Präfix) generieren.
2. Testdokument hochladen mit dem curl-Beispiel oben oder den Code-Samples.
3. Webhook registrieren um Ergebnisse asynchron zu empfangen.
4. Regelsatz konfigurieren der Ihren Geschäftsanforderungen entspricht.
5. Auf Produktion umschalten durch Ersetzen des Test-Schlüssels mit einem Live-Schlüssel (ck_live_-Präfix).

Vollständige Endpunkt-Dokumentation, SDKs (Python, Node.js, Go) und ein interaktiver API-Explorer sind unter docs.checkfile.ai verfügbar. Für Fragen zu Plänen lesen Sie Preise.

Häufig gestellte Fragen

Wie lange dauert die Verarbeitung eines Dokuments über die CheckFile-API?

Die Verarbeitungszeit hängt vom Dokumententyp und der Aktenkomplexität ab. Ein einzelnes Ausweisdokument wird im Median in 2,1 Sekunden verarbeitet (P95: 4,8 Sekunden), ein einzelner Vertrag in 3,4 Sekunden. Eine Standard-Akte mit 8 bis 12 Dokumenten benötigt im Median 12 Sekunden, eine komplexe Compliance-Akte mit 15 bis 20 Dokumenten bis zu 22 Sekunden. Für Batchverarbeitung von 100 Akten beträgt die Gesamtdauer im Median 8 Minuten.

Wie unterscheiden sich Test- und Produktions-API-Schlüssel?

Test-API-Schlüssel tragen das Präfix ck_test_ und nutzen die Sandbox-Umgebung, in der Dokumente verarbeitet, aber nicht dauerhaft gespeichert werden und keine Echtdaten-Datenbanken abgefragt werden. Produktions-Schlüssel mit dem Präfix ck_live_ nutzen die Produktionsumgebung mit echten Datenbanken und voller DSGVO-konformer Verarbeitung. Der Wechsel von Test auf Produktion erfordert lediglich den Austausch des API-Schlüssels im Code.

Was passiert, wenn ein Webhook fehlschlägt und nicht zugestellt werden kann?

CheckFile wiederholt fehlgeschlagene Webhooks automatisch nach einem exponentiellen Backoff-Schema: 30 Sekunden nach dem ersten Fehler, dann 2 Minuten, 10 Minuten, 1 Stunde und schließlich 6 Stunden. Nach 5 fehlgeschlagenen Zustellungsversuchen wird der Webhook als fehlgeschlagen markiert und eine E-Mail-Warnung an den registrierten Kontakt gesendet. Da Webhooks bei Netzwerk-Timeouts auch mehrfach zugestellt werden können, muss der empfangende Endpunkt idempotent implementiert sein.

Welche Sicherheitsstandards gelten für die Übertragung von Dokumenten an die API?

Sämtlicher Datenverkehr ist mit TLS 1.3 verschlüsselt. Hochgeladene Dokumente werden im Ruhezustand mit AES-256 verschlüsselt und nach Ablauf der konfigurierten Aufbewahrungsfrist automatisch gelöscht, in Übereinstimmung mit DSGVO Art. 5 Abs. 1 lit. e und BDSG § 64. Das BSI empfiehlt genau diese Standards als Mindestanforderung gemäß BSI TR-02102-2 für Systeme, die personenbezogene Daten verarbeiten.

Weiterführende Lektüre: Für ERP-spezifische Integrationsmuster einschließlich SAP und Salesforce lesen Sie unseren API-, Webhook- und ERP-Integrations-Leitfaden. Wenn Sie evaluieren, ob Sie Validierung intern entwickeln oder eine API wie diese nutzen, liefert unsere Eigenentwicklung-vs.-Kauflösung-Analyse einen detaillierten 3-Jahres-Kostenvergleich.