# Introdução

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

Source: https://zild.ai/pt-BR/docs/api-reference/documents-introduction

## 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'
```



<table class="api-params"><thead><tr><th>Campo</th><th>Tipo</th><th>Para que serve</th></tr></thead><tbody><tr><td><code>file</code></td><td>binário</td><td>O arquivo que será processado.</td></tr><tr><td><code>Title</code></td><td>string</td><td>O nome que identifica o documento.</td></tr><tr><td><code>Description</code></td><td>string</td><td>Uma descrição opcional para dar contexto ao arquivo.</td></tr><tr><td><code>DocumentChecklistId</code></td><td>integer</td><td>O checklist usado na análise, quando houver.</td></tr><tr><td><code>Private</code></td><td>boolean</td><td>Indica se o acesso ao documento deve ser restrito.</td></tr></tbody></table>

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](/pt-BR/docs/api-reference/webhooks#webhooks-de-documentos), 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.