> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanify.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Callback URL

> Entenda como receber automaticamente os resultados da API Scanify após o processamento de documentos

<Info>
  O Scanify permite que você receba o resultado do processamento assim que ele for concluído, usando um `callbackUrl` informado em cada requisição.
</Info>

## O que é o `callbackUrl`?

O `callbackUrl` é um parâmetro opcional que você envia junto com o documento para processar. Ele define para onde o Scanify enviará o resultado da extração e validação, assim que o documento for processado.

***

## Como usar

Inclua os campos de callback no corpo JSON da requisição `POST /extract`:

| Campo                      | Tipo                       | Obrigatório | Descrição                                                                                                                                                                                      |
| -------------------------- | -------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `callbackUrl`              | string                     | não         | URL que receberá o resultado                                                                                                                                                                   |
| `callbackMethod`           | `POST` \| `PATCH` \| `PUT` | não         | Método HTTP (padrão: `POST`)                                                                                                                                                                   |
| `callbackAuthToken`        | string                     | não         | Token enviado no header `Authorization` para o seu endpoint                                                                                                                                    |
| `includeMarkdownInWebhook` | boolean                    | não         | Inclui o markdown do documento no payload (padrão: `false`)                                                                                                                                    |
| `signature`                | string                     | não         | String opaca que o Scanify reenvia, sem modificação, no header `x-scanify-signature` do callback. Use-a apenas como token de identificação — não é uma assinatura HMAC calculada pelo Scanify. |

```bash theme={"dark"}
curl -X POST https://api.scanify.com.br/extract \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file": { "fileUrl": "https://seusistema.com/boleto.pdf" },
    "callbackUrl": "https://seusistema.com/webhook",
    "callbackMethod": "POST",
    "callbackAuthToken": "meu-token-secreto",
    "includeMarkdownInWebhook": false
  }'
```

## Cabeçalhos do callback

O Scanify sempre envia os seguintes cabeçalhos:

* `Content-Type: application/json`
* `Authorization: Bearer <callbackAuthToken>` — presente apenas se `callbackAuthToken` foi fornecido
* `x-scanify-signature: <signature>` — presente apenas se `signature` foi fornecida na requisição original

## Payload de resposta

Assim que o processamento for concluído, o Scanify enviará a requisição para a URL especificada.

<Tabs>
  <Tab title="Padrão">
    ```json theme={"dark"}
    {
      "request_id": "abc123",
      "document_type": "BOLETO",
      "status": "success",
      "reference_id": "pedido-9876",
      "metadata": { "origem": "app-mobile" },
      "fields": {
        "amount":    { "value": 129.90, "confidence_score": 0.97 },
        "due_date":  { "value": "2024-06-20" },
        "barcode":   { "value": "23791...", "confidence_score": 0.99 }
      },
      "scanify": {
        "reliability_score": 0.94,
        "reliability_level": "high",
        "schema_version": "1.0"
        // veja a página de Confiabilidade para o bloco scanify completo
      },
      "processed_at": "2025-05-15T21:00:00Z"
    }
    ```
  </Tab>

  <Tab title="Com markdown (includeMarkdownInWebhook=true)">
    ```json theme={"dark"}
    {
      "request_id": "abc123",
      "document_type": "BOLETO",
      "status": "success",
      "reference_id": "pedido-9876",
      "metadata": { "origem": "app-mobile" },
      "fields": {
        "amount":    { "value": 129.90, "confidence_score": 0.97 },
        "due_date":  { "value": "2024-06-20" },
        "barcode":   { "value": "23791...", "confidence_score": 0.99 }
      },
      "scanify": {
        "reliability_score": 0.94,
        "reliability_level": "high",
        "schema_version": "1.0"
      },
      "processed_at": "2025-05-15T21:00:00Z",
      "markdown": "# Boleto\n\n**Valor:** R$ 129,90\n...",
      "markdown_status": "completed",
      "markdown_generated_at": "2025-05-15T21:00:05Z",
      "markdown_error": null
    }
    ```
  </Tab>
</Tabs>

<Info>
  **Dica**: Replique esse payload em ambiente de teste para validar o seu endpoint antes de ir para produção.
</Info>

## Boas práticas para o callback

* Certifique-se de que sua URL:
  * Está acessível publicamente
  * Aceita requisições POST com Content-Type: application/json
  * Retorna HTTP 200 para confirmar o recebimento

Você pode usar ferramentas como [Webhook.cool](https://webhook.cool/) para testar localmente.

## O que acontece se a URL falhar?

O Scanify realiza até **3 tentativas** de entrega, com backoff exponencial entre elas. Apenas respostas `2xx` contam como sucesso; qualquer outro código (ou timeout no seu endpoint) dispara nova tentativa.

<Warning>
  Se todas as 3 tentativas falharem, o resultado não será reenviado automaticamente. Use o endpoint `GET /extract/:requestId` para recuperar o resultado.
</Warning>

## Erros comuns e como resolver

<AccordionGroup>
  <Accordion title="Não recebo o resultado"> Certifique-se de que o `callbackUrl` foi enviado corretamente na requisição e que está acessível externamente.</Accordion>
  <Accordion title="Meu endpoint retorna 500"> Corrija qualquer exceção no seu backend e lembre-se de retornar `200 OK` mesmo que você armazene o resultado de forma assíncrona.</Accordion>
  <Accordion title="Recebo vários POSTs repetidos"> Isso acontece quando seu endpoint não responde com sucesso. Garanta que seu serviço finalize a requisição com um código `200`.</Accordion>
</AccordionGroup>

<Warning>
  Seu endpoint pode ser chamado mais de uma vez para o mesmo `request_id` (devido a retries em rede). Implemente deduplicação no seu lado usando `request_id` como chave.
</Warning>