Zum Hauptinhalt springen
POST
Python
Senden Sie ein Dokument zusammen mit der Liste der Felder, die daraus gelesen werden sollen. Didit wendet sein Standard-Extraktionsmodell auf die Datei an, gibt jedes Feld typisiert zurück (text, number oder date als YYYY-MM-DD), erkennt und dekodiert unterstützte QR-Codes und Barcodes, prüft die Datei auf Manipulationen und vergleicht optional den Namen auf dem Dokument mit der erwarteten Person oder dem erwarteten Unternehmen. Verwenden Sie dies für Kapitalnachweise, Gehaltsabrechnungen, Kontoauszüge, Steuerdokumente, Rechnungen oder jedes Dokument, das keiner festen Vorlage entspricht. Dies ist die Server-zu-Server-Version des gehosteten Document AI-Schritts. Die Anfrage ist multipart/form-data: Die Datei wird im Feld document übergeben, die Felddefinitionen im Feld fields als eine JSON-kodierte Zeichenfolge mit einem Array.

Felder zur Extraktion definieren

fields ist ein JSON-Array mit 1 bis 30 Elementen, das als einzelner String gesendet wird. Jedes Element hat einen key (Kleinbuchstaben, Ziffern und Unterstriche, innerhalb der Anfrage eindeutig), einen menschenlesbaren name, eine instruction, die dem Modell sagt, wonach es suchen soll, einen type (text, number oder date) sowie zwei Flags: required und is_full_name.
Bei einer Multipart-Anfrage ist das gesamte Array ein einziger Formularwert:
Die Antwort gibt die normalisierten fields zurück und liefert extracted_data, geschlüsselt nach Ihren key-Werten, mit null für alles, was das Modell nicht finden konnte. name, instruction und type sind bei jedem Element optional (type ist standardmäßig text); key ist erforderlich. Wenn Sie fields als Formularschlüssel im Klammerformat (fields[0][key]=...) senden oder als etwas anderes als ein JSON-Array, gibt die Anfrage 400 zurück, bevor eine Extraktion läuft, sodass nichts abgerechnet wird.

QR-Codes und Barcodes

Jede erfolgreiche Antwort enthält document_ai.detected_codes. Jedes Element enthält: Das Array umfasst jede verarbeitete Seite eines PDFs und ist leer, wenn kein unterstützter Code gefunden wird. Didit errät niemals einen Payload: Beschädigte QR-Codes können mit ihrer Position und parsed_payload: null zurückgegeben werden, und Fehler bei der Codeerkennung lassen die Document-AI-Anfrage nicht fehlschlagen.

Namensabgleich

Markieren Sie höchstens ein Feld mit is_full_name: true und senden Sie, wem das Dokument Ihrer Erwartung nach gehört: Senden Sie entweder die eine oder die andere Gruppe, nicht beide. Wenn ein Name extrahiert wird und ein erwarteter Name vorhanden ist, enthält die Antwort name_match_score (0 bis 100) und name_on_document. Liegt der Wert unter document_ai_name_match_score_threshold (Standard 80), löst dies die Warnung DOCUMENT_AI_NAME_MISMATCH aus und wendet document_ai_name_mismatch_action an. Wenn kein Feld als is_full_name markiert ist, greift Didit auf das erste Textfeld zurück, dessen Schlüssel nach einem Namen aussieht (name, holder, full_name, account_holder). Markieren Sie das Feld ausdrücklich, wenn Sie steuern möchten, welcher Wert verglichen wird. Wenn auf dem Dokument kein Namenswert gefunden wird oder kein erwarteter Name gesendet wird, entfällt die Namensprüfung und name_match_score ist null.

Risiken und Aktionen

Jedes der folgenden Risiken ist einem Aktionsparameter zugeordnet, den Sie pro Anfrage festlegen können: DECLINE, REVIEW oder NO_ACTION. Die strengste ausgelöste Aktion bestimmt document_ai.status (Declined > In Review > Approved), und jedes ausgelöste Risiko wird in document_ai.warnings aufgeführt. Die Standardwerte entsprechen dem gehosteten Workflow-Schritt. Wie jedes Risiko erkannt wird, erfahren Sie unter Document AI-Regeln und Warnungen.

Dateien, Speicherung und Abrechnung

  • Akzeptierte Dateien: PDF (mehrseitig unterstützt), JPG, JPEG, PNG, TIFF, WebP oder ein ZIP-Archiv mit dem Dokument, bis zu 30 MB. Verschlüsselte PDFs geben 400 zurück; laden Sie stattdessen ein entschlüsseltes PDF oder ein Foto hoch.
  • save_api_request (Standard true): Die Anfrage, die extrahierten Felder und die erkannten Codes erscheinen in der Business Console unter Manuelle Prüfungen, wo Ihr Team sie prüfen kann. Setzen Sie den Wert auf false, um das Speichern zu überspringen.
  • vendor_data und metadata werden unverändert in der Antwort zurückgegeben, damit Sie das Ergebnis mit Ihren eigenen Datensätzen verknüpfen können.
  • Preis: $0.20 pro Dokument, abgerechnet, wenn das Dokument verarbeitet und ein Status zurückgegeben wird. Ihr Tarifrabatt gilt. Siehe Preise.
Soll der Nutzer das Dokument selbst hochladen, bis zu 3 Dokumente in einem Ablauf erfassen, den Upload-Bildschirm automatisch übersetzen lassen oder extrahierte Felder mit Ausweis- oder Fragebogendaten abgleichen? Verwenden Sie stattdessen den gehosteten Document AI-Workflow-Schritt.

Autorisierungen

x-api-key
string
header
erforderlich

Der API-Schlüssel Ihrer Anwendung, aus Entwickler -> API-Schlüssel in der Business Console. Der Primärschlüssel hat Vollzugriff. Ein benannter Schlüssel kann im Geltungsbereich eingeschränkt werden: keine, Lese- oder Schreibberechtigung pro Ressource, beschränkt auf bestimmte Workflows oder genehmigte Sitzungen, auf eine Liste von IP-Adressen und auf ein Ablaufdatum. 401 bedeutet, dass der Schlüssel falsch, widerrufen oder abgelaufen ist; 403 bedeutet, dass kein Schlüssel gesendet wurde, der Schlüssel keinen Zugriff auf diese Ressource oder Aktion hat oder die Anfrage von einer Adresse außerhalb seiner IP-Liste stammte; 404 bei einer Sitzungsroute bedeutet, dass die Sitzung außerhalb der Workflows oder Status des Schlüssels liegt. Ein Schlüssel ohne Medienzugriff erhält Bild-, Video- und PDF-URLs als null, und ein Schlüssel ohne Schreibberechtigung für Sitzungen erhält Sitzungslinks und Token als null. Siehe https://docs.didit.me/console/api-keys.

Body

multipart/form-data
document
file
erforderlich

Das zu lesende Dokument. Zulässige Dateiendungen: tiff, jpg, jpeg, png, pdf, webp, zip. Maximale Upload-Größe: 30 MB (größere Dateien werden mit 400 abgelehnt). Mehrseitige PDFs werden unterstützt (rechnen Sie mit höherer Latenz); verschlüsselte PDFs werden mit 400 abgelehnt. Bilder werden vor der Verarbeitung automatisch komprimiert.

fields
string
erforderlich

Ein JSON-codierter Array-String mit 1–30 Felddefinitionen (maximal 16 KB). Jedes Element: key (erforderlich, ^[a-z0-9_]{1,64}$, eindeutig – der in extracted_data zurückgegebene Schlüssel), name (≤100 Zeichen, in Nachrichten angezeigt), instruction (≤500 Zeichen, was das Modell lesen soll), type (text Standard | number | date), required (Boolean, Standard false), is_full_name (Boolean, Standard false, maximal eines pro Anfrage). Formular-Arrays in Klammerschreibweise, ungültiges JSON, doppelte Schlüssel oder mehr als ein is_full_name geben vor jeglicher Verarbeitung oder Abrechnung 400 zurück.

Beispiel:

"[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]"

expected_first_name
string

Vorname, der mit dem Namensfeld des Dokuments abgeglichen werden soll (Fuzzy-Match, transliterationssensitiv). Zusammen mit expected_last_name verwenden; kann nicht mit expected_company_name kombiniert werden.

Beispiel:

"Sophia"

expected_last_name
string

Mit dem Namensfeld des Dokuments abzugleichender Nachname, der zusammen mit expected_first_name für name_match_score herangezogen wird.

Beispiel:

"Martinez"

expected_company_name
string

Unternehmensname zum Abgleich mit dem Namensfeld des Dokuments (für Unternehmensdokumente). Kann nicht mit expected_first_name / expected_last_name kombiniert werden (absichtlich kein Beispielwert – das generierte Anfragebeispiel verwendet die Personenfelder; ersetzen Sie diese durch diesen Wert bei der Verifizierung eines Unternehmensdokuments).

expected_company_country
string

Optionaler ISO 3166-1 alpha-2 Ländercode (zwei ASCII-Buchstaben, z. B. FR), der die Normalisierung von Firmennamen für expected_company_name anpasst. Wird nur mit expected_company_name verwendet.

document_ai_name_match_score_threshold
integer
Standard:80

Minimaler name_match_score (0–100), ab dem der Name als übereinstimmend gilt. Ein niedrigerer Wert fügt DOCUMENT_AI_NAME_MISMATCH hinzu, gesteuert durch document_ai_name_mismatch_action.

Erforderlicher Bereich: 0 <= x <= 100
Beispiel:

80

document_ai_unreadable_document_action
enum<string>
Standard:REVIEW

Was zu tun ist, wenn kein Feld aus dem Dokument gelesen werden konnte (DOCUMENT_AI_UNREADABLE_DOCUMENT).

Verfügbare Optionen:
DECLINE,
REVIEW,
NO_ACTION
document_ai_missing_required_fields_action
enum<string>
Standard:REVIEW

Was zu tun ist, wenn mindestens ein required-Feld nicht gelesen werden konnte (DOCUMENT_AI_MISSING_REQUIRED_FIELDS; additional_data.missing_fields listet diese auf).

Verfügbare Optionen:
DECLINE,
REVIEW,
NO_ACTION
document_ai_document_tampering_action
enum<string>
Standard:DECLINE

Was zu tun ist, wenn die PDF-/EXIF-Forensik eine Manipulation vermutet — nach digitaler Signatur geändert, bekannter PDF-Editor, Overlay-Text-Manipulation, verdächtiger Re-Export, Bildanomalien (DOCUMENT_AI_SUSPECTED_MANIPULATION).

Verfügbare Optionen:
DECLINE,
REVIEW,
NO_ACTION
document_ai_name_mismatch_action
enum<string>
Standard:NO_ACTION

Was zu tun ist, wenn name_match_score unter dem Schwellenwert liegt (DOCUMENT_AI_NAME_MISMATCH).

Verfügbare Optionen:
DECLINE,
REVIEW,
NO_ACTION
document_ai_unsupported_file_action
enum<string>
Standard:REVIEW

Was zu tun ist, wenn der Upload leer oder keine verarbeitbare Datei ist (DOCUMENT_AI_UNSUPPORTED_FILE).

Verfügbare Optionen:
DECLINE,
REVIEW,
NO_ACTION
save_api_request
boolean
Standard:true

Wenn true (Standard), wird der Aufruf als Sitzung vom Typ API persistent gespeichert — sichtbar in der Business Console, abrufbar über GET /v3/session/{sessionId}/decision/ unter Verwendung der zurückgegebenen request_id, wobei das hochgeladene Dokument, die extrahierten Werte, die Felddefinitionen und der Namensabgleich-Snapshot gespeichert werden. Wenn false, wird nichts gespeichert und request_id ist eine flüchtige UUID, die nur der Antwortkorrelation dient; der Aufruf wird dennoch abgerechnet.

Beispiel:

true

vendor_data
string

Optionale opake Zeichenfolge (Ihre interne Benutzer-ID, E-Mail, UUID…), die in der gespeicherten Sitzung hinterlegt und in der Antwort zurückgegeben wird. Verwenden Sie sie, um API-Aufrufe mit Ihren eigenen Datensätzen abzugleichen und Sitzungen später zu filtern.

Beispiel:

"user-123"

metadata
object

Optionales JSON-Objekt, das mit der Sitzung gespeichert (wenn save_api_request=true) und in der Antwort zurückgegeben wird. Senden Sie es bei Multipart-Anfragen als JSON-codiertes String-Feld (z. B. metadata={"flow":"onboarding"}) – es wird in ein Objekt geparst.

Beispiel:

Antwort

Dokument verarbeitet. document_ai.status ist Approved, Declined oder In Review; jedes erkannte Problem wird einzeln in document_ai.warnings aufgeführt. Ein problematisches Dokument gibt dennoch 200 zurück – prüfen Sie den Body, nicht nur den HTTP-Code. Wenn save_api_request=true, ist request_id die persistierte Sitzungs-ID.

request_id
string<uuid>

Beibehaltene Sitzungs-ID, wenn save_api_request=true (verwendbar mit GET /v3/session/{sessionId}/decision/); andernfalls eine vorübergehende Korrelations-UUID.

document_ai
object
vendor_data
string | null

Rückgabe der von Ihnen gesendeten vendor_data oder null.

metadata
object | null

Rückgabe des von Ihnen gesendeten metadata-Objekts oder null.

created_at
string<date-time>

Wann die Anfrage verarbeitet wurde (UTC, ISO 8601).

Zuletzt geändert am 7. November 2026