Skip to main content
A consulta veicular permite consultar informações associadas a uma placa, como dados cadastrais do veículo, características, restrições e indicadores disponíveis nos datasets contratados.

​
Endpoint

POST /v1/search/vehicle

​
Formato da placa

O campo plate aceita placas no padrão antigo ou Mercosul, com ou sem hífen. Exemplos válidos: 
ABC1234
ABC-1234
ABC1D23
ABC-1D23

​
Corpo da requisição

{
  "plate": "ABC1D23",
  "mode": "sync",
  "datasets": [
    "vehicle_basic_data"
  ],
  "additional": {}
}

​
Campos da requisição

CampoTipoObrigatórioDescrição
platestringSimPlaca do veículo no padrão antigo ou Mercosul.
modestringNãoModo da consulta. Aceita sync ou async. O padrão é async.
datasetsarray<string>SimLista de datasets veiculares que serão consultados.
additionalobjectNãoDados adicionais exigidos por datasets específicos, quando aplicável.

​
Modos de execução

​
Síncrono

No modo sync, a API aguarda a execução da consulta e retorna o resultado na mesma requisição. 
{
  "plate": "ABC1D23",
  "mode": "sync",
  "datasets": [
    "vehicle_basic_data"
  ],
  "additional": {}
}

​
Assíncrono

No modo async, a API inicia a consulta em segundo plano e retorna um identificador para acompanhamento. 
{
  "plate": "ABC1D23",
  "mode": "async",
  "datasets": [
    "vehicle_basic_data"
  ],
  "additional": {}
}
Resposta inicial: 
{
  "code": 202,
  "message": "Consulta iniciada com sucesso.",
  "result": {
    "id": "7b6b2c9f-4e8a-4f65-9a51-7a4d0f2a1c11",
    "status": "queued",
    "datasets": [
      "vehicle_basic_data"
    ]
  }
}

​
Status da consulta assíncrona

StatusDescrição
queuedConsulta recebida e aguardando processamento.
processingConsulta em processamento.
completedConsulta finalizada com sucesso.
completed_with_errorsConsulta finalizada, mas um ou mais datasets tiveram falha.
failedConsulta não pôde ser concluída.
expiredResultado não está mais disponível para leitura.

​
Dados adicionais por dataset

Alguns datasets podem exigir informações extras para execução. Quando isso ocorrer, envie os dados dentro de additional, usando o ID do dataset como chave. Exemplo fictício: 
{
  "plate": "ABC1D23",
  "mode": "sync",
  "datasets": [
    "vehicle_example_dataset"
  ],
  "additional": {
    "vehicle_example_dataset": {
      "state": "BA",
      "reference_date": "2026-06-21"
    }
  }
}

​
Exemplo de resposta

{
  "code": 200,
  "message": "Consulta realizada com sucesso.",
  "result": {
    "vehicle_basic_data": {
      "owner": {
        "name": "NOME DO PROPRIETARIO",
        "tax_id": "000.000.000-00"
      },
      "vehicle": {
        "plate": "ABC1D23",
        "renavam": "00000000000",
        "state": "BA",
        "city": "SALVADOR",
        "chassis": "9XXXXXXXXXXXX0000",
        "brand": "HONDA",
        "model": "NXR160 BROS ESDD",
        "model_year": "2022",
        "manufacture_year": "2021",
        "type": "MOTOCICLETA",
        "fuel": "ALCOOL/GASOLINA",
        "color": "PRETA",
        "status": "EM CIRCULACAO",
        "origin": "NACIONAL",
        "category": "PARTICULAR"
      },
      "restrictions": [
        "SEM RESTRICAO"
      ],
      "indicators": {
        "renainf": false,
        "sale_communication": false,
        "renajud": false,
        "tax_authority": false,
        "theft": false,
        "auction": false,
        "recall": false
      }
    }
  },
  "query": {
    "id": "7b6b2c9f-4e8a-4f65-9a51-7a4d0f2a1c11",
    "timing": {
      "datasets": {
        "vehicle_basic_data": 1.24
      },
      "total": 1.31
    },
    "error": {},
    "datasets_status": {
      "vehicle_basic_data": "completed"
    },
    "datetime": "2026-06-21T09:00:00-03:00"
  }
}

​
Consulta com erro parcial

Quando um ou mais datasets falham, a consulta pode retornar os datasets concluídos normalmente e indicar as falhas em query.error. 
{
  "code": 200,
  "message": "Consulta realizada com sucesso.",
  "result": {},
  "query": {
    "id": "7b6b2c9f-4e8a-4f65-9a51-7a4d0f2a1c11",
    "timing": {
      "datasets": {
        "vehicle_basic_data": 1.08
      },
      "total": 1.12
    },
    "error": {
      "vehicle_basic_data": {
        "code": 42025,
        "message": "Não foi possível consultar o provedor da consulta."
      }
    },
    "datasets_status": {
      "vehicle_basic_data": "failed"
    },
    "datetime": "2026-06-21T09:00:00-03:00"
  }
}

​
Observações sobre o retorno

Nem todos os campos são retornados em todas as consultas. A disponibilidade depende da placa consultada, da base consultada e do retorno do provedor de dados. Campos nulos, vazios ou indisponíveis podem ser omitidos da resposta.

​
Ambiente de teste

Para executar consultas sem consumo de saldo, consulte a página de ambiente de teste:

Ambiente de teste

Veja como habilitar chamadas de teste usando o header correto.