Saltar al contingut principal
POST
Python
Envia un document i la llista de camps que vols llegir-hi. Didit executa sobre el fitxer el model d’extracció predeterminat, retorna tots els camps amb el tipus indicat (text, number o date com a YYYY-MM-DD), detecta i descodifica els codis QR i de barres compatibles, comprova si el fitxer ha estat manipulat i, opcionalment, compara el nom que consta al document amb la persona o l’empresa que esperes. Fes-lo servir per a comprovants de fons, nòmines, extractes bancaris, documents fiscals, factures o qualsevol document que no encaixi en una plantilla fixa. Aquesta és la versió de servidor a servidor del pas de Document AI allotjat. La sol·licitud és multipart/form-data: el fitxer va a document i les definicions dels camps a fields, com una única cadena que conté una matriu JSON codificada.

Definir els camps a extreure

fields és un array JSON d’1 a 30 elements, enviat com una única cadena. Cada element té una key (lletres minúscules, dígits i guions baixos, única dins de la sol·licitud), un name llegible per a humans, una instruction que indica al model què ha de buscar, un type (text, number o date) i dos indicadors: required i is_full_name.
En una sol·licitud multipart, tota la matriu és un únic valor de formulari:
La resposta reprodueix els fields normalitzats i retorna extracted_data indexat pels valors de key que has enviat, amb null per a qualsevol cosa que el model no hagi pogut trobar. name, instruction i type són opcionals a cada element (type és text per defecte); key és obligatori. Si envies fields com a claus de formulari amb format de claudàtor (fields[0][key]=...) o com a qualsevol cosa que no sigui un array JSON, es retorna 400 abans que s’executi cap extracció, de manera que no es factura res.

Codis QR i codis de barres

Cada resposta satisfactòria inclou document_ai.detected_codes. Cada element conté: La matriu cobreix totes les pàgines processades d’un PDF i és buida quan no es troba cap codi compatible. Didit no endevina mai cap payload: els codis QR malmesos es poden retornar amb la seva ubicació i parsed_payload: null, i els errors en la detecció de codis no fan fallar la sol·licitud de Document AI.

Coincidència de noms

Marca com a màxim un camp amb is_full_name: true i envia la persona o l’empresa a qui esperes que pertanyi el document: Envia un grup o l’altre, no tots dos. Quan s’extreu un nom i hi ha un nom esperat, la resposta inclou name_match_score (de 0 a 100) i name_on_document. Una puntuació inferior a document_ai_name_match_score_threshold (predeterminat 80) activa l’advertència DOCUMENT_AI_NAME_MISMATCH i aplica document_ai_name_mismatch_action. Si cap camp no està marcat com a is_full_name, Didit utilitza el primer camp de text la clau del qual sembli un nom (name, holder, full_name, account_holder); marca el camp explícitament quan vulguis controlar quin valor es compara. Quan no es troba cap valor de nom al document, o no s’envia cap nom esperat, la comprovació del nom s’omet i name_match_score és null.

Riscos i accions

Cada risc següent correspon a un paràmetre d’acció que pots definir per sol·licitud: DECLINE, REVIEW o NO_ACTION. L’acció més estricta activada determina document_ai.status (Declined > In Review > Approved), i cada risc activat apareix a document_ai.warnings. Els valors predeterminats coincideixen amb els del pas de flux de treball allotjat; consulta Regles i advertències de Document AI per saber com es detecta cada risc.

Fitxers, desament i facturació

  • Fitxers acceptats: PDF (són compatibles els de diverses pàgines), JPG, JPEG, PNG, TIFF, WebP o un ZIP que contingui el document, de fins a 30 MB. Els PDF xifrats retornen 400; puja un PDF desxifrat o una fotografia.
  • save_api_request (predeterminat true): la sol·licitud, els camps extrets i els codis detectats apareixen a la Business Console, a Comprovacions manuals, on el teu equip els pot revisar. Defineix-lo com a false per no desar-los.
  • vendor_data i metadata es retornen sense canvis a la resposta perquè puguis vincular el resultat amb els teus propis registres.
  • Preu: $0.20 per document, facturat quan el document es processa i es retorna un estat. S’aplica el descompte del teu pla. Consulta Preus.
Necessites que l’usuari pugi el document ell mateix, que es recullin fins a 3 documents en un sol flux, que es tradueixi automàticament la pantalla de pujada o que es creuin els camps extrets amb dades d’identitat o de qüestionaris? Utilitza en lloc d’això el pas de flux de treball de Document AI allotjat.

Autoritzacions

x-api-key
string
header
requerit

La clau d'API de la teva aplicació, des de Developers -> API keys a la Business Console. La clau primària té accés complet. Una clau amb nom pot tenir l'abast limitat: cap, lectura o escriptura per recurs, limitada a determinats fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a una data de caducitat. 401 significa que la clau és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap clau, que la clau no té accés a aquest recurs o acció, o que la sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una ruta de sessió significa que la sessió està fora dels fluxos de treball o estats de la clau. Una clau sense accés a fitxers multimèdia rep els URL d'imatge, vídeo i PDF com a null, i una clau sense permís d'escriptura de sessions rep els enllaços de sessió i els tokens com a null. Consulta https://docs.didit.me/console/api-keys.

Cos

multipart/form-data
document
file
requerit

El document per llegir. Extensions permeses: tiff, jpg, jpeg, png, pdf, webp, zip. Mida màxima de pujada: 30 MB (els fitxers més grans es rebutgen amb un 400). Els PDF multipàgina són compatibles (espera una latència més alta); els PDF xifrats es rebutgen amb un 400. Les imatges es comprimeixen automàticament abans de processar-se.

fields
string
requerit

Una cadena que codifica en JSON una matriu amb 1–30 definicions de camp (màxim 16 KB). Cada element: key (obligatori, ^[a-z0-9_]{1,64}$, únic — la clau retornada a extracted_data), name (≤100 caràcters, mostrat als missatges), instruction (≤500 caràcters, el que ha de llegir el model), type (text per defecte | number | date), required (booleà, per defecte false), is_full_name (booleà, per defecte false, com a màxim un per sol·licitud). Les matrius de formulari amb claudàtors, el JSON no vàlid, les claus duplicades o més d'un is_full_name retornen 400 abans de qualsevol processament o facturació.

Exemple:

"[{\"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

Nom de pila a verificar respecte al camp del nom del document (coincidència difusa, compatible amb transliteració). Utilitza'l juntament amb expected_last_name; no es pot combinar amb expected_company_name.

Exemple:

"Sophia"

expected_last_name
string

Cognom a verificar contra el camp de nom del document, combinat amb expected_first_name per a name_match_score.

Exemple:

"Martinez"

expected_company_name
string

Nom de l'empresa a verificar respecte al camp de nom del document (per a documents d'empresa). No es pot combinar amb expected_first_name / expected_last_name (no hi ha cap valor d'exemple expressament —la mostra de sol·licitud generada utilitza els camps de persona física; canvia'ls per aquest quan verifiquis un document d'empresa).

expected_company_country
string

Codi de país ISO 3166-1 alfa-2 opcional (dues lletres ASCII, p. ex., FR) que ajusta la normalització del nom de l'empresa per a expected_company_name. Només s'utilitza amb expected_company_name.

document_ai_name_match_score_threshold
integer
predeterminat:80

Puntuació mínima de name_match_score (0–100) per considerar que el nom coincideix. Una puntuació inferior afegeix DOCUMENT_AI_NAME_MISMATCH, regit per document_ai_name_mismatch_action.

Rang requerit: 0 <= x <= 100
Exemple:

80

document_ai_unreadable_document_action
enum<string>
predeterminat:REVIEW

Què fer quan no s'ha pogut llegir cap camp del document (DOCUMENT_AI_UNREADABLE_DOCUMENT).

Opcions disponibles:
DECLINE,
REVIEW,
NO_ACTION
document_ai_missing_required_fields_action
enum<string>
predeterminat:REVIEW

Què fer quan no s'ha pogut llegir almenys un camp required (DOCUMENT_AI_MISSING_REQUIRED_FIELDS; additional_data.missing_fields els enumera).

Opcions disponibles:
DECLINE,
REVIEW,
NO_ACTION
document_ai_document_tampering_action
enum<string>
predeterminat:DECLINE

Què fer quan l'anàlisi forense de PDF/EXIF sospita de manipulació — modificat després de la signatura digital, editor de PDF conegut, manipulació de text superposat, reexportació sospitosa, anomalies en la imatge (DOCUMENT_AI_SUSPECTED_MANIPULATION).

Opcions disponibles:
DECLINE,
REVIEW,
NO_ACTION
document_ai_name_mismatch_action
enum<string>
predeterminat:NO_ACTION

Què fer quan name_match_score està per sota del llindar (DOCUMENT_AI_NAME_MISMATCH).

Opcions disponibles:
DECLINE,
REVIEW,
NO_ACTION
document_ai_unsupported_file_action
enum<string>
predeterminat:REVIEW

Què fer quan la càrrega està buida o no és un fitxer processable (DOCUMENT_AI_UNSUPPORTED_FILE).

Opcions disponibles:
DECLINE,
REVIEW,
NO_ACTION
save_api_request
boolean
predeterminat:true

Quan és true (per defecte), persisteix la crida com una sessió de tipus API — visible a la Business Console, recuperable mitjançant GET /v3/session/{sessionId}/decision/ utilitzant el request_id retornat, amb el document carregat, els valors extrets, les definicions de camps i la instantània de coincidència de noms emmagatzemats. Quan és false, no s'emmagatzema res i request_id és un UUID transitori només per a la correlació de la resposta; la crida es continua facturant.

Exemple:

true

vendor_data
string

Cadena opaca opcional (el teu ID d'usuari intern, correu electrònic, UUID…) desada a la sessió persistent i retornada a la resposta. Utilitza-la per correlacionar crides a l'API amb els teus propis registres i per filtrar sessions més endavant.

Exemple:

"user-123"

metadata
object

Objecte JSON opcional emmagatzemat amb la sessió (quan save_api_request=true) i retornat a la resposta. En sol·licituds multipart, envia'l com a camp de cadena codificat en JSON (p. ex., metadata={"flow":"onboarding"}); s'analitza com un objecte.

Exemple:

Resposta

Document processat. document_ai.status és Approved, Declined o In Review; cada problema detectat es detalla a document_ai.warnings. Un document problemàtic continua retornant 200; inspecciona el cos, no només el codi HTTP. Quan save_api_request=true, request_id és l'id de sessió persistit.

request_id
string<uuid>

ID de sessió persistida quan save_api_request=true (utilitzable amb GET /v3/session/{sessionId}/decision/); en cas contrari, un UUID de correlació transitori.

document_ai
object
vendor_data
string | null

Ressò de les vendor_data que has enviat, o null.

metadata
object | null

Ressò de l'objecte metadata que has enviat, o null.

created_at
string<date-time>

Quan es va processar la sol·licitud (UTC, ISO 8601).

Darrera modificació el 7 de novembre del 2026