A API Assertiva Veículos permite consultar informações cadastrais, técnicas, financeiras e históricas de veículos a partir de uma placa, chassi, motor ou de um CPF/CNPJ, conforme o tipo de consulta utilizado.

Entre as informações disponíveis estão:

Dados de identificação do veículo;
Marca, modelo, ano, cor e combustível;
Ficha técnica;
Situação cadastral e de circulação;
Restrições e bloqueios;
Gravames e alienação fiduciária;
Indícios de roubo ou furto;
Histórico de leilão;
Indícios de sinistro;
Dados de precificação;
Veículos vinculados a um CPF ou CNPJ.

A integração deve ser realizada por uma equipe técnica. A documentação completa está disponível na https://integracao.assertivasolucoes.com.br/v3/portal

1. URL base

As requisições devem utilizar a seguinte URL base:

https://api.assertivasolucoes.com.br

Os endpoints do produto Veículos utilizam o caminho:

/veiculos/v3

2. Autenticação

O acesso à API é realizado por meio de um token OAuth 2.0 do tipo Bearer.

Para gerar o token, são necessárias as credenciais da aplicação:

Client ID;
Secret.

2.1 Endpoint para gerar o token

Método: POST

URL:

https://api.assertivasolucoes.com.br/oauth2/v3/token

Configure a requisição com:

Authorization: Basic Auth;
Username: Client ID;
Password: Secret;
Content-Type: application/x-www-form-urlencoded;
Parâmetro: grant_type=client_credentials.

Exemplo do corpo:

grant_type=client_credentials

2.2 Utilização do token

Após a geração, envie o token no cabeçalho das requisições:

Authorization: Bearer SEU_TOKEN_DE_ACESSO

O tempo de validade deve ser controlado com base no campo expires_in retornado pelo serviço de autenticação. A documentação operacional informa que o token deve ser renovado após 30 minutos, enquanto o exemplo da especificação OAuth apresenta expires_in em segundos. Por segurança, a aplicação deve considerar o valor efetivamente retornado pela API.

Para consultar o procedimento completo de criação das credenciais, acesse o artigo Como gerar credenciais e token de acesso para as APIs da Assertiva.

3. Finalidade de uso e LGPD

As consultas que envolvem dados pessoais devem informar o parâmetro idFinalidade.

Para a API Veículos, estão disponíveis as seguintes finalidades:

ID	Finalidade	Descrição
`2`	Ciclo de crédito	Utilização dos dados no ciclo de proteção ao crédito, incluindo cobrança, análise da situação financeira e correta identificação.
`4`	Execução de contrato	Utilização dos dados para atualização ou execução de contrato e procedimentos preliminares relacionados ao contrato.

O valor informado deve corresponder à finalidade real do tratamento dos dados.

4. Fluxo de consulta

O fluxo recomendado depende do tipo de informação desejada.

4.1 Consulta base

A consulta base deve ser realizada primeiro quando a operação exigir informações complementares.

Ela retorna um protocolo, que deverá ser armazenado e utilizado posteriormente nas consultas adicionais.

4.2 Consultas complementares

Após realizar a consulta base, é possível solicitar informações específicas utilizando:

O mesmo tipo de identificador;
O mesmo documento consultado;
O protocolo retornado na consulta base;
O nome da consulta complementar.

4.3 Consulta de histórico por CPF ou CNPJ

A consulta de histórico de veículos por CPF ou CNPJ é independente da consulta base do veículo.

5. Consulta base do veículo

A consulta base retorna os principais dados cadastrais e técnicos do veículo.

5.1 Endpoint

Método: GET

Endpoint:

/veiculos/v3/consulta-base

URL completa:

https://api.assertivasolucoes.com.br/veiculos/v3/consulta-base

5.2 Parâmetros

Parâmetro	Obrigatório	Descrição
`tipo`	Sim	Tipo do identificador utilizado na pesquisa. Valores aceitos: `placa` ou `chassi`.
`documento`	Sim	Valor da placa ou do chassi a ser consultado.
`idFinalidade`	Sim	Finalidade de uso dos dados. Valores aceitos: `2` ou `4`.

Exemplo de requisição

GET /veiculos/v3/consulta-base?tipo=placa&documento=AAA-BBBB&idFinalidade=2

5.3 Informações retornadas

A resposta pode conter:

Placa;
Chassi;
Número do motor;
Marca e modelo;
Ano de fabricação;
Ano do modelo;
Cor;
Combustível;
Espécie;
Capacidade de passageiros;
Cilindradas;
Tipo de veículo;
Tipo de carroceria;
Número de eixos;
Peso bruto total;
Potência;
Situação de circulação;
Situação do chassi;
Município e UF;
Restrições;
Alertas;
Protocolo da consulta.

O protocolo retornado no cabeçalho deve ser armazenado para utilização em consultas complementares.

6. Consultas complementares

As consultas complementares fornecem informações específicas sobre o veículo. Para realizá-las, é necessário ter feito previamente uma consulta base com o mesmo tipo e documento.

6.1 Endpoint

Método: GET

Endpoint:

/veiculos/v3/demais-consultas

URL completa:

https://api.assertivasolucoes.com.br/veiculos/v3/demais-consultas

6.2 Parâmetros

Parâmetro	Obrigatório	Descrição
`tipo`	Sim	Tipo do identificador: `placa` ou `chassi`.
`documento`	Sim	Placa ou chassi utilizado na consulta base.
`consulta`	Sim	Tipo de informação complementar desejada.
`protocolo`	Sim	Protocolo retornado pela consulta base.
`idFinalidade`	Sim	Finalidade de uso dos dados. Valores aceitos: `2` ou `4`.

6.3 Consultas disponíveis

O parâmetro consulta aceita os seguintes valores:

Valor	Consulta	Informações principais
`binestadual`	BIN estadual	Dados estaduais, situação do veículo, débitos, restrições e comunicação de venda.
`binfederal`	BIN federal	Dados federais, identificação do veículo, gravame e restrições.
`binfederalrf`	BIN federal com roubo e furto	Dados federais complementados por informações de roubo e furto.
`decodificadorchassi`	Decodificador de chassi	Informações decodificadas a partir do chassi e dados de referência do veículo.
`gravame`	Gravame	Alienação fiduciária, agente financeiro, financiado e restrição financeira.
`historicoleilao`	Histórico de leilão	Registros de leilão, comitente, leiloeiro e indicadores relacionados.
`indiciosinistro`	Indício de sinistro	Indica a existência ou não de indício de sinistro.
`precificador`	Precificador	Dados do veículo e valores de referência, incluindo informações da Tabela FIPE.

Exemplo de requisição

GET /veiculos/v3/demais-consultas?tipo=chassi&documento=99YBSR9RH9J999999&consulta=gravame&protocolo=SEU_PROTOCOLO&idFinalidade=2

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

Esse endpoint retorna veículos historicamente vinculados a uma pessoa física ou jurídica.

7.1 Endpoint

Método: GET

Endpoint:

/veiculos/v3/historico-veiculos

URL completa:

https://api.assertivasolucoes.com.br/veiculos/v3/historico-veiculos

7.2 Parâmetros

Parâmetro	Obrigatório	Descrição
`documento`	Sim	CPF ou CNPJ a ser consultado.
`idFinalidade`	Sim	Finalidade de uso dos dados. Valores aceitos: `2` ou `4`.

Exemplo de requisição

GET /veiculos/v3/historico-veiculos?documento=11111111111&idFinalidade=2

7.3 Informações retornadas

A resposta pode conter, para cada veículo relacionado:

Placa;
Município;
UF;
RENAVAM;
Chassi;
Número do motor;
Ano de fabricação;
Ano do modelo;
Procedência;
Espécie;
Combustível;
Cor;
Marca e modelo.

8. Estrutura geral da resposta

As respostas da API normalmente são organizadas em duas partes:

8.1 Cabeçalho

O cabeçalho pode apresentar:

Data e hora da consulta;
Protocolo;
Produto;
Funcionalidade;
Finalidade utilizada;
Descrição da finalidade;
Indicação de reconsulta;
Dados de entrada utilizados.

8.2 Resposta

A propriedade resposta contém os dados específicos da consulta realizada.

A estrutura pode variar conforme o endpoint e a consulta complementar selecionada.

8.3 Alertas

A API pode retornar a propriedade alerta com mensagens adicionais relacionadas ao resultado ou ao processamento da consulta.

9. Códigos de resposta

Código	Significado	Tratamento recomendado
`200`	Consulta realizada com sucesso.	Processar e armazenar o resultado.
`400`	Parâmetros inválidos ou em desacordo com a documentação.	Validar tipo, documento, finalidade, consulta e protocolo.
`401`	Falha na autenticação.	Verificar o token e gerar um novo se necessário.
`403`	Usuário sem permissão para realizar a operação.	Confirmar as permissões da aplicação e do produto.
`500`	Erro interno inesperado.	Tentar novamente e acionar o suporte se persistir.
`502`	Resposta inesperada de um serviço integrado.	Repetir a requisição posteriormente.
`503`	Serviço temporariamente indisponível.	Aguardar e realizar nova tentativa.
`504`	Tempo limite excedido.	Aguardar antes de repetir a consulta.

A documentação informa que, em caso de timeout, a aplicação deve aguardar antes de realizar uma nova consulta para o mesmo veículo.

10. Tratamento de erros

10.1 Erro 400

Verifique:

Se tipo foi informado corretamente;
Se o valor de tipo é placa ou chassi;
Se o documento possui formato válido;
Se idFinalidade foi informado;
Se a finalidade é compatível com o produto;
Se consulta possui um valor permitido;
Se o protocolo pertence a uma consulta base anterior;
Se o mesmo documento foi utilizado na consulta base e na consulta complementar.

10.2 Erro 401

Verifique:

Se o cabeçalho Authorization foi enviado;
Se o formato utilizado é Bearer SEU_TOKEN;
Se o token expirou;
Se as credenciais foram configuradas corretamente.

10.3 Erro 403

O erro pode indicar:

Credencial não informada;
Falta de permissão para utilizar a API Veículos;
Falta de permissão para realizar a operação solicitada.

10.4 Erros temporários

Para os códigos 500, 502, 503 e 504:

Registre o erro sem armazenar dados sensíveis;
Evite várias tentativas simultâneas;
Utilize retentativas controladas;
Respeite o tempo recomendado antes de repetir;
Acione o suporte se o problema persistir.

11. Segurança e LGPD

A API pode retornar dados pessoais e informações relacionadas a veículos, proprietários, financiados e restrições. O uso dessas informações deve respeitar a LGPD e as políticas internas da organização.

Recomenda-se:

Informar uma finalidade compatível com o uso real dos dados;
Restringir o acesso às respostas por perfil de usuário;
Não armazenar informações além do período necessário;
Proteger CPF, CNPJ, nome e dados de proprietários;
Não registrar tokens ou dados completos em logs;
Utilizar HTTPS em todas as requisições;
Criptografar os resultados armazenados;
Registrar o protocolo para fins de auditoria;
Evitar o compartilhamento com sistemas não autorizados;
Aplicar controles de retenção e descarte dos dados.

12. Boas práticas de integração

Normalize placa, chassi, CPF e CNPJ antes de realizar a consulta.
Armazene o protocolo retornado na consulta base.
Utilize o mesmo tipo e documento nas consultas complementares.
Não realize uma consulta complementar sem o protocolo correspondente.
Controle consultas duplicadas.
Evite repetir chamadas após timeout sem verificar o resultado anterior.
Trate cada código de resposta individualmente.
Mantenha o token em um gerenciador seguro de credenciais.
Renove o token conforme o valor de expires_in.
Implemente retentativas com intervalo progressivo para falhas temporárias.
Não considere a ausência de restrições como garantia absoluta de inexistência de ocorrências fora da base consultada.
Valide se a finalidade informada corresponde ao processo de negócio.
Armazene os dados retornados somente pelo tempo necessário.

13. Resumo dos endpoints

Funcionalidade	Método	Endpoint
Gerar token de acesso	`POST`	`/oauth2/v3/token`
Consultar dados base do veículo	`GET`	`/veiculos/v3/consulta-base`
Consultar informações complementares	`GET`	`/veiculos/v3/demais-consultas`
Consultar histórico por CPF/CNPJ	`GET`	`/veiculos/v3/historico-veiculos`

14. Documentação e suporte

Para consultar parâmetros, exemplos de respostas e regras específicas de cada consulta, acesse a https://integracao.assertivasolucoes.com.br/v3/portal

Em caso de problemas relacionados à integração, entre em contato pelo e-mail:

atendimento@assertivasolucoes.com.br