API-Dokumentation

Endpoint

Authentifizierung über einen API-Schlüssel im Authorization-Header. Schlüssel erstellen Sie im Dashboard unter „API-Schlüssel“; jeder Aufruf zählt gegen Ihr Monatskontingent. Die Version steht im Pfad — /v1/ ist die aktuelle.

curl -X POST \
  -H "Authorization: Bearer <api-key>" \
  -F "file=@fahrzeugschein.jpg" \
  https://api.fahrzeugschein24.de/v1/extract

Formate und Limits

• JPEG, PNG, TIFF, BMP, WebP, HEIC/HEIF sowie PDF (Seite 1)
• Maximal 20 MB pro Datei
• Alternativ zum Formular-Upload: das Bild direkt als Request-Body senden
• Gedrehte oder schräg fotografierte Aufnahmen werden automatisch korrigiert
• Kurzzeit-Limit je Tarif: 10 (Free) bis 150 (Enterprise) Anfragen pro Minute, zusätzlich zum Monatskontingent
• Anfragen mit Echtheitsprüfung haben ein eigenes, engeres Minutenlimit

Versionierung

Die API ist versioniert: Innerhalb einer Version ändern sich Antwortstruktur und Fehlercodes nicht mehr. Neue, nicht abwärtskompatible Funktionen erscheinen unter einer neuen Version — Ihre bestehende Anbindung läuft unverändert weiter.

• Aktueller Pfad: /v1/extract — die Version steht immer im Pfad
• Der Pfad ohne Versionsangabe (/extract) bleibt dauerhaft auf v1 festgelegt
• Jede Antwort nennt im Header X-API-Version die bearbeitende Version
• Vor einer Abkündigung informieren die Header Deprecation und Sunset über den Zeitplan

Optionen pro Anfrage

Optionale Formularfelder neben „file“. Ohne Angabe gelten Ihre gespeicherten Einstellungen aus dem Dashboard.

• services — „extraction“ (Standard) oder „extraction,fraud_detection“ für die zusätzliche Echtheitsprüfung.
• include_field_images — true/false — Bildausschnitt je Feld (cutout_image) mitliefern.
• include_document_image — true/false — zugeschnittenes Gesamtbild des Dokuments mitliefern (vergrößert die Antwort deutlich).

Antwort

„fields“ ist ein Objekt, in dem jeder Feldname auf value, confidence (0–1), bbox und optional cutout_image zeigt. Welche Felder enthalten sind, legen Sie in den Einstellungen fest. „vin_valid“ ist kein Feld, sondern das Ergebnis der Prüfziffernkontrolle zur FIN — true, false oder null, wenn nichts zu vergleichen war. Ist für Ihr Konto die Ausgabe als ausgefülltes PDF eingerichtet, kommt statt dieser Antwort Ihr ausgefülltes PDF-Formular zurück; mit dem zusätzlichen Formularfeld „output=json“ erhalten Sie für einzelne Anfragen stattdessen diese Antwort. Fehler bleiben JSON.

{
  "fields": {
    "registrationNumber": { "value": "HH-PS 241",         "confidence": 0.99, "bbox": [412, 268, 668, 318] },
    "vin":                { "value": "WVWZZZ1JZXW000001", "confidence": 0.96, "bbox": [770, 512, 1290, 566] },
    "d1":                 { "value": "VOLKSWAGEN",        "confidence": 0.98, "bbox": [770, 604, 1010, 652] },
    "ez":                 { "value": "14.03.2019",        "confidence": 0.97, "bbox": [412, 604, 604, 652] }
  },
  "vin_valid": true,
  "image_width": 2480,
  "image_height": 1748,
  "services": ["extraction"]
}

Echtheitsprüfung (optional)

Ist die Betrugserkennung aktiviert, enthält die JSON-Antwort zusätzlich ein fraud_detection-Objekt: eine Gesamtnote overall_risk (A–F), getrennte Bewertungen für Bildbearbeitung und KI-Erzeugung sowie einen Eintrag je Einzelprüfung unter tests: metadata und thumbnail, bei JPEG-Dateien ela, jpeg_ghost nur bei Dateien, die eine Einschätzung zulassen, zusammen mit der Extraktion außerdem field_consistency und bei JPEG-Aufnahmen glyph_duplicates. Die Bewertung ai_generated stützt sich allein auf die Herkunftsangaben der Datei. Über die API ist die Prüfung ab dem Tarif Business enthalten; in den kleineren Tarifen können Sie sie mit 10 kostenlosen Analysen pro Monat im Playground testen.

{
  "fraud_detection": {
    "overall_risk": "A",
    "verdict": "authentic",
    "fraud_score":  { "risk": "A", "score": 0.05 },
    "ai_generated": { "risk": "A", "score": 0.00 },
    "tests": {
      "metadata":          { "risk": "A", "score": 0.00, "findings": [] },
      "thumbnail":         { "risk": "A", "score": 0.00, "findings": [] },
      "ela":               { "risk": "A", "score": 0.00, "findings": [] },
      "glyph_duplicates":  { "risk": "A", "score": 0.00, "findings": [] },
      "field_consistency": { "risk": "A", "score": 0.00, "status": "ok" }
    }
  }
}

Dublettenprüfung (dokumentübergreifend)

Jede JSON-Antwort enthält ein cross_document-Objekt. Es erkennt — unabhängig von der Echtheitsprüfung und nur innerhalb Ihres eigenen Kontos — wenn dieselbe Dokumentnummer oder dieselbe Seitenvorlage erneut mit anderen Daten eingereicht wird. Für die Dublettenprüfung wird kein Dokument gespeichert, sondern je Einreichung nur ein nicht umkehrbarer Fingerabdruck aus gesalzenen Hashwerten und groben Bildmerkmalen — keine Klartextdaten.

{
  "cross_document": {
    "verdict": "alert",
    "is_duplicate": true,
    "document_id": "B-S-2-313/15-64360",
    "matches": [
      {
        "type": "document_id_reuse",
        "severity": "alert",
        "message": "Same document number already used for a DIFFERENT vehicle (VIN mismatch).",
        "prior_seen_at": "2026-06-20T09:14:00+00:00",
        "distinct_count": 2
      }
    ]
  }
}

Fehlercodes

• 400Kein Bild im Request (Feld „file“ fehlt oder Body leer) oder ungültiger Wert im Feld „output“ (nur bei Konten mit PDF-Ausgabe).
• 401API-Schlüssel fehlt, ist ungültig oder wurde widerrufen.
• 402Funktion im Tarif nicht enthalten (z. B. Echtheitsprüfung unterhalb von Business).
• 409Ausgabe als ausgefülltes PDF eingestellt, aber kein Formular eingerichtet.
• 413Datei größer als 20 MB.
• 415Nicht unterstütztes Dateiformat.
• 429Minutenlimit überschritten, Dienst kurzzeitig ausgelastet oder monatliches Kontingent aufgebraucht (Feld „code“ unterscheidet die Fälle).
• 500Das ausgefüllte PDF konnte nicht erstellt werden; zählt nicht auf das Kontingent.
• 502Verarbeitung vorübergehend nicht erreichbar.
• 504Zeitüberschreitung bei der Verarbeitung.

Mehr Beispiele

Die vollständige Dokumentation mit Beispielen in cURL, Node.js und Python sowie Ihren persönlichen Schlüsseln finden Sie nach der Anmeldung im Dashboard.