Pular para o conteúdo principal
POST
Python
Envie um documento e a lista de campos que você quer ler nele. A Didit executa seu modelo de extração padrão sobre o arquivo, retorna cada campo com tipo (text, number ou date como YYYY-MM-DD), detecta e decodifica os QR codes e códigos de barras compatíveis, verifica se o arquivo foi manipulado e, opcionalmente, compara o nome no documento com o nome da pessoa ou empresa esperada. Use-o para comprovante de fundos, holerites, extratos bancários, documentos fiscais, faturas ou qualquer documento que não se encaixe em um modelo fixo. Esta é a versão de servidor para servidor da etapa hospedada de Document AI. A requisição é multipart/form-data: o arquivo vai em document, e as definições dos campos vão em fields como uma única string com um array codificado em JSON.

Defina 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 sublinhados, única dentro da requisição), um name legível por humanos, uma instruction que diz ao modelo o que procurar, um type (text, number ou date) e duas flags: required e is_full_name.
Em uma requisição multipart, o array inteiro é um único valor de formulário:
A resposta devolve os fields normalizados e retorna extracted_data com chaves correspondentes aos seus valores de key, com null para tudo o que o modelo não conseguiu encontrar. name, instruction e type são opcionais em cada item (type tem text como padrão); key é obrigatório. Enviar fields como chaves de formulário com colchetes (fields[0][key]=...) ou em qualquer formato que não seja um array JSON retorna 400 antes de qualquer extração, portanto nada é cobrado.

QR codes e códigos de barras

Toda resposta bem-sucedida inclui document_ai.detected_codes. Cada item contém: O array cobre todas as páginas processadas de um PDF e fica vazio quando nenhum código suportado é encontrado. A Didit nunca adivinha um payload: QR codes danificados podem ser retornados com sua localização e parsed_payload: null, e falhas na detecção de códigos não fazem a requisição de Document AI falhar.

Correspondência de nome

Marque no máximo um campo com is_full_name: true e envie o nome de quem você espera que seja o titular do documento: Envie um grupo ou o outro, não os dois. Quando um nome é extraído e há um nome esperado, a resposta inclui name_match_score (de 0 a 100) e name_on_document. Uma pontuação abaixo de document_ai_name_match_score_threshold (padrã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 usa o primeiro campo de texto cuja chave pareça um nome (name, holder, full_name, account_holder); marque o campo explicitamente quando quiser controlar qual valor é comparado. Quando nenhum nome é encontrado no documento, ou nenhum nome esperado é enviado, 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 você pode definir por requisição: DECLINE, REVIEW ou NO_ACTION. A ação mais rigorosa acionada define document_ai.status (Declined > In Review > Approved), e todos os riscos acionados são listados em document_ai.warnings. Os padrões são os mesmos da etapa do fluxo hospedado; consulte Regras e avisos do Document AI para saber como cada risco é detectado.

Arquivos, salvamento e faturamento

  • Arquivos aceitos: PDF (com suporte a várias páginas), JPG, JPEG, PNG, TIFF, WebP ou um ZIP contendo o documento, até 30 MB. PDFs criptografados retornam 400; envie um PDF descriptografado ou uma foto.
  • save_api_request (padrão true): a requisição, os campos extraídos e os códigos detectados aparecem no Business Console em Manual Checks, onde sua equipe pode revisá-los. Defina como false para não salvar.
  • vendor_data e metadata são retornados sem alterações na resposta para que você possa vincular o resultado aos seus próprios registros.
  • Preço: $0.20 por documento, cobrado quando o documento é processado e um status é retornado. O desconto do seu plano se aplica. Consulte Preços.
Precisa que o próprio usuário envie o documento? Precisa coletar até 3 documentos em um único fluxo, traduzir automaticamente a tela de envio ou cruzar os campos extraídos com dados do documento de identidade ou de questionários? Use, em vez disso, a etapa hospedada do fluxo de trabalho do Document AI.

Autorizações

x-api-key
string
header
obrigatório

Chave de API da sua aplicação, em Developers -> API keys no Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter escopo restrito: nenhum acesso, 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á errada, 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 a requisição veio de um endereço fora da sua lista de IPs; 404 em uma rota de sessão significa que a sessão está fora dos fluxos ou status da chave. Uma chave sem acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave sem permissão de escrita em sessões recebe links e tokens de sessão como null. Consulte https://docs.didit.me/console/api-keys.

Corpo

multipart/form-data
document
file
obrigatório

O documento a ser lido. Extensões permitidas: tiff, jpg, jpeg, png, pdf, webp, zip. Tamanho máximo de upload: 30 MB (arquivos maiores são rejeitados com 400). PDFs com várias páginas são compatíveis (espere maior latência); PDFs criptografados são rejeitados com 400. As imagens são compactadas automaticamente antes do processamento.

fields
string
obrigatório

Uma string com um array codificado em JSON contendo 1–30 definições de campos (máximo de 16 KB). Cada item: key (obrigatório, ^[a-z0-9_]{1,64}$, único; a chave retornada em extracted_data), name (≤100 caracteres, exibido nas mensagens), instruction (≤500 caracteres, o que o modelo deve ler), type (text padrão | number | date), required (booleano, padrão false), is_full_name (booleano, padrão false, no máximo um por requisição). Arrays de formulário no estilo de colchetes, JSON inválido, chaves duplicadas ou mais de um is_full_name retornam 400 antes de qualquer processamento ou faturamento.

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 ser verificado em relação ao campo de nome do documento (correspondência aproximada, considerando transliteração). Use junto com expected_last_name; não pode ser combinado com expected_company_name.

Exemplo:

"Sophia"

expected_last_name
string

Sobrenome a ser verificado em relação 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 ser verificado em relação ao campo de nome do documento (para documentos de empresas). Não pode ser combinado com expected_first_name / expected_last_name (sem valor de exemplo de propósito: o exemplo de requisição gerado usa 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 alfa-2 opcional (duas letras ASCII, por exemplo FR) que ajusta a normalização do nome da empresa para expected_company_name. Usado apenas com expected_company_name.

document_ai_name_match_score_threshold
integer
padrão:80

name_match_score mínimo (0–100) para considerar que o nome corresponde. Uma pontuação menor adiciona DOCUMENT_AI_NAME_MISMATCH, regido por document_ai_name_mismatch_action.

Intervalo obrigatório: 0 <= x <= 100
Exemplo:

80

document_ai_unreadable_document_action
enum<string>
padrão:REVIEW

O que fazer quando nenhum campo pôde 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 pelo menos um campo required não pôde ser lido (DOCUMENT_AI_MISSING_REQUIRED_FIELDS; additional_data.missing_fields os lista).

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 suspeita de manipulação — modificação após a assinatura digital, editor de PDF conhecido, manipulação por sobreposição de texto, reexportação suspeita, anomalias de 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 está 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 envio está vazio ou não é um arquivo processável (DOCUMENT_AI_UNSUPPORTED_FILE).

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

Quando true (padrão), persiste a chamada como uma sessão do tipo API: visível no Business Console, recuperável via GET /v3/session/{sessionId}/decision/ usando o request_id retornado, com o documento enviado, os valores extraídos, as definições de campos e o snapshot da correspondência de nome armazenados. Quando false, nada é armazenado e request_id é um UUID transitório usado apenas para correlacionar a resposta; a chamada continua sendo cobrada.

Exemplo:

true

vendor_data
string

String opaca opcional (seu ID interno de usuário, e-mail, UUID…) armazenada na sessão persistida e devolvida na resposta. Use-a para correlacionar chamadas de API com seus próprios registros e para filtrar sessões posteriormente.

Exemplo:

"user-123"

metadata
object

Objeto JSON opcional armazenado com a sessão (quando save_api_request=true) e devolvido na resposta. Em requisições multipart, envie-o como um campo de string codificada em JSON (por exemplo, metadata={"flow":"onboarding"}), que é convertido em um objeto.

Exemplo:

Resposta

Documento processado. document_ai.status é Approved, Declined ou In Review; cada problema detectado é detalhado em document_ai.warnings. Um documento com problemas ainda retorna 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 você enviou, ou null.

metadata
object | null

Eco do objeto metadata que você enviou, ou null.

created_at
string<date-time>

Quando a requisição foi processada (UTC, ISO 8601).

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