Referência pública

Documentação da API e documentos suportados

Envie o conteúdo Base64 de um QR Code VIO e receba uma resposta JSON estruturada. A autenticação usa API key e os webhooks são assinados com HMAC-SHA256.

Revisado em 11 de setembro de 2026.

Resposta rápida

A integração envia o valor Base64 lido do QR Code no campo payload_base64 e recebe os dados que o template reconhecido expõe em JSON. A foto só é retornada quando existe no documento, é compatível e foi solicitada. Para automações, o servidor pode receber o resultado por webhook assinado.

Autenticação: Header X-API-Key; nunca exponha a chave no navegador.
Formato: application/json com entrada Base64 e resposta JSON.
Entrega assíncrona: Webhook HTTPS validado com timestamp, HMAC-SHA256 e ID único.
Limite funcional: Campos e foto variam por documento; a leitura não decide sozinha sua validade jurídica.

1. Autentique

Crie uma chave no painel e envie-a somente no header X-API-Key.

2. Decodifique

Faça POST com JSON estrito e payload Base64 no limite documentado.

3. Automatize

Em planos compatíveis, receba eventos assinados no endpoint HTTPS cadastrado.

POST /api/v1/decode/payload

Use `Content-Type: application/json`. O campo `payload_base64` é obrigatório; `include_photo_base64` controla se a resposta deve incluir a imagem quando o documento oferecer esse dado.

# 1. Defina CONSULTA_API_KEY no ambiente e envie o payload Base64
curl -X POST https://consulta.dev.br/api/v1/decode/payload \
  -H "X-API-Key: ${CONSULTA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"payload_base64": "ZBEiAQVAAEc...", "include_photo_base64": true}'

A API retorna códigos 401 para credencial inválida, 413 para corpo acima do limite, 429 para cota excedida e respostas 4xx estáveis para entrada inválida.

Validação de webhooks

Valide sempre a assinatura sobre o corpo bruto, confira a janela do timestamp e armazene o identificador da entrega para impedir processamento duplicado.

signed = X-Webhook-Timestamp + "." + raw_body
expected = "v1=" + HMAC_SHA256(WEBHOOK_SECRET, signed)

# Compare em tempo constante, aceite no máximo 5 minutos
# e deduplique pelo header X-Webhook-Delivery.

Sobre a tecnologia VIO

O SERPRO descreve o VIO como uma tecnologia para inserir dados de documentos em QR Codes e disponibiliza um aplicativo oficial e uma API Decoder. O consulta.dev.br é um serviço independente: ele não é o aplicativo oficial do SERPRO ou da SENATRAN e deve ser usado com revisão e finalidade autorizada.

Dados e segurança

Conheça os documentos catalogados e a política de retenção antes de integrar.

Ver documentos Privacidade

Catálogo técnico

Documentos suportados

Consulte os templates que possuem descrição técnica no catálogo público. A compatibilidade efetiva depende da versão do QR Code e do template reconhecido pelo motor no momento da consulta.