Primeira requisição

Este passo a passo leva você até a primeira consulta bem-sucedida no Veículos, usando a consulta base por placa como exemplo.

Pré-requisitos

Credenciais

Ter suas credenciais de aplicação (Client ID e Secret).

Token de acesso

Ter gerado um token de acesso — veja Autenticação.

Monte a consulta base

GET /veiculos/v3/consulta-base — dados cadastrais e técnicos do veículo

Parâmetros (query):

Parâmetro	Obrigatório	Descrição
`tipo`	sim	Tipo do identificador: `placa` ou `chassi`.
`documento`	sim	Valor da placa ou do chassi a ser consultado.
`idFinalidade`	sim	Finalidade de uso LGPD (`2` — Ciclo de crédito).

Os valores abaixo são fictícios, apenas para ilustração. Use dados reais só em produção e conforme a finalidade declarada.

Faça a chamada

GET /veiculos/v3/consulta-base

curl -X GET \
  "https://api.assertivasolucoes.com.br/veiculos/v3/consulta-base?tipo=placa&documento=AAA-BBBB&idFinalidade=2" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

// Node 18+ possui fetch nativo.
const accessToken = process.env.ASSERTIVA_ACCESS_TOKEN;

const url = new URL("https://api.assertivasolucoes.com.br/veiculos/v3/consulta-base");
url.searchParams.set("tipo", "placa");
url.searchParams.set("documento", "AAA-BBBB");
url.searchParams.set("idFinalidade", "2");

const resposta = await fetch(url, {
  headers: { Authorization: `Bearer ${accessToken}` }
});
if (!resposta.ok) throw new Error(`Consulta falhou: ${resposta.status}`);
const dados = await resposta.json();
// Guarde o protocolo para as consultas complementares.
console.log(dados.cabecalho.protocolo);

import os
import requests

access_token = os.environ["ASSERTIVA_ACCESS_TOKEN"]

resposta = requests.get(
    "https://api.assertivasolucoes.com.br/veiculos/v3/consulta-base",
    headers={"Authorization": f"Bearer {access_token}"},
    params={"tipo": "placa", "documento": "AAA-BBBB", "idFinalidade": 2},
)
resposta.raise_for_status()
dados = resposta.json()
# Guarde o protocolo para as consultas complementares.
print(dados["cabecalho"]["protocolo"])

Entenda a resposta

A resposta de sucesso (200) traz, entre outros:

cabecalho: data/hora, protocolo, produto, funcionalidade, finalidade e dados de entrada. Guarde o protocolo — ele é exigido nas consultas complementares.
resposta: os dados do veículo (placa, chassi, número do motor, marca e modelo, ano de fabricação e do modelo, cor, combustível, espécie, capacidade, cilindradas, tipo de veículo e carroceria, eixos, peso bruto, potência, situação de circulação e do chassi, município/UF e restrições).
alerta: mensagens adicionais, quando houver.

O protocolo retornado no cabeçalho deve ser armazenado para as consultas complementares (GET /veiculos/v3/demais-consultas), que exigem o mesmo tipo e documento da consulta base.

Principais respostas de erro

Código	Significado	Tratamento recomendado
`400`	Parâmetros inválidos ou em desacordo com a documentação.	Validar `tipo`, `documento`, `idFinalidade`, `consulta` e `protocolo`.
`401`	Falha na autenticação.	Verificar o cabeçalho `Authorization`, o formato `Bearer` e a validade do token.
`403`	Usuário sem permissão para a operação.	Confirmar as permissões da aplicação e do produto.
`500` / `502` / `503` / `504`	Erro interno, serviço integrado, indisponibilidade ou tempo limite.	Aguardar e repetir com retentativas controladas; em timeout, aguarde antes de reconsultar o mesmo veículo.

Próximo passo

Veja como encadear a consulta base com as complementares e o histórico por CPF/CNPJ nos casos de uso.