Callback URL - Scanify

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

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.

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.

Padrão
Com markdown (includeMarkdownInWebhook=true)

{
  "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"
}

{
  "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
}

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

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 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.

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

Erros comuns e como resolver

Não recebo o resultado

Certifique-se de que o callbackUrl foi enviado corretamente na requisição e que está acessível externamente.

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.

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.

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.

​O que é o callbackUrl?

​Como usar

​Cabeçalhos do callback

​Payload de resposta

​Boas práticas para o callback

​O que acontece se a URL falhar?

​Erros comuns e como resolver

O que é o `callbackUrl`?

Como usar

Cabeçalhos do callback

Payload de resposta

Boas práticas para o callback

O que acontece se a URL falhar?

Erros comuns e como resolver