Pular para o conteúdo principal

Início Rápido

Aprenda a fazer sua primeira consulta veicular em 5 minutos!

Pré-requisitos​

  • Conta de integrador ativa na Checktudo
  • API Key gerada (ver como obter)
  • Webhook cadastrado no Portal do Integrador — sem webhook, a criação de consultas responde 404 Webhook not found!
  • Saldo ou limite disponível para consultas

Passo 1: Escolher o Produto​

A chave de API (x-api-key) é aceita somente nas rotas de consulta:

RotaUso
POST /queries/integration/{slug}Criar uma consulta
GET /queries/integration/{queryId}Obter o resultado
POST /queries/integration/{queryId}/reprocessReprocessar a consulta

Não há rota de API para listar produtos. Para ver os produtos habilitados para a sua conta, com preço, use a página Tabela de preço do Portal do Integrador. O slug, as chaves de busca e os campos de cada produto estão na API Reference. Em caso de dúvida, fale com o suporte.

Passo 2: Realizar a Consulta​

Com o slug do produto, faça uma requisição POST para criar a consulta.

Endpoint​

POST /queries/integration/:slug

Parâmetros​

ParâmetroTipoObrigatórioDescrição
slugpath✅Slug do produto (ex: agregados, veiculo-total-mais)
keysbody✅Objeto com as chaves de busca
duplicitybody❌true cria uma nova consulta mesmo havendo outra igual nos últimos 60 minutos

Headers​

HeaderObrigatórioDescrição
x-api-key✅Sua chave de API
Content-Type✅application/json

Chaves de Busca​

ChaveDescriçãoFormato
licensePlatePlaca do veículoABC1234 ou ABC1D23
chassisNúmero do chassi17 caracteres
renavamCódigo Renavam9 a 11 dígitos
engineNumberNúmero do motorTexto
ufEstadoSigla com 2 letras (SP)
cpfCPF11 dígitos
cnpjCNPJ14 dígitos
Basta uma das chaves do produto

As chaves listadas em cada produto são alternativas: envie ao menos uma delas (placa ou chassi; CPF ou CNPJ). Quando tiver placa e chassi, envie os dois, porque algumas bases só aceitam um deles.

Verificação de Duplicidade

Uma consulta do mesmo produto, para a mesma chave principal (placa, depois chassi, CPF e CNPJ), feita nos últimos 60 minutos, é recusada com 409 e o existingQueryId da consulta anterior. Isso vale para consultas em qualquer status. Use "duplicity": true no body para criar uma nova consulta, que será cobrada.

Exemplo​

curl -X POST "https://hwfxu4zs36.execute-api.sa-east-1.amazonaws.com/queries/integration/agregados" \
-H "x-api-key: sua_api_key" \
-H "Content-Type: application/json" \
-d '{
"keys": {
"licensePlate": "ABC1234"
}
}'

Resposta (201)​

{
"statusCode": 201,
"data": {
"queryId": "550e8400-e29b-41d4-a716-446655440000",
"status": "pendente"
}
}

A consulta é processada de forma assíncrona. Quando ela termina, a Checktudo envia o resultado ao seu webhook.

Status Possíveis​

StatusFinal?Descrição
pendenteNãoConsulta em processamento
reprocessandoNãoReprocessamento em andamento
sucessoSimTodas as fontes responderam
parcialSimAo menos uma fonte falhou (ver servicesBroken); pode ser reprocessada
falhaSimNenhum dado obtido; o valor é estornado
saldo_insuficienteSimNão executada e não cobrada (saldo/limite insuficiente ou produto fora da sua tabela)

Passo 3: Obter os Dados​

O resultado chega pelo webhook. Se a notificação não chegar, use o queryId para buscar o resultado.

Endpoint​

GET /queries/integration/:queryId

Parâmetros​

ParâmetroTipoObrigatórioDescrição
queryIdpath✅ID da consulta retornado no Passo 2

Exemplo​

curl -X GET "https://hwfxu4zs36.execute-api.sa-east-1.amazonaws.com/queries/integration/550e8400-e29b-41d4-a716-446655440000" \
-H "x-api-key: sua_api_key"

Resposta (200)​

{
"statusCode": 200,
"data": {
"queryId": "550e8400-e29b-41d4-a716-446655440000",
"status": "sucesso",
"servicesBroken": [],
"response": {
"agregados": {
"placa": "ABC1234",
"chassi": "9BWZZZ377VT004251",
"renavam": "00123456789",
"marca": "VOLKSWAGEN",
"modelo": "GOL 1.0",
"anoFabricacao": "2020",
"anoModelo": "2021",
"cor": "BRANCO",
"combustivel": "FLEX",
"uf": "SP",
"municipio": "SAO PAULO",
"situacaoVeiculo": "CIRCULACAO"
}
}
}
}

O webhook recebe o mesmo conteúdo de data, sem o envelope, mais o campo type com o evento (QUERY_SUCCEED, QUERY_FAILED ou QUERY_REPROCESSED).

Consultas mais completas

Para obter dados detalhados como restrições, débitos, histórico de proprietários e análise de risco, utilize o produto veiculo-total-mais. Veja todos os campos disponíveis na API Reference.

Próximos Passos​

Agora que você fez sua primeira consulta, explore mais recursos:

Precisa de Ajuda?​