Introdução

Veja como enviar um arquivo, acompanhar o processamento assíncrono e receber o resultado pelo webhook DocumentCompleted.

Fluxo de integração

Quando você envia um documento, a API cria o registro e inicia o processamento em segundo plano. Isso significa que a integração acontece em duas etapas: primeiro o upload; depois, a notificação de que o trabalho terminou.

Antes de enviar o primeiro arquivo, cadastre uma URL para receber o evento DocumentCompleted (webhookType: 9). Feita essa configuração, sua aplicação deve:

enviar o arquivo para POST /Document;
guardar o id devolvido pela API;
aguardar a chamada do Webhook de Eventos de Documentos;
confirmar que DocumentStatusType é 4 (Completed) e localizar o documento pelo campo Id.

A resposta do upload informa que o documento foi recebido, mas não que o processamento já terminou. Por isso, não deixe a requisição aberta nem consulte a API repetidamente: aguarde o webhook.

Payload para enviar o arquivo

O arquivo não vai dentro de um JSON. Envie a requisição como multipart/form-data: o campo file leva o conteúdo binário, enquanto título, descrição e demais informações seguem como campos de formulário.

Este é um exemplo completo usando cURL:

curl --request POST \
  --url 'https://api.zild.ai/Document' \
  --header 'X-API-Key: YOUR_USER_API_KEY' \
  --form 'file=@Contrato.pdf;type=application/pdf' \
  --form 'Title=Contrato.pdf' \
  --form 'Description=Contrato enviado pelo sistema financeiro' \
  --form 'DocumentChecklistId=7' \
  --form 'Private=false'

Campo	Tipo	Para que serve
`file`	binário	O arquivo que será processado.
`Title`	string	O nome que identifica o documento.
`Description`	string	Uma descrição opcional para dar contexto ao arquivo.
`DocumentChecklistId`	integer	O checklist usado na análise, quando houver.
`Private`	boolean	Indica se o acesso ao documento deve ser restrito.

A API devolve o documento criado logo após o upload. Guarde o campo id dessa resposta: ele será o elo entre a requisição que você enviou e o campo Id recebido mais tarde no webhook.

Payload do webhook de arquivo processado

Assim que o arquivo estiver pronto, a Zild faz uma requisição POST para a URL cadastrada no evento DocumentCompleted. Desta vez, o conteúdo chega como application/json:

{
  "Id": 123,
  "TenantId": 45,
  "Title": "Contrato.pdf",
  "Description": "Contrato enviado pelo sistema financeiro",
  "ExtractedText": "Texto extraído do documento...",
  "QuantityPages": 8,
  "AnalysisText": "Resultado da análise...",
  "FileUrl": "https://...",
  "DocumentStatusId": 12,
  "DocumentType": 2,
  "CreatedAt": "2026-09-24T12:00:00Z",
  "AnalizedAt": "2026-09-24T12:01:30Z",
  "DocumentChecklistId": 7,
  "Private": false,
  "CreatedByUserId": 18,
  "DocumentStatusType": 4
}

O valor 4 em DocumentStatusType confirma que o processamento foi concluído com sucesso. O campo Id é o mesmo documento criado no upload e deve ser usado para fazer a correlação.

Seu endpoint deve responder rapidamente com um status 2xx. Como uma mesma notificação pode ser entregue mais de uma vez, trate o Id de forma idempotente para não executar a mesma ação em duplicidade.

Webhooks de documentos

O evento de conclusão é apenas uma parte do ciclo. No artigo Webhooks de Documento, você encontra as instruções para configurar o endpoint e a lista completa de eventos: documento recebido, processamento iniciado, texto extraído, erro, conclusão e cancelamento.