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
| Chave | Descrição | Formato | Exemplo |
|---|---|---|---|
licensePlate | Placa do veículo | ABC1234 ou ABC1D23 | ABC1234 |
chassis | Número do chassi | 17 caracteres | 9BWZZZ377VT004251 |
renavam | Código Renavam | 11 dígitos | 00123456789 |
engineNumber | Número do motor | Alfanumérico | ABC123456 |
uf | Estado (UF) | 2 caracteres | SP |
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" } }
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:
| Slug | Descrição |
|---|---|
agregados | Consulta agregada com dados básicos do veículo |
veiculo-total-mais | Consulta completa com todos os dados disponíveis |
Para um guia passo a passo de como realizar consultas, veja o Início Rápido.
Para ver a resposta completa, todos os campos retornados e testar os endpoints interativamente, acesse a API Reference.
Cobrança
| Situação | Cobrança |
|---|---|
Consulta criada (201) | Valor do produto reservado |
falha | Estorno automático |
parcial | Cobrada; reprocessamento sem custo adicional (até 2 vezes) |
saldo_insuficiente | Não executa e não cobra |
Nova consulta com "duplicity": true | Cobrada 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
- Cache de resultados: Armazene consultas recentes para evitar custos repetidos
- Validação prévia: Valide o formato da placa antes de enviar
- Verifique duplicidade: consultas repetidas do mesmo produto e da mesma chave em até 60 minutos recebem
409com oexistingQueryId. Useduplicity: truesó para gerar, de propósito, uma nova consulta (cobrada) - Webhook + GET: trate o resultado pelo webhook e use
GET /queries/integration/{queryId}como contingência
Próximos Passos
- Início Rápido - Guia passo a passo
- API Reference - Teste os endpoints
- CRLV Digital
- Consultas em Lote