API-Referenz

Serverseitig authentifizieren.

API-Zugang erhalten Sie auf Anfrage. Verwenden Sie Ihren Schlüssel ausschließlich in Ihrer Serveranwendung, nie im Browser, in mobilen Client-Bundles, URLs oder öffentlichen Repositories.

Fehlende oder falsche Zugangsdaten führen zu 401 unauthorized. Schlüssel werden exakt geprüft. Nach Freischaltung erhalten Sie die separate Basis-URL. Konfigurieren Sie MRZ_BASE_URL und den geschützten Schlüssel MRZ_API_KEY serverseitig. Auf dieser Website ist /v1/mrz aktuell nicht freigeschaltet (HTTP 404).

Ein Bild als Base64-JSON senden.

Setzen Sie Content-Type: application/json und senden Sie genau das Feld image_base64. Die Bildbytes werden mit standardkonformem Base64 kodiert.

{
  "image_base64": "BASE64_BILD"
}

Multipart bleibt unterstützt.

Bestehende Integrationen können weiterhin die Bilddatei im Multipart-Feld file senden. Lassen Sie den HTTP-Client den Content-Type einschließlich Boundary erzeugen. Die Erkennungs- und Antwortsemantik ist für beide Eingabearten gleich.

curl "${MRZ_BASE_URL}/v1/mrz?include_crop=false" \
  --header "Authorization: Bearer $MRZ_API_KEY" \
  --form 'file=@document.jpg' 

POST /v1/mrz

HTTP 200 liefert ein MRZResponse-Objekt. Jedes Dokument bleibt ein eigenständiger Kandidat.

Ergebniszustände

Vollständiges Antwortbeispiel

Schematisches Beispiel mit öffentlichen ICAO-Utopia-Daten. Bildbytes sind durch BASE64_JPEG ersetzt; Zeit- und Versionswerte illustrieren nur den Datentyp und sind kein Leistungsversprechen.

{
  "image": {
    "width": 1200,
    "height": 760,
    "coordinate_space": "exif_oriented_pixels"
  },
  "documents": [
    {
      "status": "recognized",
      "format": "TD3",
      "raw_mrz": [
        "P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<",
        "L898902C36UTO7408122F1204159ZE184226B<<<<<10"
      ],
      "mrz": [
        "P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<",
        "L898902C36UTO7408122F1204159ZE184226B<<<<<10"
      ],
      "fields": {
        "document_code": "P<",
        "issuing_state": "UTO",
        "document_number_raw": "L898902C3",
        "nationality": "UTO",
        "date_of_birth": "740812",
        "sex": "F",
        "date_of_expiry": "120415",
        "optional_data": "ZE184226B<<<<<",
        "names_raw": "ERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<",
        "document_number": "L898902C3",
        "document_number_extended": false,
        "surname_raw": "ERIKSSON",
        "given_names_raw": "ANNA<MARIA",
        "surname": "ERIKSSON",
        "given_names": "ANNA MARIA"
      },
      "checks": {
        "date_of_birth": {
          "expected": "2",
          "actual": "2",
          "valid": true,
          "applicable": true
        },
        "date_of_expiry": {
          "expected": "9",
          "actual": "9",
          "valid": true,
          "applicable": true
        },
        "optional_data": {
          "expected": "1",
          "actual": "1",
          "valid": true,
          "applicable": true
        },
        "document_number": {
          "expected": "6",
          "actual": "6",
          "valid": true,
          "applicable": true
        },
        "composite": {
          "expected": "0",
          "actual": "0",
          "valid": true,
          "applicable": true
        }
      },
      "corrections": [],
      "errors": [],
      "mrz_quad": [
        [
          60.63999938964844,
          516.3800048828125
        ],
        [
          1112.280029296875,
          515.219970703125
        ],
        [
          1112.6600341796875,
          601.4600219726562
        ],
        [
          60.790000915527344,
          602.9500122070312
        ]
      ],
      "recognition_score": 0.9833,
      "recognition_method": "neural_mrz_casefold_aspect0.7+neural_mrz_casefold",
      "document_quad": [
        [
          11.5600004196167,
          3.5999999046325684
        ],
        [
          1185.4300537109375,
          9.420000076293945
        ],
        [
          1185.760009765625,
          756.9400024414062
        ],
        [
          9.619999885559082,
          754.3699951171875
        ]
      ],
      "crop_quad": [
        [
          11.559963226318358,
          3.598575592041015
        ],
        [
          1185.4285889897849,
          9.422903061521222
        ],
        [
          1185.759399282995,
          756.9421386655698
        ],
        [
          9.615039825346546,
          754.3733520866444
        ]
      ],
      "document_score": 0.9992,
      "crop_basis": "document",
      "association_basis": null,
      "recognition_retry": null,
      "crop_jpeg_base64": "BASE64_JPEG"
    }
  ],
  "timed_out": false,
  "processing_ms": 125.5,
  "engine_version": "0.1.6"
}

Dokumentobjekt: alle öffentlichen Felder

Die ausgelesenen Felder

Prüfziffern richtig interpretieren

{"expected":"6","actual":"6","valid":true,"applicable":true}

expected ist die berechnete, actual die gelesene Prüfziffer; beide dürfen null sein. Nur applicable=true und valid=true bedeuten eine bestandene anwendbare Prüfung. Fehlende oder nicht anwendbare Prüfungen gelten nicht automatisch als bestanden. Prüfungsnamen: document_number, date_of_birth, date_of_expiry, optional_data und composite.

Hinweise und mehrere Dokumente behandeln.

Jeder Kandidat enthält seine Diagnosen in errors. Prüfen Sie zusätzlich checks, corrections und gegebenenfalls recognition_retry. Ein Status recognized ersetzt diese Prüfung nicht.

Dokumentdiagnosen

Der aktuelle Kern kann folgende Diagnosegruppen ausgeben. Zusätzlich stehen fehlgeschlagene Prüfziffern als checksum_<name> in errors. Erhalten Sie unbekannte zukünftige Codes; behandeln Sie sie als prüfbedürftig statt als Erfolg.

Mehrere Kandidaten bleiben getrennt.

documents enthält alle Kandidaten, auch solche mit uncertain oder no_mrz. Die API wählt daraus kein einziges flaches Ergebnis und vermischt keine Felder. Wenn Ihre Anwendung genau ein Dokument benötigt, prüfen Sie die Anzahl und die Kandidaten ausdrücklich. Bei Mehrdeutigkeit ein separates Dokumentbild anfordern oder eine manuelle Auswahl vorsehen. documents: [] bedeutet, dass kein Kandidat gefunden wurde.

HTTP-Fehler und konkrete nächste Schritte.

Anfrage- und Dienstfehler verwenden HTTP 4xx/5xx. Die Tabelle beschreibt die aktuellen Engine-Mappings einschließlich gemeinsamer Decoderdiagnosen. Nicht jeder Diagnosecode ist mit jedem Format erreichbar.

Fehlerformate unterscheiden

{"error":"invalid_base64"}

{"error":"processing_timeout","timed_out":true,"documents":[]}

Proxyfehler können ein einfaches Objekt wie {"error":"request_failed"} liefern. Eine unbekannte URL kann HTTP 404 mit Text statt JSON zurückgeben. Prüfen Sie daher immer Status und Content-Type, bevor Sie das Erfolgsmodell lesen. Neue Diagnosecodes defensiv behandeln.

Ein verlässlicher Ablauf für Ihre Anwendung.

1. HTTP-Antwort prüfen

   4xx: Eingabe oder Zugang korrigieren. 503: Retry-After beachten. 500/502/504: begrenzt mit Pause wiederholen. Netzwerkfehler und nicht-JSON-Antworten separat abfangen.

2. Verarbeitungsergebnis prüfen

   timed_out=false, gewünschter Kandidat vorhanden und documents[].status=recognized. Anzahl und Zuordnung der Kandidaten ausdrücklich prüfen. Teilfelder in negativen Ergebnissen nicht übernehmen.

3. Hinweise und Daten validieren

   Prüfziffern, Korrekturen, Rohdaten und Zuordnungsbelege bewerten. Pflichtfelder, Datumsannahmen, Alter und Gültigkeit nach Ihren Geschäftsregeln prüfen. Fehlende Felder nicht ergänzen oder erraten.

4. Übernehmen oder prüfen lassen

   Nur nach Ihren Annahmekriterien übernehmen. Unsichere, mehrdeutige oder unvollständige Ergebnisse an einen sichtbaren Prüfprozess geben. Dokumente nie anhand gültiger Prüfziffern als echt erklären.

Dekodieren Sie Bildausgaben als Base64 und prüfen Sie JPEG-Format und Größe vor einer Weiterverarbeitung. Eine Data-URL für die Anzeige erzeugen Sie erst in Ihrer eigenen Oberfläche. Protokollieren Sie technische Status-/Fehlercodes statt Dokumentbildern, vollständigen Antworten oder API-Schlüsseln.

Formate und Grenzen

KI-Bildaufbereitung ist eine gesonderte Erweiterung auf Anfrage. Diese Schnittstelle bietet keinen Standardparameter, der „Enhance Output Image with AI“ aktiviert.

Öffentliche Website-Demo

Einwilligung und Trainingsspeicherung in der Demo

Datei- und Beispielauswahl, Ablegen oder Kameraaktivierung starten die Übertragung nach dem sichtbaren Speicherhinweis. Die Oberfläche sendet X-Training-Consent: training-v3; training-v1 und training-v2 bleiben für ältere Clients akzeptiert. Der Header kennzeichnet die Hinweisversion.

Originalbilder und vollständige Ergebnisse werden verschlüsselt für 30 Tage ab Upload zu Trainingszwecken und zur Qualitätsverbesserung gespeichert und anschließend automatisch gelöscht. Eine frühere Löschung können Sie mit Ihrer Upload-ID unter info@oasisscan.de anfordern. Diese Speicherung betrifft nur die öffentliche Demo.

X-Training-Upload-ID enthält die ID einer angenommenen Speicherung. Auch bei einem Erkennungsfehler kann der Upload bereits gespeichert sein; wiederholen Sie ihn dann nicht automatisch. Abbrechen oder Zurücksetzen löscht gespeicherte Daten nicht.

Demo-spezifisch: 422 training_consent_required bedeutet, dass der Hinweismarker fehlt oder nicht unterstützt wird; 503 training_storage_unavailable bedeutet, dass die sichere Speicherung momentan nicht möglich ist. Es wird dann nicht stillschweigend ohne Speicherung verarbeitet. 503 service_busy ohne Upload-ID kann nach Retry-After begrenzt wiederholt werden. Der Browser-Batch nutzt bis zu vier parallele Einbild-Requests und zeigt Status und Upload-ID pro Datei. Details: Datenschutz.