Saltar para o conteúdo principal
POST
Python
Envie um documento e a lista dos campos que pretende ler nele. A Didit aplica o seu modelo de extração predefinido ao ficheiro, devolve todos os campos tipificados (text, number ou date como YYYY-MM-DD), deteta e descodifica os códigos QR e de barras suportados, verifica se o ficheiro foi manipulado e, opcionalmente, compara o nome que consta do documento com a pessoa ou empresa que espera. Use-o para comprovativos de fundos, recibos de vencimento, extratos bancários, documentos fiscais, faturas ou qualquer documento que não se enquadre num modelo fixo. Esta é a versão entre servidores do passo Document AI alojado. O pedido é multipart/form-data: o ficheiro vai em document e as definições dos campos vão em fields, como uma única string que contém um array JSON codificado.

Definir os campos a extrair

fields é um array JSON de 1 a 30 itens, enviado como uma única string. Cada item tem uma key (letras minúsculas, dígitos e underscores, única dentro do pedido), um name legível para humanos, uma instruction que indica ao modelo o que procurar, um type (text, number ou date) e duas flags: required e is_full_name.
Num pedido multipart, o array inteiro é um único valor de formulário:
A resposta repete os fields normalizados e devolve extracted_data com as suas chaves key, com null em qualquer campo que o modelo não tenha conseguido encontrar. name, instruction e type são opcionais em cada item (type assume text por predefinição); key é obrigatória. Enviar fields como chaves de formulário em notação de parênteses retos (fields[0][key]=...) ou em qualquer formato que não seja um array JSON devolve 400 antes de a extração ser executada, pelo que nada é faturado.

Códigos QR e códigos de barras

Todas as respostas bem-sucedidas incluem document_ai.detected_codes. Cada item contém: O array abrange todas as páginas processadas de um PDF e fica vazio quando não é encontrado nenhum código suportado. A Didit nunca adivinha um payload: os códigos QR danificados podem ser devolvidos com a respetiva localização e parsed_payload: null, e as falhas na deteção de códigos não fazem falhar o pedido de Document AI.

Correspondência de nomes

Marque no máximo um campo com is_full_name: true e envie a pessoa ou empresa que espera que seja a titular do documento: Envie um grupo ou outro, nunca ambos. Quando um nome é extraído e está presente um nome esperado, a resposta inclui name_match_score (0 a 100) e name_on_document. Uma pontuação abaixo de document_ai_name_match_score_threshold (predefinição 80) gera o aviso DOCUMENT_AI_NAME_MISMATCH e aplica document_ai_name_mismatch_action. Se nenhum campo estiver marcado com is_full_name, a Didit recorre ao primeiro campo de texto cuja chave pareça um nome (name, holder, full_name, account_holder); marque o campo explicitamente se quiser controlar qual o valor comparado. Quando não é encontrado nenhum valor de nome no documento, ou não é enviado nenhum nome esperado, a verificação de nome é ignorada e name_match_score é null.

Riscos e ações

Cada risco abaixo corresponde a um parâmetro de ação que pode definir por pedido: DECLINE, REVIEW ou NO_ACTION. A ação mais restritiva acionada determina document_ai.status (Declined > In Review > Approved), e todos os riscos acionados são listados em document_ai.warnings. As predefinições correspondem às do passo do fluxo alojado; consulte Regras e avisos do Document AI para saber como é detetado cada risco.

Ficheiros, gravação e faturação

  • Ficheiros aceites: PDF (são suportados PDFs com várias páginas), JPG, JPEG, PNG, TIFF, WebP ou um ZIP que contenha o documento, até 30 MB. PDFs encriptados devolvem 400; carregue um PDF desencriptado ou uma fotografia.
  • save_api_request (predefinição true): o pedido, os campos extraídos e os códigos detetados aparecem na Business Console, em Verificações manuais, onde a sua equipa pode rever tudo. Defina-o como false para não gravar.
  • vendor_data e metadata são devolvidos sem alterações na resposta, para que possa associar o resultado aos seus próprios registos.
  • Preço: $0.20 por documento, faturado quando o documento é processado e é devolvido um estado. O desconto do seu plano aplica-se. Consulte Preços.
Precisa de que o utilizador carregue ele próprio o documento, de recolher até 3 documentos num único fluxo, de traduzir automaticamente o ecrã de carregamento ou de cruzar os campos extraídos com dados de identidade ou de questionários? Use, em vez disso, o passo de fluxo Document AI alojado.

Autorizações

x-api-key
string
header
obrigatório

A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está incorreta, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys.

Corpo

multipart/form-data
document
file
obrigatório

O documento a ler. Extensões permitidas: tiff, jpg, jpeg, png, pdf, webp, zip. Tamanho máximo de carregamento: 30 MB (ficheiros maiores são rejeitados com 400). São suportados PDFs de várias páginas (espere uma latência superior); PDFs encriptados são rejeitados com 400. As imagens são comprimidas automaticamente antes do processamento.

fields
string
obrigatório

Uma cadeia de caracteres que representa um array codificado em JSON com 1–30 definições de campos (máximo de 16 KB). Cada item: key (obrigatório, ^[a-z0-9_]{1,64}$, exclusivo — a chave devolvida em extracted_data), name (≤100 caracteres, apresentado nas mensagens), instruction (≤500 caracteres, o que o modelo deve ler), type (text predefinido | number | date), required (booleano, predefinição false), is_full_name (booleano, predefinição false, no máximo um por pedido). Arrays de formulário com estilo de parênteses retos, JSON inválido, chaves duplicadas ou mais do que um is_full_name devolvem 400 antes de qualquer processamento ou faturação.

Exemplo:

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

Primeiro nome a verificar contra o campo do nome do documento (correspondência difusa, sensível a transliteração). Utilize em conjunto com expected_last_name; não pode ser combinado com expected_company_name.

Exemplo:

"Sophia"

expected_last_name
string

Apelido a verificar face ao campo de nome do documento, combinado com expected_first_name para name_match_score.

Exemplo:

"Martinez"

expected_company_name
string

Nome da empresa a verificar contra o campo de nome do documento (para documentos de empresas). Não pode ser combinado com expected_first_name / expected_last_name (intencionalmente sem valor de exemplo — a amostra de pedido gerada utiliza os campos de pessoa; substitua-os por este ao verificar um documento de empresa).

expected_company_country
string

Código de país ISO 3166-1 alpha-2 opcional (duas letras ASCII, por exemplo, FR) que ajusta a normalização do nome da empresa para expected_company_name. Utilizado apenas com expected_company_name.

document_ai_name_match_score_threshold
integer
padrão:80

Valor mínimo de name_match_score (0–100) para considerar que o nome coincide. Uma pontuação inferior adiciona DOCUMENT_AI_NAME_MISMATCH, regulado por document_ai_name_mismatch_action.

Intervalo necessário: 0 <= x <= 100
Exemplo:

80

document_ai_unreadable_document_action
enum<string>
padrão:REVIEW

O que fazer quando nenhum campo puder ser lido do documento (DOCUMENT_AI_UNREADABLE_DOCUMENT).

Opções disponíveis:
DECLINE,
REVIEW,
NO_ACTION
document_ai_missing_required_fields_action
enum<string>
padrão:REVIEW

O que fazer quando não for possível ler pelo menos um campo required (DOCUMENT_AI_MISSING_REQUIRED_FIELDS; additional_data.missing_fields lista-os).

Opções disponíveis:
DECLINE,
REVIEW,
NO_ACTION
document_ai_document_tampering_action
enum<string>
padrão:DECLINE

O que fazer quando a análise forense de PDF/EXIF suspeitar de manipulação — modificado após assinatura digital, editor de PDF conhecido, manipulação de texto sobreposto, reexportação suspeita, anomalias na imagem (DOCUMENT_AI_SUSPECTED_MANIPULATION).

Opções disponíveis:
DECLINE,
REVIEW,
NO_ACTION
document_ai_name_mismatch_action
enum<string>
padrão:NO_ACTION

O que fazer quando name_match_score estiver abaixo do limiar (DOCUMENT_AI_NAME_MISMATCH).

Opções disponíveis:
DECLINE,
REVIEW,
NO_ACTION
document_ai_unsupported_file_action
enum<string>
padrão:REVIEW

O que fazer quando o carregamento está vazio ou não é um ficheiro processável (DOCUMENT_AI_UNSUPPORTED_FILE).

Opções disponíveis:
DECLINE,
REVIEW,
NO_ACTION
save_api_request
boolean
padrão:true

Quando for true (predefinição), persiste a chamada como uma sessão do tipo API — visível na Business Console, recuperável através de GET /v3/session/{sessionId}/decision/ utilizando o request_id devolvido, com o documento carregado, os valores extraídos, as definições de campos e o instantâneo da correspondência de nomes armazenados. Quando for false, nada é armazenado e request_id é um UUID transitório apenas para correlação de respostas; a chamada continua a ser faturada.

Exemplo:

true

vendor_data
string

String opaca opcional (o seu ID de utilizador interno, e-mail, UUID...) guardada na sessão persistida e devolvida na resposta. Utilize-a para correlacionar chamadas de API com os seus próprios registos e para filtrar sessões mais tarde.

Exemplo:

"user-123"

metadata
object

Objeto JSON opcional armazenado com a sessão (quando save_api_request=true) e devolvido na resposta. Em pedidos multipart, envie-o como um campo de texto codificado em JSON (por exemplo, metadata={"flow":"onboarding"}) — é convertido num objeto.

Exemplo:

Resposta

Documento processado. document_ai.status é Approved, Declined ou In Review; cada problema detetado é discriminado em document_ai.warnings. Um documento com problemas continua a devolver 200 — inspecione o corpo, não apenas o código HTTP. Quando save_api_request=true, request_id é o id da sessão persistida.

request_id
string<uuid>

ID da sessão persistida quando save_api_request=true (utilizável com GET /v3/session/{sessionId}/decision/); caso contrário, um UUID de correlação transitório.

document_ai
object
vendor_data
string | null

Eco do vendor_data que enviou, ou null.

metadata
object | null

Eco do objeto metadata que enviou, ou null.

created_at
string<date-time>

Quando o pedido foi processado (UTC, ISO 8601).

Última modificação em 7 de novembro de 2026