API de consulta veicular

A mesma consulta do aplicativo, para a sua aplicação. Esta página cobre os endpoints veiculares. A referência completa, com todos os campos e códigos de erro, está em valida.certificadoradigital.com/docs.

Endereço base
https://valida.certificadoradigital.com/api/v1
Versão atual da API: 1.5.0. Toda resposta traz X-Request-Id, e todo erro sai no formato RFC 9457 (application/problem+json) com um code estável.

Autenticação

Envie a chave no cabeçalho Authorization. O prefixo define o ambiente: bv_live_ para produção e bv_test_ para teste. A chave de teste responde com dados gravados, sem cobrança e sem consultar as bases.

curl https://valida.certificadoradigital.com/api/v1/pacotes \
  -H "Authorization: Bearer bv_live_sua_chave"

Como a cobrança funciona

Cada consulta debita o preço do produto da carteira da conta. Se a consulta falhar, o valor é estornado. Numa consulta combinada, o lote inteiro é validado e debitado antes de qualquer execução: ou tudo entra, ou nada é cobrado.

Idempotência

Nos endpoints que cobram, envie Idempotency-Key com um UUID por intenção. Repetir a mesma chave devolve a mesma resposta, com o cabeçalho Idempotent-Replayed: true, em vez de cobrar de novo.

Endpoints veiculares

GET /pacotes produtos:ler

Os laudos veiculares disponíveis, com preço, o que cada um verifica e como executar. execucao diz se o pedido vai em /consultas (um produto) ou em /consultas-combinadas (lista de produtos). O preço é a soma dos produtos.

{
  "objeto": "lista",
  "itens": [
    {
      "id": "veiculo-consulta-simples",
      "objeto": "pacote",
      "nome": "Consulta Veicular Simples",
      "execucao": "combinada",
      "produtos": ["veiculo-debitos-restricoes", "veiculo-bnacional-online", "…"],
      "preco": { "centavos": 629, "formatado": "R$ 6,29" },
      "verificacoes": ["Débitos e restrições", "Ficha técnica de fábrica", "…"]
    }
  ]
}

GET /produtos produtos:ler

Todos os produtos da API, com preço, parâmetros aceitos e o que cada um entrega. Use quando precisar montar a sua própria combinação em vez de usar um pacote pronto.

POST /consultas consultas:executar

Executa um produto e debita o preço. A requisição espera até cerca de 20 segundos: 201 quando termina nesse tempo, com o resultado na resposta, e 202 quando segue em andamento. Nesse caso acompanhe pelo id, respeitando o Retry-After.

curl -X POST https://valida.certificadoradigital.com/api/v1/consultas \
  -H "Authorization: Bearer bv_live_sua_chave" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1b1d5a-0a3e-4a9f-9a1a-2f5f0b4f2c11" \
  -d '{"produto": "veiculo-total", "parametros": {"placa": "ABC1D23"}}'

POST /consultas-combinadas consultas:executar

De 1 a 20 produtos sobre os mesmos parâmetros, numa chamada só. Devolve um grupo_id e o resumo do lote. É assim que os laudos com execucao: "combinada" são pedidos.

curl -X POST https://valida.certificadoradigital.com/api/v1/consultas-combinadas \
  -H "Authorization: Bearer bv_live_sua_chave" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4a0e2b6c-9f31-4c62-8d0e-7b2a11d9c8e4" \
  -d '{
    "produtos": ["veiculo-debitos-restricoes", "veiculo-bnacional-online"],
    "parametros": {"placa": "ABC1D23"}
  }'

GET /consultas/{id} · /consultas-combinadas/{grupoId}

Acompanha ou recupera o pedido, em qualquer estado, sem custo e sem refazer a consulta. Use para terminar um 202 e para recuperar um resultado cuja resposta você perdeu.

GET /consultas/{id}/relatorio · /consultas-combinadas/{grupoId}/relatorio

O relatório por assunto, o mesmo que sai na tela e no PDF: identificação do veículo, resultado geral, pontos de atenção e cada seção com o que a base respondeu. Com ?formato=pdf devolve o PDF, que em produção leva código de validação.

curl "https://valida.certificadoradigital.com/api/v1/consultas/$ID/relatorio?formato=pdf" \
  -H "Authorization: Bearer bv_live_sua_chave" -o laudo.pdf

GET /consultas histórico

Uma entrada por pedido, da mais recente para a mais antiga, com paginação por cursor. Filtre por categoria=veiculos para ver só o veicular.

GET /carteira carteira:ler

Saldo atual e totais consumidos. No ambiente de teste o saldo é fixo.

Erros

Decida sempre pelo code, nunca pelo texto. Os mais comuns no veicular:

Código	HTTP	O que fazer
`parametros_invalidos`	422	Placa fora do formato ou parâmetro que o produto não aceita. Nada foi cobrado.
`saldo_insuficiente`	402	Recarregue a carteira e repita com uma nova Idempotency-Key.
`limite_excedido`	429	Respeite o `Retry-After`.
`relatorio_indisponivel`	409	A consulta ainda está em andamento ou falhou e foi estornada.
`servidor_falhou`	502	A base não respondeu. Nada foi cobrado; tente de novo.

A prévia gratuita é exclusiva dos aplicativos. O endpoint POST /veiculos/previa aceita só token de sessão de app, com cota diária por aparelho. Pela API com chave, use os produtos veiculares.

Quero uma chave

As chaves são criadas no painel, em Configurações › API e chaves. Para contratar, fale com [email protected].