Veículos

A consulta de veículos permite buscar informações associadas a uma placa, como dados cadastrais, características, restrições e indicadores disponíveis nos datasets contratados. Use esta funcionalidade para validação veicular, análise de risco, antifraude, conferência cadastral e automação de fluxos operacionais envolvendo veículos.

Forma de consulta

Busca por placa

Consulte uma placa nos datasets veiculares selecionados.

Endpoints disponíveis

Recurso	Método	Endpoint	Uso principal
Busca por placa	`POST`	`/v1/search/vehicle`	Consulta datasets veiculares a partir de uma placa.
Datasets e preços	`GET`	`/v1/search/datasets/vehicle`	Lista datasets veiculares disponíveis, preço aplicado e estrutura de retorno.
Resultado assíncrono	`GET`	`/v1/search/vehicle/{id}`	Consulta o andamento e o resultado final de uma busca veicular assíncrona.

Consulta por placa

A consulta veicular usa o campo plate como identificador e executa um ou mais datasets informados em datasets.

{
  "plate": "ABC0A00",
  "mode": "async",
  "datasets": ["vehicle_basic_data"],
  "additional": {}
}

Campo	Tipo	Obrigatório	Descrição
`plate`	`string`	Sim	Placa do veículo no formato antigo ou Mercosul. Pode ser enviada com ou sem hífen.
`mode`	`string`	Não	Modo da consulta. Aceita `async` ou `sync`. O padrão recomendado é `async`.
`datasets`	`array<string>`	Sim	Lista de IDs dos datasets veiculares que serão consultados.
`additional`	`object`	Não	Dados adicionais por dataset, quando algum dataset exigir parâmetros extras.

Liste os datasets disponíveis em Datasets e preços usando target: vehicle.

Formato da placa

O campo plate aceita placas brasileiras no formato antigo e no padrão Mercosul.

Formato	Exemplo estrutural	Descrição
Antigo	`ABC1234`	Três letras seguidas de quatro números.
Mercosul	`ABC1D23`	Três letras, um número, uma letra e dois números.

A API normaliza o valor antes da consulta, removendo hífen, espaços e pontuação. Exemplos aceitos:

ABC1234
ABC-1234
ABC1D23
ABC-1D23

Modos de execução

Modo	Descrição
`async`	Inicia a consulta e retorna um `id` para acompanhar o processamento depois. É o modo recomendado para consultas com fontes online.
`sync`	Aguarda a conclusão da consulta e retorna os dados diretamente na resposta.

Consultas assíncronas podem passar pelos seguintes status:

Status	Descrição
`queued`	Consulta criada e aguardando processamento.
`processing`	Consulta em processamento.
`completed`	Consulta finalizada. Verifique o resultado, erros e status por dataset.
`failed`	Consulta finalizada com falha geral.

Para consultar o resultado final, use o endpoint de resultado assíncrono com target: vehicle.

Datasets veiculares

Os datasets veiculares disponíveis podem variar conforme plano, permissões e configuração comercial da conta.

Datasets e preços

Consulte os datasets veiculares disponíveis usando target: vehicle.

Use apenas datasets com active: true. Datasets inativos ou indisponíveis para a conta podem retornar erro.

Dados adicionais por dataset

Alguns datasets veiculares podem exigir parâmetros complementares. Esses campos aparecem em additional_fields no endpoint de Datasets e preços. Quando exigidos, envie os dados em additional, usando o ID do dataset como chave:

{
  "plate": "ABC0A00",
  "mode": "async",
  "datasets": ["vehicle_example_dataset"],
  "additional": {
    "vehicle_example_dataset": {
      "state": "SP"
    }
  }
}

O dataset acima é fictício e serve apenas para demonstrar a estrutura de envio de dados adicionais.

Retorno inicial assíncrono

Quando mode for async, a API inicia a consulta em segundo plano e retorna um identificador para acompanhamento.

{
  "code": 202,
  "message": "Consulta iniciada com sucesso.",
  "result": {
    "id": "9fcb573b-7f62-4774-978b-07e89dfef5f2",
    "status": "queued",
    "status_values": ["queued", "processing", "completed", "failed"],
    "datasets": ["vehicle_basic_data"]
  }
}

Resultado final

Quando a consulta for finalizada, o endpoint de resultado assíncrono retorna a estrutura completa da busca.

{
  "code": 200,
  "message": "Consulta realizada com sucesso.",
  "result": {
    "id": "9fcb573b-7f62-4774-978b-07e89dfef5f2",
    "status": "completed",
    "target": "vehicle",
    "query": {
      "plate": "ABC0A00",
      "datasets": ["vehicle_basic_data"],
      "additional": {}
    },
    "cost": {
      "total": 0.12,
      "refunded": 0,
      "datasets": {
        "vehicle_basic_data": {
          "charged": 0.12,
          "refunded": 0
        }
      }
    },
    "timing": {
      "total": 1.84,
      "datasets": {
        "vehicle_basic_data": 1.84
      }
    },
    "errors": {},
    "datasets_status": {
      "vehicle_basic_data": "completed"
    },
    "result": {
      "vehicle_basic_data": {
        "plate": "ABC0A00",
        "state": "SP",
        "city": "São Paulo",
        "brand": "MARCA EXEMPLO",
        "model": "MODELO EXEMPLO",
        "manufacture_year": "2020",
        "model_year": "2021",
        "fuel": "FLEX",
        "color": "PRATA",
        "vehicle_type": "AUTOMOVEL",
        "status": "EM CIRCULACAO"
      }
    },
    "created_at": "2026-06-22T12:00:00Z",
    "last_updated_at": "2026-06-22T12:00:02Z"
  }
}

Campo	Descrição
`query`	Placa, datasets e campos adicionais usados na consulta.
`cost`	Valores debitados e estornados por dataset.
`timing`	Tempo total e tempo individual por dataset, quando disponível.
`errors`	Erros por dataset, quando ocorrerem.
`datasets_status`	Status individual de cada dataset consultado.
`result`	Dados retornados por cada dataset veicular.

Campos descritos na estrutura dos datasets podem não aparecer em todas as consultas. A disponibilidade depende da placa consultada, da fonte e do dataset selecionado.

Ambiente de teste

A consulta veicular tem suporte ao ambiente de teste. Para executar uma chamada sem consumo de saldo, envie o header:

x-ambient: sandbox

Ambiente de teste

Veja como usar o header de sandbox e validar integrações sem consumir saldo.

Regras importantes

A placa deve estar em formato antigo ou Mercosul válido.
A API remove hífen, espaços e pontuação antes de validar a placa.
Campos fora do schema documentado são rejeitados pela validação da API.
Datasets indisponíveis, inativos ou não permitidos para a conta podem retornar erro.
Consultas com múltiplos datasets podem retornar resultados parciais caso algum dataset falhe.
A cobrança é calculada com base nos datasets efetivamente executados, conforme as regras comerciais da conta.
Campos nulos, vazios ou indisponíveis podem ser omitidos da resposta.

Próximos passos

Busca por placa

Veja os parâmetros e respostas da consulta veicular.

Resultado assíncrono

Consulte o andamento e o resultado final de uma consulta veicular.

Datasets e preços

Liste os datasets veiculares disponíveis e os preços aplicados.

Códigos de erro

Consulte os erros relacionados a consultas.

Primeiros passos

Utilidades

Funcionalidades

Webhook

Forma de consulta

Busca por placa

Endpoints disponíveis

Consulta por placa

Formato da placa

Modos de execução

Datasets veiculares

Datasets e preços

Dados adicionais por dataset

Retorno inicial assíncrono

Resultado final

Ambiente de teste

Ambiente de teste

Regras importantes

Próximos passos

Busca por placa

Resultado assíncrono

Datasets e preços

Códigos de erro

​Forma de consulta

Busca por placa

​Endpoints disponíveis

​Consulta por placa

​Formato da placa

​Modos de execução

​Datasets veiculares

Datasets e preços

​Dados adicionais por dataset

​Retorno inicial assíncrono

​Resultado final

​Ambiente de teste

Ambiente de teste

​Regras importantes

​Próximos passos

Busca por placa

Resultado assíncrono

Datasets e preços

Códigos de erro

Forma de consulta

Endpoints disponíveis

Consulta por placa

Formato da placa

Modos de execução

Datasets veiculares

Dados adicionais por dataset

Retorno inicial assíncrono

Resultado final

Ambiente de teste

Regras importantes

Próximos passos