Dokumentenprüfung-API: Integrationsleitfaden für Entwickler

Eine Dokumentenprüfung-API ist eine programmatische Schnittstelle, über die Entwickler Ausweisdokumente, Rechnungen, Bescheinigungen oder Adressnachweise einreichen und strukturierte Prüfergebnisse erhalten — Echtheitsprüfungen, Datenextraktion, Betrugssignale — ohne die zugrunde liegenden KI-Modelle selbst entwickeln zu müssen. Die CheckFile-API verarbeitet ein Dokument in durchschnittlich 4,2 Sekunden, erreicht eine OCR-Genauigkeit von 98,7 % in 24 Sprachen und unterstützt mehr als 3 200 Dokumenttypen in 32 Rechtsräumen.

Die EU-KI-Verordnung (Verordnung (EU) 2024/1689, Art. 6 und Anhang III) stuft KI-Systeme zur Identitätsdokumentenprüfung im Finanzdienstleistungsbereich als Hochrisiko ein und verpflichtet Anbieter zur Führung technischer Dokumentation, eines Risikomanagementsystems und menschlicher Aufsichtsfähigkeiten. Jede API, die Sie integrieren, muss diese Anforderungen erfüllen — andernfalls übernehmen Sie die Konformitätslücke.

Dieser Leitfaden behandelt Authentifizierung, Kern-Endpoints, Webhook-Konfiguration, Fehlerbehandlung, SDK-Optionen und Preisgestaltung. Er richtet sich an Backend-Entwickler, DevOps-Teams und technische Leiter, die Dokumentenprüfung-APIs für den Produktionseinsatz evaluieren.

Dieser Artikel dient ausschließlich zu Informationszwecken und stellt keine Rechts-, Finanz- oder Regulierungsberatung dar.

Authentifizierung und Sicherheit

Die CheckFile-API verwendet OAuth 2.0 Client Credentials für die Maschine-zu-Maschine-Authentifizierung gemäß RFC 6749, Abschnitt 4.4. Sie tauschen Ihre client_id und client_secret gegen ein zeitlich begrenztes Bearer-Token (60 Minuten Gültigkeit) und fügen dieses Token im Authorization-Header jeder nachfolgenden Anfrage ein.

Sämtlicher API-Verkehr ist mit TLS 1.3 verschlüsselt. Dokumente werden im Ruhezustand mit AES-256 verschlüsselt, und personenbezogene Daten werden automatisch aus Protokollen entfernt — in Übereinstimmung mit Art. 32 DSGVO zu angemessenen technischen Maßnahmen (DSGVO, Art. 32).

 # Zugriffstoken abrufen
curl -X POST https://api.checkfile.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=IHRE_ID&client_secret=IHR_SECRET"

 # Antwort
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Zentrale Sicherheitsfunktionen:

• IP-Allowlisting — API-Zugriff auf bekannte Server-IPs beschränken
• Rate-Limiting — pro Plan konfigurierbar (siehe Preisabschnitt)
• Webhook-Signaturen — HMAC-SHA256-Überprüfung bei jedem Callback
• Audit-Log — jeder API-Aufruf wird mit Zeitstempel, Client-ID, Dokumenttyp und Ergebnis protokolliert

Scopes und Berechtigungen

Kern-Endpoints der API

Die API folgt RESTful-Konventionen mit JSON-Payloads. Basis-URL: https://api.checkfile.ai/v1.

Dokumenteinreichung

POST /v1/documents/verify
Content-Type: multipart/form-data
Authorization: Bearer {token}

 # Felder:
 # file (erforderlich) — Dokumentbild oder PDF (max. 20 MB)
 # document_type (optional) — "passport", "id_card", "invoice", "proof_of_address"
 # country (optional) — ISO 3166-1 Alpha-2-Code
 # webhook_url (optional) — Callback-URL für asynchrone Ergebnisse
 # reference_id (optional) — Ihre interne Referenz zur Korrelation

Antwort (HTTP 202 Accepted):

{
  "document_id": "doc_8f3a2b1c",
  "status": "processing",
  "estimated_completion_seconds": 4,
  "created_at": "2026-03-19T10:15:00Z"
}

Wird document_type nicht angegeben, verwendet die API ihr KI-Klassifizierungssystem — das eine Klassifizierungsgenauigkeit von 96,1 % bei unserem Benchmark von über 3 200 Dokumenttypen erreicht — zur automatischen Typerkennung.

Ergebnisabfrage

GET /v1/documents/{document_id}
Authorization: Bearer {token}

Antwort (HTTP 200):

{
  "document_id": "doc_8f3a2b1c",
  "status": "completed",
  "document_type": "personalausweis",
  "country": "DE",
  "verification": {
    "authentic": true,
    "confidence": 0.97,
    "fraud_signals": [],
    "checks": {
      "mrz_valid": true,
      "photo_tamper": false,
      "expiry_valid": true,
      "data_consistency": true
    }
  },
  "extracted_data": {
    "full_name": "Anna Müller",
    "date_of_birth": "1990-05-12",
    "document_number": "T220001293",
    "expiry_date": "2031-05-11",
    "nationality": "DEU"
  },
  "processing_time_ms": 3840,
  "created_at": "2026-03-19T10:15:00Z",
  "completed_at": "2026-03-19T10:15:03.840Z"
}

Das extracted_data-Objekt erreicht eine Feldextraktionsgenauigkeit von 94,3 % in unserem internen Benchmark über alle unterstützten Dokumenttypen.

Stapelverarbeitung

Für Integrationen mit hohem Volumen akzeptiert der Batch-Endpoint bis zu 50 Dokumente pro Anfrage:

POST /v1/documents/verify/batch
Content-Type: multipart/form-data
Authorization: Bearer {token}

 # files[] — Array von Dokumentdateien
 # options — JSON-Objekt mit gemeinsamen Einstellungen

Batch-Anfragen geben eine batch_id zurück und liefern Ergebnisse per Webhook, sobald jedes Dokument verarbeitet ist.

Webhook-Konfiguration

Ereignisgesteuerte Architekturen vermeiden Polling-Overhead. Registrieren Sie einen Webhook-Endpoint, um Echtzeit-Benachrichtigungen nach Abschluss der Prüfungen zu erhalten.

POST /v1/webhooks
Authorization: Bearer {token}
Content-Type: application/json

{
  "url": "https://ihre-app.de/webhooks/checkfile",
  "events": ["document.completed", "document.failed", "document.review_required"],
  "secret": "whsec_ihr_geheimer_schluessel"
}

Jede Webhook-Zustellung enthält einen X-CheckFile-Signature-Header mit einem HMAC-SHA256-Hash des Payloads. Überprüfen Sie ihn vor der Verarbeitung:

import hmac
import hashlib

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

Webhook-Wiederholungsrichtlinie: 3 Versuche mit exponentiellem Backoff (5s, 30s, 300s). Nach 3 Fehlversuchen wird der Webhook deaktiviert und Ihr Team erhält eine E-Mail-Benachrichtigung.

SDK und Integrationsoptionen

Die REST-API funktioniert mit jeder Programmiersprache, aber offizielle SDKs reduzieren die Integrationszeit von Tagen auf Stunden.

Verfügbare SDKs

Python-Integrationsbeispiel

from checkfile import CheckFileClient

client = CheckFileClient(
    client_id="IHRE_CLIENT_ID",
    client_secret="IHR_CLIENT_SECRET"
)

 # Synchrone Prüfung
result = client.documents.verify(
    file=open("personalausweis.pdf", "rb"),
    document_type="id_card",
    country="DE"
)

print(f"Authentisch: {result.verification.authentic}")
print(f"Name: {result.extracted_data.full_name}")
print(f"Verarbeitungszeit: {result.processing_time_ms}ms")

Node.js-Integrationsbeispiel

import { CheckFileClient } from '@checkfile/sdk';
import { readFileSync } from 'fs';

const client = new CheckFileClient({
  clientId: process.env.CHECKFILE_CLIENT_ID,
  clientSecret: process.env.CHECKFILE_CLIENT_SECRET,
});

const result = await client.documents.verify({
  file: readFileSync('personalausweis.pdf'),
  documentType: 'id_card',
  country: 'DE',
});

console.log(`Authentisch: ${result.verification.authentic}`);
console.log(`Vertrauen: ${result.verification.confidence}`);

Die SDKs übernehmen Token-Erneuerung, Wiederholungsversuche mit exponentiellem Backoff und Webhook-Signaturprüfung automatisch. Unsere Analyse zeigt, dass SDK-basierte Integrationen die mediane Zeit bis zur Produktionsreife von 8 Tagen (reines REST) auf 2 Tage reduzieren.

Fehlerbehandlung und Rate-Limits

Die API verwendet Standard-HTTP-Statuscodes mit strukturierten Fehlerkörpern:

{
  "error": {
    "code": "DOCUMENT_UNREADABLE",
    "message": "Die hochgeladene Datei konnte nicht verarbeitet werden. Stellen Sie sicher, dass DPI >= 300.",
    "details": { "min_dpi": 300, "detected_dpi": 72 },
    "request_id": "req_9f2c4d1e"
  }
}

Häufige Fehlercodes

Rate-Limits nach Tarif

Rate-Limit-Header (X-RateLimit-Remaining, X-RateLimit-Reset) sind in jeder Antwort enthalten. Bauen Sie Ihre Wiederholungslogik auf diesen Headern auf, statt Verzögerungen fest zu kodieren.

Konformität und Datenverarbeitung

Die Dokumentenprüfung berührt personenbezogene Daten in mehreren Rechtsräumen. Die API ist mit Konformität als erstrangiger Anforderung konzipiert.

Seit März 2026 verpflichtet die DSGVO (Verordnung (EU) 2016/679, Art. 28) Verantwortliche, nur Auftragsverarbeiter einzusetzen, die hinreichende Garantien für geeignete technische und organisatorische Maßnahmen bieten. CheckFile agiert als Auftragsverarbeiter mit einem unterzeichneten Auftragsverarbeitungsvertrag (AVV) in allen Business- und Enterprise-Tarifen.

Gemäß den Anforderungen der BaFin an die Auslagerung von IT-Dienstleistungen (MaRisk AT 9) bietet die API:

• Aufbewahrung: Dokumente werden nach der Verarbeitung gelöscht, sofern Sie nicht explizit Speicherung anfordern (konfigurierbar von 0 bis 365 Tagen)
• Datenresidenz: Verarbeitung in der EU standardmäßig; US- und APAC-Regionen auf Enterprise-Tarifen verfügbar
• Prüfpfad: Jeder API-Aufruf erzeugt einen unveränderlichen Prüfdatensatz mit Dokument-Hash, Zeitstempel, Ergebnis und Client-ID
• SOC 2 Typ II-Zertifizierung für die API-Infrastruktur
• PCI-DSS-konforme Dokumentenverarbeitung für Finanzdokumente

Für Integrationen, die dem GwG (Geldwäschegesetz) unterliegen, stellt CheckFile die erforderliche Drittanbieter-Sicherheitsdokumentation, Ergebnisse der Geschäftskontinuitätstests und Exit-Strategiebedingungen bereit.

Preisstruktur

CheckFile verwendet ein Preismodell pro Dokument mit Mengenrabatten. Alle Tarife umfassen den vollständigen API-Zugang, Webhooks und Audit-Protokolle.

Alle Details zu Volumenstufen, Jahresrabatte und Enterprise-SLA-Bedingungen finden Sie auf der Preisseite.

Unsere Plattformanalyse zeigt, dass Organisationen, die von manueller Dokumentenprüfung auf API-basierte Prüfung umsteigen, die Kosten pro Vorgang um 67 % und die Bearbeitungszeit um 83 % senken. Die durchschnittliche Amortisationszeit für Business-Kunden liegt bei unter 3 Monaten ab einem Volumen von 500+ Dokumenten pro Monat.

Integrationsarchitektur-Muster

Muster 1: Synchron (einfach)

Für Integrationen mit niedrigem Volumen (< 60 Anfragen/Min.), einreichen und abfragen:

Client → POST /v1/documents/verify → 202 Accepted
Client → GET /v1/documents/{id} (Polling alle 2s) → 200 mit Ergebnissen

Geeignet für Onboarding-Abläufe, bei denen der Benutzer auf die Verifizierung wartet.

Muster 2: Asynchron mit Webhooks (empfohlen)

Für Produktions-Workloads, einreichen und Ergebnisse per Webhook empfangen:

Client → POST /v1/documents/verify (mit webhook_url) → 202 Accepted
CheckFile → POST webhook_url (signierter Payload) → Ihr Handler verarbeitet das Ergebnis

Entkoppelt Einreichung von Verarbeitung. Skaliert linear mit dem Volumen.

Muster 3: Batch-Pipeline

Für Backoffice-Verarbeitung (nächtliche KYC-Überprüfungen, Massen-Compliance-Checks):

Client → POST /v1/documents/verify/batch (bis zu 50 Dateien) → batch_id
CheckFile → POST webhook_url pro Dokument bei Fertigstellung
CheckFile → POST webhook_url mit batch.completed-Zusammenfassung

Unsere Plattform verarbeitet monatlich über 180.000 Dokumente mit diesen Mustern. Das asynchrone Webhook-Muster deckt 94 % der Produktionsintegrationen ab.

Erste Schritte

Die Integration folgt vier Schritten:

1. Konto erstellen bei checkfile.ai und API-Zugangsdaten im Dashboard generieren
2. In der Sandbox testen — die Sandbox-Umgebung spiegelt die Produktion mit synthetischen Dokumenten wider (ohne Abrechnung)
3. Integrieren mit dem SDK oder direkten REST-Aufrufen, beginnend mit dem synchronen Muster
4. Live gehen — auf Produktions-Zugangsdaten wechseln und Webhooks konfigurieren

Die API-Dokumentation enthält einen interaktiven Playground zum Testen der Endpoints, und die Preisseite erläutert die Tarifoptionen für Ihr erwartetes Volumen.

Für Teams, die automatisierte Dokumentenprüfungs-Workflows aufbauen, lässt sich die API direkt mit den in unserem Workflow-Einrichtungsleitfaden beschriebenen Mustern integrieren. Wenn Sie Prüfungslösungen umfassender evaluieren, deckt unser Leitfaden zur Automatisierung der Dokumentenprüfung das gesamte Spektrum der Ansätze zur Dokumentenprüfung ab.

Häufig gestellte Fragen

Welche Dokumenttypen unterstützt die API?

Die CheckFile-API unterstützt über 3.200 Dokumenttypen in 32 Rechtsräumen: Reisepässe, Personalausweise, Führerscheine, Rechnungen, Kontoauszüge, Adressnachweise, Steuerbescheide, Gehaltsabrechnungen und Handelsregisterauszüge. Das KI-Klassifizierungssystem erkennt Dokumenttypen automatisch mit 96,1 % Genauigkeit, wenn der document_type-Parameter weggelassen wird.

Wie lange dauert die Überprüfung?

Die durchschnittliche Verarbeitungszeit beträgt 4,2 Sekunden pro Dokument. Die P95-Latenz liegt unter 12 Sekunden für Standarddokumenttypen. Batch-Einreichungen verarbeiten Dokumente parallel — ein 50-Dokumente-Batch wird typischerweise in 30 bis 60 Sekunden abgeschlossen, je nach Dokumentkomplexität.

Ist die API DSGVO-konform?

Ja. CheckFile agiert als Auftragsverarbeiter gemäß Art. 28 DSGVO mit unterzeichnetem AVV, EU-basierter Verarbeitungsinfrastruktur, konfigurierbarer Datenaufbewahrung (0 bis 365 Tage) und automatischer Entfernung personenbezogener Daten aus Protokollen. SOC 2 Typ II und ISO 27001-Zertifizierungen decken die API-Infrastruktur ab.

Kann ich die API vor einem kostenpflichtigen Tarif testen?

Der Starter-Tarif umfasst 100 kostenlose Prüfungen pro Monat, und die Sandbox-Umgebung ermöglicht unbegrenzte Tests mit synthetischen Dokumenten ohne Kosten. Keine Kreditkarte erforderlich, um zu starten.

Was passiert, wenn die API ein Dokument nicht verifizieren kann?

Dokumente, die unter den Vertrauensschwellenwert fallen, werden mit dem Status review_required gekennzeichnet und über Webhook an Ihre manuelle Überprüfungswarteschlange weitergeleitet. Die Antwort enthält das Teilergebnis mit Vertrauenswert, extrahierten Daten und den spezifischen Betrugssignalen, die die Kennzeichnung ausgelöst haben. So geht kein Dokument verloren.