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.
| Variable | Zweck |
|---|---|
MRZ_BASE_URL | Ihre freigeschaltete Basis-URL |
MRZ_API_KEY | Ihr geheimer API-Schlüssel |
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.
#!/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
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.
{
"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üfen | Behandlung |
|---|---|
timed_out | Bei true ist das Ergebnis unvollständig. Nicht automatisch übernehmen. |
documents | Leer: kein Kandidat gefunden. Mehrere Einträge: getrennt prüfen und das passende Dokument eindeutig auswählen. |
status | recognized: weiter prüfen. uncertain oder no_mrz: manuelle Prüfung oder ein besseres Bild anfordern. |
checks, errors, corrections | Auch 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.
Fehler behandeln
Prüfen Sie den HTTP-Status, bevor Sie die Antwort als Ergebnis verwenden. HTTP 200 allein bedeutet noch keine erfolgreiche Erkennung.
| HTTP | Nächster Schritt |
|---|---|
| 401 | API-Schlüssel prüfen. Nicht unverändert wiederholen. |
| 404 | Basis-URL und Freischaltung prüfen; die Website-Adresse ist kein aktiver Enterprise-Zugang. |
| 400 / 405 / 408 / 413 / 422 | Methode, Eingabeformat, Bildgröße oder Upload-Verbindung korrigieren. |
| 503 | Retry-After beachten und mit Pause begrenzt erneut versuchen. |
| 500 / 502 / 504 | Vorü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.