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.

A API do Scanify retorna códigos HTTP padrão e, em caso de falha, um JSON descrevendo o erro. O formato do corpo depende do código.

​
Códigos HTTP

CódigoQuando ocorreShape de resposta
200Sucesso.Ver Payload de resposta.
400Erro de validação (corpo, formato, URL, segurança do arquivo).{ "message": "..." }
401Chave de API ausente ou inválida.{ "error": "Unauthorized" }
404requestId informado não existe ou não pertence à conta.{ "message": "Request not found" }
408Timeout do endpoint síncrono.{ "success": false, "status": "failed", "code": "SYNC_TIMEOUT", "message": "...", "request_id": "..." }
500Falha inesperada no servidor.{ "message": "...", "request_id"?: "..." }

​
400 — Bad Request

Resposta: 
{
  "message": "Dados inválidos: ..."
}
Em endpoints que já criaram a requisição antes de falhar, o corpo pode incluir request_id. Causas conhecidas:
  • Schema inválido (Zod): parâmetros faltando, tipos errados ou valores fora do range. Mensagem no formato Dados inválidos: <detalhe do Zod>.
  • documentType inválido: valor não está na lista suportada. Veja Tipos de documento.
  • Arquivo + URL no mesmo request: Envie o arquivo ou a URL, não ambos.
  • Nenhum arquivo enviado: Nenhum arquivo enviado.
  • Arquivo vazio: Arquivo vazio.
  • Formato não suportado: Formato de arquivo não suportado. Formatos aceitos: PDF, JPEG, PNG, TIFF, XML.
  • XML em endpoint errado: XML só é aceito em /extract/sync com documentType=NFE. Em /classify: Classificação de XML não é suportada. Use /extract/sync com documentType=NFE.
  • Arquivo bloqueado por segurança: Arquivo bloqueado pela validação de segurança.
  • URL inválida: URL inválida. ou Protocolo de URL inválido.
  • IP de destino bloqueado (SSRF): Endereço IP não permitido. — a URL resolveu para um IP privado, loopback ou link-local.
  • Download falhou: Não foi possível baixar o arquivo da URL fornecida.
  • Arquivo excede o tamanho máximo: Arquivo excede o tamanho máximo permitido.

​
401 — Unauthorized

{
  "error": "Unauthorized"
}
Causas:
  • Header Authorization ausente.
  • Token presente mas chave de API inválida ou revogada.
Veja Autenticação para o formato correto do header.

​
404 — Not Found

{
  "message": "Request not found"
}
Retornado por GET /extract/{requestId} (e endpoints relacionados como /markdown e /bounding-box) quando o requestId não existe ou não pertence à conta dona da chave de API usada.

​
408 — Request Timeout

Exclusivo do endpoint síncrono POST /extract/sync. 
{
  "success": false,
  "status": "failed",
  "code": "SYNC_TIMEOUT",
  "message": "...",
  "request_id": "req_01H..."
}
O documento não terminou de processar dentro do timeout informado (padrão 60000 ms). Recomendações:
  • Aumente o parâmetro timeout no corpo da requisição (até o limite documentado).
  • Para documentos grandes ou processamento em volume, use o fluxo assíncrono com callbackUrl. Veja Fluxo de uso.
  • A requisição continua processando — você pode consultar o status posteriormente em GET /extract/{requestId} usando o request_id retornado.

​
500 — Internal Server Error

{
  "message": "Erro inesperado.",
  "request_id": "req_01H..."
}
request_id aparece se a requisição chegou a ser criada antes da falha. Recomendações:
  • Faça retry com backoff exponencial.
  • Se persistir, contate o suporte com o request_id.
A lista completa de valores aceitos em documentType está em Tipos de documento.