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.

{
  "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 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. Ü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.23 },
    "ai_generated": { "risk": "A", "score": 0.02 },
    "tests": {
      "metadata":          { "risk": "A", "score": 0.00, "findings": [] },
      "ela":               { "risk": "A", "score": 0.00, "findings": [] },
      "clone":             { "risk": "A", "score": 0.15, "findings": ["document security pattern"] },
      "field_consistency": { "risk": "A", "score": 0.00, "status": "ok" }
    }
  }
}

Dublettenprüfung (dokumentübergreifend)

Jede 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. Gespeichert werden ausschließlich salted Hashwerte, keine Klartextdaten.

{
  "cross_document": {
    "verdict": "alert",
    "is_duplicate": true,
    "document_id": "B-S-2-189/15-00436",
    "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).
• 401API-Schlüssel fehlt, ist ungültig oder wurde widerrufen.
• 402Funktion im Tarif nicht enthalten (z. B. Echtheitsprüfung unterhalb von Business).
• 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).
• 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.