Casos de uso

Como combinar as consultas da API Veículos em fluxos práticos. Os cenários abaixo usam apenas comportamentos descritos na documentação da API.

1. Consulta base + gravame

Objetivo: obter os dados do veículo e verificar a situação de alienação fiduciária antes de uma negociação.

Faça a consulta base

GET /veiculos/v3/consulta-base com tipo=chassi, documento e idFinalidade. Guarde o protocolo.

Consulte o gravame

GET /veiculos/v3/demais-consultas com consulta=gravame, o mesmo tipo e documento, e o protocolo retornado.

Interprete a resposta

O gravame traz alienação fiduciária, agente financeiro, financiado e restrição financeira.

GET /veiculos/v3/demais-consultas — gravame

curl -X GET \
  "https://api.assertivasolucoes.com.br/veiculos/v3/demais-consultas?tipo=chassi&documento=99YBSR9RH9J999999&consulta=gravame&protocolo=SEU_PROTOCOLO&idFinalidade=2" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

const accessToken = process.env.ASSERTIVA_ACCESS_TOKEN;

const url = new URL("https://api.assertivasolucoes.com.br/veiculos/v3/demais-consultas");
url.searchParams.set("tipo", "chassi");
url.searchParams.set("documento", "99YBSR9RH9J999999");
url.searchParams.set("consulta", "gravame");
url.searchParams.set("protocolo", protocolo);
url.searchParams.set("idFinalidade", "2");

const resposta = await fetch(url, {
  headers: { Authorization: `Bearer ${accessToken}` }
});
const dados = await resposta.json();
console.log(dados.resposta);

import os
import requests

access_token = os.environ["ASSERTIVA_ACCESS_TOKEN"]

resposta = requests.get(
    "https://api.assertivasolucoes.com.br/veiculos/v3/demais-consultas",
    headers={"Authorization": f"Bearer {access_token}"},
    params={
        "tipo": "chassi",
        "documento": "99YBSR9RH9J999999",
        "consulta": "gravame",
        "protocolo": protocolo,
        "idFinalidade": 2,
    },
)
resposta.raise_for_status()
print(resposta.json()["resposta"])

A consulta complementar exige que uma consulta base com o mesmo tipo e documento tenha sido feita antes — por isso o protocolo é obrigatório.

2. Verificação de risco (roubo/furto e sinistro)

Objetivo: avaliar indícios de risco de um veículo antes de aceitá-lo em uma operação.

consulta=binfederalrf: dados federais complementados por informações de roubo e furto.
consulta=indiciosinistro: indica a existência ou não de indício de sinistro.
consulta=historicoleilao: registros de leilão, comitente, leiloeiro e indicadores relacionados.

Não considere a ausência de restrições como garantia absoluta de inexistência de ocorrências fora da base consultada.

3. Precificação do veículo

Objetivo: obter valores de referência do veículo, incluindo a Tabela FIPE.

Após a consulta base, chame GET /veiculos/v3/demais-consultas com consulta=precificador, o mesmo tipo e documento e o protocolo. A resposta traz dados do veículo e valores de referência.

4. Dados estaduais e federais

Objetivo: aprofundar os dados cadastrais e a situação do veículo.

BIN estadual

consulta=binestadual: dados estaduais, situação do veículo, débitos, restrições e comunicação de venda.

BIN federal

consulta=binfederal: dados federais, identificação do veículo, gravame e restrições.

Decodificador de chassi

consulta=decodificadorchassi: informações decodificadas a partir do chassi e dados de referência.

5. Histórico de veículos por CPF ou CNPJ

Objetivo: listar os veículos historicamente vinculados a uma pessoa física ou jurídica. Esta consulta é independente da consulta base.

GET /veiculos/v3/historico-veiculos — veículos vinculados a um documento

GET /veiculos/v3/historico-veiculos

curl -X GET \
  "https://api.assertivasolucoes.com.br/veiculos/v3/historico-veiculos?documento=11111111111&idFinalidade=2" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

const accessToken = process.env.ASSERTIVA_ACCESS_TOKEN;

const url = new URL("https://api.assertivasolucoes.com.br/veiculos/v3/historico-veiculos");
url.searchParams.set("documento", "11111111111");
url.searchParams.set("idFinalidade", "2");

const resposta = await fetch(url, {
  headers: { Authorization: `Bearer ${accessToken}` }
});
const dados = await resposta.json();
console.log(dados.resposta);

import os
import requests

access_token = os.environ["ASSERTIVA_ACCESS_TOKEN"]

resposta = requests.get(
    "https://api.assertivasolucoes.com.br/veiculos/v3/historico-veiculos",
    headers={"Authorization": f"Bearer {access_token}"},
    params={"documento": "11111111111", "idFinalidade": 2},
)
resposta.raise_for_status()
print(resposta.json()["resposta"])

A resposta pode trazer, para cada veículo: placa, município, UF, RENAVAM, chassi, número do motor, ano de fabricação e do modelo, procedência, espécie, combustível, cor e marca/modelo.

Recomendações

Boas práticas

Reaproveite o protocolo

As consultas complementares exigem o protocolo e o mesmo tipo/documento da consulta base.

Normalize a entrada

Normalize placa, chassi, CPF e CNPJ antes de consultar e controle consultas duplicadas.

Informe a finalidade

A API Veículos aceita apenas idFinalidade=2 (Ciclo de crédito), compatível com o processo de negócio.

Trate erros temporários

Em 500/502/503/504, use retentativas controladas; em timeout, aguarde antes de reconsultar.