IDPARSE
Kostenlos testen

Ergebnisse und Abrechnung

Ergebnisfelder

Eine Datei kann mehrere Dokumente enthalten, zum Beispiel zwei Reisepässe, die auf einer Seite eingescannt wurden. Deshalb beschreibt jede 200-Antwort von POST /v1/extract die Datei und listet die Dokumente auf, die darin gefunden wurden.

Die Datei:

Feld Typ Beschreibung
success boolean true, wenn mindestens ein Dokument gelesen wurde und alle drei Prüfziffern dieses Dokuments gestimmt haben
documents Array von Objekten Jedes gefundene Dokument, in der Reihenfolge der Seiten und von oben nach unten. Das Array kann leer sein ([])
document_count integer Die Zahl der Einträge in documents
verified_document_count integer Wie viele davon "success": true haben
processing_complete boolean false, wenn eine Grenze die Arbeit beendet hat, bevor jeder Teil der Datei gelesen wurde, siehe Mehrere Dokumente in einer Datei
truncation_reason string oder null null, wenn processing_complete den Wert true hat. Sonst document_limit, page_limit oder time_budget
failure_reason string oder null null, wenn success den Wert true hat. Sonst einer der zehn festen Texte unter Fehlergründe
notes Array von Strings Kurze technische Anmerkungen zur Datei, zum Beispiel welche Leseverfahren versucht wurden. Anmerkungen enthalten nie Dokumentdaten
duration_ms integer Die Verarbeitungszeit in Millisekunden
service_version string Die Version des Verarbeitungsdienstes

Jeder Eintrag von documents:

Feld Typ Beschreibung
success boolean true nur dann, wenn die MRZ (maschinenlesbare Zone, die Zeilen aus Buchstaben, Ziffern und <-Zeichen am unteren Rand des Dokuments) dieses Dokuments gelesen wurde und alle drei Prüfziffern gestimmt haben
document_type string oder null Das gefundene MRZ-Format: TD3 (Reisepass), TD1 oder TD2 (Ausweiskarte), MRV-A oder MRV-B (Visum). null, wenn kein Format erkannt wurde
fields object Die extrahierten Daten, siehe die nächste Tabelle. Das Objekt kann leer sein ({})
check_digits_valid object Das Ergebnis jeder Prüfziffer, siehe Prüfziffern. Das Objekt kann leer sein ({})
checksum_protected object Für jedes der acht Felder, ob überhaupt eine Prüfziffer es abdeckt. Es ist für jedes Dokument gleich
failure_reason string oder null null bei einem Erfolg. Sonst einer der festen Texte unter Fehlergründe
notes Array von Strings Kurze technische Anmerkungen zu diesem Lesevorgang, zum Beispiel birth date century inferred. Anmerkungen enthalten nie Dokumentdaten
page integer Die Seite der Datei, ab 1 gezählt. Eine Bilddatei hat eine Seite
region object oder null Wo die MRZ gefunden wurde, als Anteile der Seite: x, y, width und height, jeweils von 0 bis 1. null, wenn die Position nicht bekannt ist

Das Objekt fields:

Feld Format Durch eine Prüfziffer geschützt
surname Text in Großbuchstaben Nein
given_names Text in Großbuchstaben, Namen durch ein Leerzeichen getrennt Nein
birth_date YYYY-MM-DD Ja
sex M, F, X oder null. Das MRZ-Füllzeichen < wird als X (nicht angegeben) zurückgegeben Nein
nationality Ländercode aus der MRZ. Das Füllzeichen < wird entfernt, der Code kann also kürzer als drei Buchstaben sein, zum Beispiel D Nein
document_number Text Ja
expiry_date YYYY-MM-DD Ja
issuing_country Ländercode aus der MRZ. Das Füllzeichen < wird entfernt, der Code kann also kürzer als drei Buchstaben sein, zum Beispiel D Nein

In einem Dokument mit "success": true sind alle acht Schlüssel vorhanden. Die drei geschützten Felder enthalten immer einen Wert. Die fünf Felder ohne Prüfziffer (surname, given_names, sex, nationality, issuing_country) können null sein, wenn sie nicht gelesen werden konnten.

Hinweis

Die MRZ speichert ein Jahr nur mit zwei Ziffern. Die Engine wählt das Jahrhundert und teilt Ihnen das in den notes des Dokuments mit, zum Beispiel mit birth date century inferred.

Mehrere Dokumente in einer Datei

Eine Datei kann mehrere Dokumente enthalten: zum Beispiel die Reisepässe von zwei Personen auf einer eingescannten Seite, oder einen Reisepass auf jeder Seite eines PDF. IDParse gibt jedes gefundene Dokument zurück, bis zu fünf pro Datei.

  • Prüfen Sie success von jedem Dokument. Das success der Datei sagt Ihnen nur, dass mindestens ein Dokument geprüft wurde.
  • Eine Datei kann ein geprüftes Dokument und ein Dokument enthalten, das nicht geprüft werden konnte. Beide werden aufgelistet, und die Datei zählt als Erfolg.
  • Dieselbe Dokumentnummer auf zwei verschiedenen Seiten wird zweimal aufgelistet. IDParse kann nicht wissen, ob es dasselbe physische Dokument ist.
  • Eine PDF-Seite, die sich nicht öffnen lässt, wird übersprungen, und die notes der Datei sagen das, zum Beispiel page 2 could not be rendered. Die anderen Seiten werden trotzdem gelesen. Bei einem seltenen PDF, dessen Seitenzahl sich nicht lesen lässt, beendet eine solche Seite stattdessen das Lesen, und die weiteren Seiten werden nicht durchsucht.
  • Nachdem ein Dokument geprüft wurde, werden die weiteren Seiten eines PDF schneller gelesen. Ein zweites, sehr schwer lesbares Dokument kann dort dann übersehen werden, auch wenn processing_complete den Wert true hat. Senden Sie solche Dokumente besser einzeln.

Wenn processing_complete den Wert false hat, hat eine Grenze die Arbeit früher beendet. Die bis dahin gefundenen Dokumente werden trotzdem zurückgegeben und sind richtig. truncation_reason nennt die Grenze:

truncation_reason Bedeutung
document_limit Die Datei enthält mehr Dokumente als die Grenze von fünf pro Datei
page_limit Das PDF hat mehr Seiten als die Seitengrenze
time_budget Die Verarbeitungszeit war zu Ende, bevor jeder Teil der Datei gelesen wurde
Hinweis

Die besten Ergebnisse erhalten Sie mit einem Dokument pro Datei. Mehrere Dokumente in einer Datei funktionieren, aber jedes bekommt weniger von der Verarbeitungszeit.

Prüfziffern

Eine Prüfziffer ist eine Kontrollzahl, die in der MRZ aufgedruckt ist. Sie wird aus den Zeichen eines Feldes berechnet. Nach dem Lesen berechnet die Engine die Zahl erneut und vergleicht sie mit der gedruckten Zahl. Prüfziffern erkennen viele Lesefehler, garantieren aber nicht, dass die extrahierten Werte richtig sind.

Prüfziffern schützen nur drei Felder: document_number, birth_date und expiry_date. Das Objekt check_digits_valid enthält für jedes dieser Felder ein Kennzeichen (true oder false). Ein Kennzeichen ist nur dann true, wenn das Feld einen brauchbaren Wert enthält, seine eigene Prüfziffer stimmt und keine kombinierte Prüfziffer, die dieselbe Zeile abdeckt, fehlschlägt. In einem Teilergebnis ist ein Kennzeichen außerdem false, wenn zwei Lesungen derselben Seite unterschiedliche geprüfte Werte für das Feld ergeben haben.

Was Prüfziffern leisten:

  • Sie erkennen viele Lesefehler in den drei geschützten Feldern, zum Beispiel eine 0, die als O gelesen wurde.

Was Prüfziffern nicht leisten:

  • Sie beweisen nicht, dass ein Dokument echt ist. Ein gefälschtes Dokument kann richtige Prüfziffern tragen.
  • Sie beweisen nicht, dass das Dokument der Person gehört, die es vorlegt.
  • Sie schützen nicht die Namen, das Geschlecht, die Staatsangehörigkeit oder den Ausstellerstaat. Diese Felder können einen Lesefehler enthalten, auch wenn success den Wert true hat.

Ein zweiter, unabhängiger Leser kann den Namen prüfen. Die notes des Dokuments sagen dann readers agree on the name (beide Leser haben denselben Namen gelesen) oder name not checked by a second reader (keine zweite Lesung war möglich). Beides sind Hinweise, keine Prüfziffern. Wenn die beiden Leser verschiedene Namen lesen, ist das Dokument nicht geprüft: sein failure_reason ist mrz check digits passed but two readers read different names, die Namen werden zurückgehalten, und die geschützten Felder bleiben als Teilergebnis erhalten.

Wichtig

IDParse ist ein Dienst zur Datenextraktion. Er liest, was in der MRZ gedruckt ist. Entscheidungen über eine Person oder über die Gültigkeit eines Dokuments bleiben bei Ihnen.

Fehlergründe

Wenn das success der Datei den Wert false hat, enthält ihr failure_reason genau einen dieser zehn Texte. Ein Dokument, das nicht geprüft werden konnte, trägt einen davon auch in seinem eigenen failure_reason. Die Texte sind fest, Sie können sie also in Ihrem Code vergleichen. Eine Datei ohne geprüftes Dokument ist kostenlos.

failure_reason Bedeutung Was Sie tun können
no machine readable zone found In der Datei wurde keine MRZ gefunden Achten Sie darauf, dass die ganze MRZ sichtbar, scharf und gut beleuchtet ist. Prüfen Sie, ob das Dokument überhaupt eine MRZ hat
mrz found but check digits failed Eine MRZ wurde gefunden, aber mindestens eine Prüfziffer hat nicht gestimmt. Das Leseergebnis ist nicht verlässlich Senden Sie ein besseres Bild: höhere Auflösung, keine Spiegelung, keine Unschärfe, keine Finger über der MRZ. Ein Teilergebnis ist möglich
mrz check digits passed but the name zone could not be read Die geschützten Felder wurden gelesen, aber der Namensteil der MRZ war nicht lesbar Senden Sie ein schärferes Bild der ganzen MRZ. Ein Teilergebnis ist möglich
mrz check digits passed but two readers read different names Die geschützten Felder haben ihre Prüfziffern bestanden, aber zwei unabhängige Leser haben den Namen unterschiedlich gelesen, deshalb werden die Namen zurückgehalten Senden Sie ein schärferes Bild der ganzen MRZ, oder lassen Sie eine Person den Namen lesen. Ein Teilergebnis ist möglich
ambiguous mrz candidates Es wurden zwei verschiedene Lesungen derselben MRZ gefunden, und die Engine konnte sich nicht entscheiden Senden Sie ein schärferes Bild dieses Dokuments
unrecognised file type Die Datei hat keinen der unterstützten Dateitypen Senden Sie eine Datei im Format JPEG, PNG, PDF, TIFF, BMP, WebP oder HEIF/HEIC
image could not be decoded Die Bilddatei ist beschädigt oder unvollständig Exportieren oder speichern Sie das Bild erneut und senden Sie die neue Datei
image exceeds the pixel limit Das Bild hat zu viele Pixel Verkleinern Sie das Bild und senden Sie es erneut
pdf could not be rendered Die PDF-Datei konnte nicht geöffnet werden, zum Beispiel weil sie beschädigt oder durch ein Passwort geschützt ist Exportieren Sie die PDF-Datei erneut ohne Schutz, oder senden Sie die Seite als Bild
no ocr engine available Die Texterkennung (OCR, optische Zeichenerkennung) ist auf unserer Seite nicht bereit. Das ist eine vorübergehende Störung des Dienstes, kein Problem Ihrer Datei Senden Sie dieselbe Datei später erneut. Wenn es wieder passiert, wenden Sie sich an den Support

Teilergebnisse

Ein Teilergebnis ist ein Dokument mit "success": false, in dem einige fields gefüllt sind. Es kann bei Fehlergründen wie mrz found but check digits failed, mrz check digits passed but the name zone could not be read oder mrz check digits passed but two readers read different names vorkommen. Ein Teilergebnis kann allein in der Datei stehen oder neben geprüften Dokumenten.

Sie erkennen ein Teilergebnis an seinem Array notes. Es enthält genau den Text partial read: trust only fields whose check digit passed. Ein geschütztes Feld, dem nicht vertraut wird, wird als null zurückgegeben. Eine Lesung, in der kein Feld geprüft werden konnte, wird gar nicht zurückgegeben.

Regeln für ein Teilergebnis:

  1. Vertrauen Sie einem geschützten Feld (document_number, birth_date, expiry_date) nur dann, wenn sein Eintrag in check_digits_valid den Wert true hat.
  2. Behandeln Sie jedes andere gefüllte Feld nur als Hinweis. Zeigen Sie es einer Person zur Prüfung, oder bitten Sie um ein besseres Bild.
  3. Ein fehlender Schlüssel in check_digits_valid bedeutet "nicht geprüft". Behandeln Sie ihn wie false.

Eine Datei, die nur Teilergebnisse enthält, ist kostenlos. Ein Beispiel finden Sie unter Endpunkte.

Was berechnet wird

Nur ein validierter Erfolg wird berechnet: HTTP 200 mit "success": true. Eine Datei verbraucht einen Ihrer enthaltenen Scans, egal wie viele Dokumente sie enthält.

Antwort Berechnet
200 mit "success": true, ein oder mehrere Dokumente Ja, ein Scan
200 mit "success": true und "processing_complete": false Ja, ein Scan
200 mit "success": false (nicht lesbar oder Teilergebnis) Nein
Jeder 4xx-Fehler (zum Beispiel 401, 413, 422, 429) Nein
Jeder 5xx-Fehler (zum Beispiel 502, 503, 504) Nein
GET /v1/quota Nein, nie
Wichtig

Es gibt keinen Schutz vor Duplikaten. Wenn Sie dieselbe Datei zweimal senden und beide Antworten ein Erfolg sind, werden zwei Scans berechnet. Speichern Sie das Ergebnis eines Erfolgs auf Ihrer Seite, statt die Datei erneut zu senden.

Wann Sie wiederholen sollten

  • Wiederholen Sie nach 503 (engine_busy, engine_unavailable, service_unavailable), 504 (engine_timeout) und 502 (bad_engine_result). Diese Anfragen wurden nicht berechnet. Wenn die Antwort einen Retry-After-Header hat, warten Sie mindestens diese Zahl an Sekunden.
  • Wiederholen Sie nach 429 rate_limited. Warten Sie zuerst die Zahl an Sekunden aus Retry-After.
  • Wiederholen Sie nicht schnell nach 429 quota_exhausted. Hier ist Retry-After die Zeit bis zum nächsten Kalendermonat.
  • Senden Sie dieselbe Datei später erneut nach 200 mit "success": false und dem Fehlergrund no ocr engine available. Das ist eine vorübergehende Störung des Dienstes, kein Problem Ihrer Datei.
  • Senden Sie dieselbe Datei nicht erneut nach jedem anderen 200 mit "success": false. Diese Antworten brauchen ein besseres Bild, keinen neuen Versuch.
  • Senden Sie nicht die ganze Datei erneut nach 200 mit "processing_complete": false. Behalten Sie die erhaltenen Dokumente, und senden Sie die Seiten oder Dokumente, die nicht gelesen wurden, als eigene Dateien.
  • Wiederholen Sie nicht nach 401, 403, 413 und 422. Korrigieren Sie zuerst den Schlüssel, das Konto oder die Datei.
  • Begrenzen Sie die Zahl der Versuche, und verlängern Sie die Wartezeit nach jedem fehlgeschlagenen Versuch.
Hinweis

Wenn Ihre Verbindung abbricht, bevor Sie eine Antwort erhalten, können Sie nicht wissen, ob der Scan berechnet wurde. Der Wert used von GET /v1/quota kann Ihnen einen Hinweis geben, aber keinen Beweis. Der Nutzungszähler kann Scans enthalten, die noch verarbeitet werden. Er kann nicht bestätigen, ob eine einzelne unterbrochene Anfrage berechnet wurde.