MRZ API

Ein Dokumentbild senden. Strukturierte Daten als JSON erhalten.

POST/v1/mrz

Basis-URL und Schlüssel erhalten Sie nach Freischaltung. Auf dieser Website ist die Kunden-API nicht freigeschaltet.

Vollständige Referenz ↗

Zugang

Sie erhalten eine Basis-URL und einen API-Schlüssel von uns. Hinterlegen Sie beides als Umgebungsvariablen auf Ihrem Server. Den Schlüssel nicht in Browsercode, Apps oder öffentliche Repositories übernehmen.

VariableZweck
MRZ_BASE_URLIhre freigeschaltete Basis-URL
MRZ_API_KEYIhr geheimer API-Schlüssel

Zugang anfragen · Authentifizierung im Detail

Anfrage senden

Senden Sie POST /v1/mrz mit Authorization: Bearer … und Content-Type: application/json. Das JSON enthält genau image_base64 mit den Base64-kodierten Bildbytes, ohne Data-URI-Präfix.

Die Beispiele verwenden include_crop=false und liefern zunächst nur Daten. Für einen verfügbaren Dokumentausschnitt setzen Sie include_crop=true oder lassen den Parameter weg. Die Bildbytes stehen dann in crop_jpeg_base64; ist kein Ausschnitt verfügbar, bleibt der Wert null.

Bash 3.2+, cURL und Python 3.

mrz.sh
#!/usr/bin/env bash
set -euo pipefail
: "${MRZ_BASE_URL:?Set MRZ_BASE_URL}"
: "${MRZ_API_KEY:?Set MRZ_API_KEY}"
timeout="${MRZ_TIMEOUT_SECONDS:-95}"
if ! python3 -c 'import math, sys; n = float(sys.argv[1]); assert math.isfinite(n) and n > 0' "$timeout" 2>/dev/null; then
  printf '%s\n' 'Set a positive MRZ_TIMEOUT_SECONDS.' >&2
  exit 1
fi

# Keep the request and response in memory, not in temporary document files.
if ! wire="$(python3 -c '
import base64, json
from pathlib import Path
print(json.dumps({"image_base64": base64.b64encode(Path("document.jpg").read_bytes()).decode("ascii")}))
' 2>/dev/null | curl --disable --silent \
  --max-time "$timeout" --proto '=http,https' \
  --request POST "${MRZ_BASE_URL%/}/v1/mrz?include_crop=false" \
  --header "Authorization: Bearer ${MRZ_API_KEY}" \
  --header 'Content-Type: application/json' --header 'Accept: application/json' \
  --data-binary @- --write-out '\n%{http_code}')"; then
  printf '%s\n' 'MRZ request failed.' >&2
  exit 1
fi
status="${wire##*$'\n'}"
body="${wire%$'\n'*}"
case "$status" in
  2??) ;;
  *) printf 'MRZ HTTP %s.\n' "$status" >&2; exit 1 ;;
esac
printf '%s' "$body" | python3 -c '
import json, sys
try:
    result = json.load(sys.stdin, parse_constant=lambda _: (_ for _ in ()).throw(ValueError()))
except (ValueError, UnicodeError):
    sys.exit("Invalid JSON response.")
# Use result in your application; do not print document data.
print("MRZ response received.")
'

Ausführen: bash mrz.sh

Beispiel herunterladen ↓

Eingabeformate, Base64-Regeln und Größenlimits ↗

Ergebnis lesen

Die Antwort enthält documents als Liste. Jedes Dokument hat seine eigenen Felder und Prüfergebnisse. Hier ein gekürztes Beispiel; die vollständige Antwort enthält weitere Felder.

Gekürzte Antwort · HTTP 200
{
  "documents": [
    {
      "status": "recognized",
      "format": "TD3",
      "mrz": [
        "P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<",
        "L898902C36UTO7408122F1204159ZE184226B<<<<<10"
      ],
      "fields": {
        "surname": "ERIKSSON",
        "given_names": "ANNA MARIA",
        "document_number": "L898902C3"
      },
      "errors": [],
      "corrections": [],
      "crop_jpeg_base64": null
    }
  ],
  "timed_out": false
}
PrüfenBehandlung
timed_outBei true ist das Ergebnis unvollständig. Nicht automatisch übernehmen.
documentsLeer: kein Kandidat gefunden. Mehrere Einträge: getrennt prüfen und das passende Dokument eindeutig auswählen.
statusrecognized: weiter prüfen. uncertain oder no_mrz: manuelle Prüfung oder ein besseres Bild anfordern.
checks, errors, correctionsAuch bei erkannter MRZ auswerten. Fehlgeschlagene anwendbare Prüfziffern und korrigierte oder unsichere Daten nicht ungeprüft importieren.

Datumsfelder bleiben im MRZ-Format YYMMDD; ein Jahrhundert wird nicht geraten. Prüfziffern belegen weder Dokumentechtheit noch Identität.

Alle Antwortfelder und Ergebniszustände ↗

Fehler behandeln

Prüfen Sie den HTTP-Status, bevor Sie die Antwort als Ergebnis verwenden. HTTP 200 allein bedeutet noch keine erfolgreiche Erkennung.

HTTPNächster Schritt
401API-Schlüssel prüfen. Nicht unverändert wiederholen.
404Basis-URL und Freischaltung prüfen; die Website-Adresse ist kein aktiver Enterprise-Zugang.
400 / 405 / 408 / 413 / 422Methode, Eingabeformat, Bildgröße oder Upload-Verbindung korrigieren.
503Retry-After beachten und mit Pause begrenzt erneut versuchen.
500 / 502 / 504Vorübergehender Dienstfehler möglich. Höchstens begrenzt wiederholen; bei Wiederholung Kontakt aufnehmen.

Fehler können ein error- oder detail-Feld enthalten. Auch Netzwerkfehler und nicht-JSON-Antworten abfangen. Keine Dokumentdaten oder API-Schlüssel in Fehlerprotokolle schreiben.

Alle Fehlercodes und Hinweise zu Wiederholungen ↗