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:
| Rota | Uso |
|---|---|
POST /queries/integration/{slug} | Criar uma consulta |
GET /queries/integration/{queryId} | Obter o resultado |
POST /queries/integration/{queryId}/reprocess | Reprocessar 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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
slug | path | ✅ | Slug do produto (ex: agregados, veiculo-total-mais) |
keys | body | ✅ | Objeto com as chaves de busca |
duplicity | body | ❌ | true cria uma nova consulta mesmo havendo outra igual nos últimos 60 minutos |
Headers
| Header | Obrigatório | Descrição |
|---|---|---|
x-api-key | ✅ | Sua chave de API |
Content-Type | ✅ | application/json |
Chaves de Busca
| Chave | Descrição | Formato |
|---|---|---|
licensePlate | Placa do veículo | ABC1234 ou ABC1D23 |
chassis | Número do chassi | 17 caracteres |
renavam | Código Renavam | 9 a 11 dígitos |
engineNumber | Número do motor | Texto |
uf | Estado | Sigla com 2 letras (SP) |
cpf | CPF | 11 dígitos |
cnpj | CNPJ | 14 dígitos |
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.
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
| Status | Final? | Descrição |
|---|---|---|
pendente | Não | Consulta em processamento |
reprocessando | Não | Reprocessamento em andamento |
sucesso | Sim | Todas as fontes responderam |
parcial | Sim | Ao menos uma fonte falhou (ver servicesBroken); pode ser reprocessada |
falha | Sim | Nenhum dado obtido; o valor é estornado |
saldo_insuficiente | Sim | Nã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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
queryId | path | ✅ | 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).
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: