Pular para o conteúdo principal

Consultas Veiculares

As consultas veiculares são o principal recurso da API Checktudo. Este guia cobre tudo que você precisa saber para realizar consultas de forma eficiente.

Base URL​

https://hwfxu4zs36.execute-api.sa-east-1.amazonaws.com

Visão Geral​

A API permite consultar informações de veículos através de diferentes chaves de busca. Cada produto informa as chaves que aceita na API Reference.

Chaves Disponíveis​

ChaveDescriçãoFormatoExemplo
licensePlatePlaca do veículoABC1234 ou ABC1D23ABC1234
chassisNúmero do chassi17 caracteres9BWZZZ377VT004251
renavamCódigo Renavam11 dígitos00123456789
engineNumberNúmero do motorAlfanuméricoABC123456
ufEstado (UF)2 caracteresSP

Quais Chaves Enviar​

As chaves listadas em um produto são alternativas: basta enviar uma delas. Se nenhuma das chaves aceitas pelo produto vier preenchida, a API responde 409.

// Apenas placa
{ "keys": { "licensePlate": "ABC1234" } }

// Placa + Chassi (recomendado quando você tem os dois)
{ "keys": { "licensePlate": "ABC1234", "chassis": "9BWZZZ377VT004251" } }

// Produtos por documento: CPF ou CNPJ
{ "keys": { "cnpj": "00000000000191" } }
Dica

Quando tiver placa e chassi, envie os dois. Algumas bases só aceitam placa (ex.: Proprietário Atual, Consulta CSV, Histórico KM) e outras só chassi (ex.: gravame). Só com chassi, esses produtos podem voltar sem dado ou em parcial.

Produtos​

Cada produto define quais blocos de informação são retornados e tem um preço próprio, definido na sua tabela de preço (Portal do Integrador → Tabela de preço). Exemplos:

SlugDescrição
agregadosConsulta agregada com dados básicos do veículo
veiculo-total-maisConsulta completa com todos os dados disponíveis
Como realizar consultas

Para um guia passo a passo de como realizar consultas, veja o Início Rápido.

Detalhes de cada endpoint

Para ver a resposta completa, todos os campos retornados e testar os endpoints interativamente, acesse a API Reference.

Cobrança​

SituaçãoCobrança
Consulta criada (201)Valor do produto reservado
falhaEstorno automático
parcialCobrada; reprocessamento sem custo adicional (até 2 vezes)
saldo_insuficienteNão executa e não cobra
Nova consulta com "duplicity": trueCobrada integralmente

Tratamento de Erros​

Os erros seguem o formato { statusCode, timestamp, path, error, message }. Veja a lista completa em Tratamento de Erros.

Boas Práticas​

  1. Cache de resultados: Armazene consultas recentes para evitar custos repetidos
  2. Validação prévia: Valide o formato da placa antes de enviar
  3. Verifique duplicidade: consultas repetidas do mesmo produto e da mesma chave em até 60 minutos recebem 409 com o existingQueryId. Use duplicity: true só para gerar, de propósito, uma nova consulta (cobrada)
  4. Webhook + GET: trate o resultado pelo webhook e use GET /queries/integration/{queryId} como contingência

Próximos Passos​