Início Rápido
Aprenda a fazer sua primeira consulta veicular em 5 minutos!
Pré-requisitos
- ✅ Conta ativa na Checktudo
- ✅ API Key gerada (ver como obter)
- ✅ Saldo disponível para consultas
Passo 1: Listar Templates Disponíveis
Primeiro, veja quais tipos de consulta estão disponíveis:
curl -X GET "https://pwe6qnayhg.execute-api.sa-east-1.amazonaws.com/checktudo/query-templates" \
-H "x-api-key: sua_api_key"
Resposta
{
"statusCode": 200,
"body": [
{
"id": "template-uuid-1",
"slug": "consulta-completa-nacional",
"name": "Consulta Completa Nacional",
"description": "Dados completos do veículo em nível nacional",
"price": 15.00,
"requiredKeys": ["licensePlate"]
},
{
"id": "template-uuid-2",
"slug": "consulta-basica",
"name": "Consulta Básica",
"description": "Dados básicos do veículo",
"price": 5.00,
"requiredKeys": ["licensePlate"]
}
]
}
Passo 2: Realizar a Consulta
Com o slug do template desejado, 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 template (ex: agregados, veiculo-total-mais) |
keys | body | ✅ | Objeto com as chaves de busca do veículo |
Headers
| Header | Obrigatório | Descrição |
|---|---|---|
x-api-key | ✅ | Sua chave de API |
Content-Type | ✅ | application/json |
Chaves de Busca Disponíveis
| Chave | Descrição | Formato |
|---|---|---|
licensePlate | Placa do veículo | ABC1234 ou ABC1D23 |
chassis | Número do chassi | 17 caracteres |
renavam | Código Renavam | 11 dígitos |
Parâmetros Opcionais
| Parâmetro | Tipo | Descrição |
|---|---|---|
duplicity | boolean | Permite repetir consulta com mesmas chaves em menos de 1 hora |
Dica
Você pode combinar múltiplas chaves para maior precisão na busca.
Verificação de Duplicidade
Por padrão, consultas com as mesmas chaves dentro de 1 hora são bloqueadas. Use "duplicity": true no body para forçar uma nova consulta.
Exemplo
curl -X POST "https://pwe6qnayhg.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
{
"queryId": "550e8400-e29b-41d4-a716-446655440000",
"status": "sucesso"
}
Status Possíveis
| Status | Descrição |
|---|---|
sucesso | Consulta finalizada com sucesso |
pendente | Consulta em processamento |
falha | Falha na consulta |
parcial | Dados parciais disponíveis |
saldo_insuficiente | Saldo insuficiente |
Passo 3: Obter os Dados
Use o queryId retornado para buscar os dados completos da consulta.
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://pwe6qnayhg.execute-api.sa-east-1.amazonaws.com/queries/integration/550e8400-e29b-41d4-a716-446655440000" \
-H "x-api-key: sua_api_key"
Resposta
{
"queryId": "550e8400-e29b-41d4-a716-446655440000",
"status": "sucesso",
"type": "agregados",
"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"
}
}
}
Consultas mais completas
Para obter dados detalhados como restrições, débitos, histórico de proprietários e análise de risco, utilize o template 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: