Skip to main content

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.

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:
CampoTipoObrigatórioDescrição
callbackUrlstringnãoURL que receberá o resultado
callbackMethodPOST | PATCH | PUTnãoMétodo HTTP (padrão: POST)
callbackAuthTokenstringnãoToken enviado no header Authorization para o seu endpoint
includeMarkdownInWebhookbooleannãoInclui o markdown do documento no payload (padrão: false)
signaturestringnãoString 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. 
{
  "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"
}
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

Certifique-se de que o callbackUrl foi enviado corretamente na requisição e que está acessível externamente.
Corrija qualquer exceção no seu backend e lembre-se de retornar 200 OK mesmo que você armazene o resultado de forma assíncrona.
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.