Enriquecimento de Placa

Descrição

Consulta informações completas e atualizadas sobre um veículo utilizando apenas a placa. Este endpoint retorna dados cadastrais do veículo registrados nos órgãos de trânsito (Detrans) de forma síncrona e imediata.

Cobertura Nacional: O serviço funciona para veículos registrados em todos os 26 estados brasileiros e no Distrito Federal.

Quando Usar

Use este endpoint quando:

Precisa validar dados de um veículo antes de consultar débitos
Quer obter informações completas do veículo (marca, modelo, ano, chassi, etc.)
Necessita do RENAVAM para consultar débitos
Deseja enriquecer seu cadastro com dados oficiais dos Detrans

Este endpoint é opcional no fluxo de consulta de débitos. Se você já possui placa, RENAVAM e CPF/CNPJ, pode ir direto para a consulta de débitos.

Parâmetros

Path Parameters

licensePlate

string

required

Placa do veículo no formato ABC1234 ou ABC1D23 (Mercosul). Pode ser informada com ou sem hífen.Exemplos válidos:

ABC1234
ABC-1234
ABC1D23
ABC-1D23

Query Parameters

string

Sigla do estado (UF) onde o veículo está registrado. Quando informado, otimiza a consulta direcionando para o Detran específico.Valores aceitos: AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TORecomendação: Sempre informe a UF quando disponível para melhor performance.

Informações Retornadas

O endpoint retorna as seguintes informações do veículo:

Dados Básicos

placa: Placa do veículo
renavam: Número do RENAVAM (11 dígitos)
chassi: Número do chassi
uf: Estado de registro
municipio: Município de emplacamento

Características do Veículo

marca: Marca do veículo (ex: VOLKSWAGEN, FIAT, CHEVROLET)
modelo: Modelo do veículo (ex: GOL 1.0, ONIX PLUS)
anoFabricacao: Ano de fabricação
anoModelo: Ano do modelo
cor: Cor do veículo
combustivel: Tipo de combustível (FLEX, GASOLINA, DIESEL, etc.)

Classificação

categoria: Categoria do veículo (PARTICULAR, ALUGUEL, OFICIAL, etc.)
especie: Espécie do veículo (PASSAGEIRO, CARGA, etc.)
tipo: Tipo do veículo (AUTOMOVEL, MOTOCICLETA, CAMINHAO, etc.)
carroceria: Tipo de carroceria (HATCH, SEDAN, SUV, etc.)

Informações Técnicas

potencia: Potência do motor em CV
cilindradas: Cilindradas do motor em cm³
capacidadePassageiros: Capacidade de passageiros
procedencia: Procedência (NACIONAL, IMPORTADO)

Status e Restrições

situacao: Situação do veículo (CIRCULACAO, BAIXADO, etc.)
dataRegistro: Data de registro do veículo
restricoes: Array com restrições do veículo (se houver)

Códigos de Resposta HTTP

200 - Sucesso

Dados do veículo retornados com sucesso.

{
  "success": true,
  "data": {
    "placa": "ABC1234",
    "renavam": "12345678901",
    "chassi": "9BWZZZ377VT004251",
    "uf": "SP",
    "municipio": "São Paulo",
    "marca": "VOLKSWAGEN",
    "modelo": "GOL 1.0",
    "anoFabricacao": "2020",
    "anoModelo": "2021",
    "cor": "PRATA",
    "combustivel": "FLEX",
    "categoria": "PARTICULAR",
    "especie": "PASSAGEIRO",
    "tipo": "AUTOMOVEL",
    "carroceria": "HATCH",
    "potencia": "75",
    "cilindradas": "999",
    "capacidadePassageiros": 5,
    "procedencia": "NACIONAL",
    "situacao": "CIRCULACAO",
    "dataRegistro": "2020-08-15",
    "restricoes": []
  }
}

400 - Bad Request

Requisição inválida:

Placa em formato inválido
Parâmetros obrigatórios ausentes
UF inválida (se informada)

{
  "success": false,
  "error": "INVALID_REQUEST",
  "message": "Placa inválida. Use o formato ABC1234 ou ABC1D23"
}

401 - Unauthorized

Token de autenticação inválido ou ausente.

{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "API Key inválida ou ausente"
}

404 - Not Found

Veículo não encontrado nos registros dos Detrans.

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "Veículo não encontrado com a placa informada"
}

429 - Too Many Requests

Limite de requisições excedido.

{
  "success": false,
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Limite de requisições excedido. Tente novamente em 60 segundos",
  "retryAfter": 60
}

500 - Internal Server Error

Erro interno do servidor.

{
  "success": false,
  "error": "INTERNAL_ERROR",
  "message": "Erro ao processar requisição. Tente novamente mais tarde"
}

503 - Service Unavailable

Serviço temporariamente indisponível (geralmente por instabilidade no Detran).

{
  "success": false,
  "error": "SERVICE_UNAVAILABLE",
  "message": "Serviço temporariamente indisponível. Tente novamente em alguns minutos"
}

Casos de Uso

Validação de Dados em Financiamentos

Valide automaticamente as informações do veículo antes de aprovar um financiamento ou empréstimo, garantindo que os dados fornecidos pelo cliente estão corretos.

// Validar dados do veículo antes de aprovar financiamento
const veiculo = await uvvipague.enriquecerVeiculo('ABC1234', 'SP');

if (veiculo.restricoes.length > 0) {
  console.log('Veículo possui restrições:', veiculo.restricoes);
  // Negar financiamento
}

Obter RENAVAM para Consulta de Débitos

Use o enriquecimento para obter o RENAVAM quando você só tem a placa, facilitando a consulta de débitos posterior.

// 1. Enriquecer para obter RENAVAM
const veiculo = await uvvipague.enriquecerVeiculo('ABC1234', 'SP');

// 2. Consultar débitos com os dados obtidos
const debitos = await uvvipague.consultarDebitos({
  state: veiculo.uf,
  licensePlate: veiculo.placa,
  renavam: veiculo.renavam,
  cpfCnpj: '12345678900'
});

Enriquecer Cadastro de Clientes

Enriqueça automaticamente o cadastro de clientes com dados oficiais dos veículos, melhorando a qualidade das informações.

Marketplaces de Veículos

Enriqueça anúncios automaticamente com informações oficiais do veículo, aumentando a confiança dos compradores.

Gestão de Frotas

Mantenha um cadastro atualizado e completo de todos os veículos da frota com dados oficiais dos Detrans.

Boas Práticas

Valide o Formato da Placa

Antes de enviar a requisição, valide se a placa está no formato correto (ABC1234 ou ABC1D23). Isso evita erros desnecessários.

function validarPlaca(placa) {
  const regex = /^[A-Z]{3}[0-9][A-Z0-9][0-9]{2}$/;
  return regex.test(placa.replace(/[-\s]/g, ''));
}

Informe a UF quando Possível

Passar o parâmetro uf otimiza a consulta e reduz o tempo de resposta, pois a API consulta diretamente o Detran específico.

Implemente Cache

Considere cachear os resultados por um período razoável (ex: 24-48 horas) para evitar consultas duplicadas do mesmo veículo.

const cache = new Map();
const CACHE_TTL = 24 * 60 * 60 * 1000; // 24 horas

async function enriquecerComCache(placa, uf) {
  const key = `${placa}-${uf}`;
  const cached = cache.get(key);
  
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  
  const data = await uvvipague.enriquecerVeiculo(placa, uf);
  cache.set(key, { data, timestamp: Date.now() });
  
  return data;
}

Trate Erros Adequadamente

Implemente tratamento de erros robusto, especialmente para casos de placa não encontrada ou timeout de conexão.

try {
  const veiculo = await uvvipague.enriquecerVeiculo('ABC1234', 'SP');
} catch (error) {
  if (error.statusCode === 404) {
    console.log('Veículo não encontrado');
  } else if (error.statusCode === 503) {
    console.log('Detran temporariamente indisponível');
  } else {
    console.error('Erro inesperado:', error);
  }
}

Respeite os Limites de Rate

Monitore seu uso da API e implemente controles para não exceder os limites de requisições do seu plano.

Limitações e Considerações

Dados Sujeitos a Disponibilidade: As informações retornadas dependem da disponibilidade dos sistemas dos Detrans. Em casos de instabilidade, alguns dados podem não estar disponíveis temporariamente.

Os dados retornados são os registrados oficialmente nos Detrans
Alterações recentes no veículo podem levar alguns dias para serem refletidas
Veículos muito antigos podem ter informações limitadas
A consulta não retorna dados do proprietário por questões de privacidade (LGPD)
O tempo de resposta varia entre 1-5 segundos dependendo do Detran consultado

Próximos Passos

Após enriquecer os dados do veículo, você pode:

Consultar Débitos

Use os dados obtidos para consultar débitos pendentes do veículo

Fluxo Completo

Veja o fluxo completo de consulta e pagamento

Webhooks

Configure notificações para eventos importantes

Autenticação

Aprenda como obter e usar seu token de autenticação

Authorizations

x-api-key

string

header

required

API Key fornecida no painel administrativo da Uvvipague

Path Parameters

licensePlate

string

required

Placa do veículo no formato ABC1234 ou ABC1D23 (Mercosul)

Example:

"ABC1234"

Query Parameters

enum<string>

Sigla do estado (UF) onde o veículo está registrado

Available options:

AC,

AL,

AP,

AM,

BA,

CE,

DF,

ES,

GO,

MA,

MT,

MS,

MG,

PA,

PB,

PR,

PE,

PI,

RJ,

RN,

RS,

RO,

RR,

SC,

SP,

SE,

TO

Example:

"SP"

Response

Dados do veículo retornados com sucesso

success

boolean

Example:

true

data

object

Show child attributes

Documentação da API

Veículos

Débitos

Pagamentos

Webhooks

Enriquecimento de Placa

Descrição

Quando Usar

Parâmetros

Path Parameters

Query Parameters

Informações Retornadas

Dados Básicos

Características do Veículo

Classificação

Informações Técnicas

Status e Restrições

Códigos de Resposta HTTP

200 - Sucesso

400 - Bad Request

401 - Unauthorized

404 - Not Found

429 - Too Many Requests

500 - Internal Server Error

503 - Service Unavailable

Casos de Uso

Boas Práticas

Limitações e Considerações

Próximos Passos

Consultar Débitos

Fluxo Completo

Webhooks

Autenticação

Authorizations

Path Parameters

Query Parameters

Response

Documentação da API

Veículos

Débitos

Pagamentos

Webhooks

​Descrição

​Quando Usar

​Parâmetros

​Path Parameters

​Query Parameters

​Informações Retornadas

​Dados Básicos

​Características do Veículo

​Classificação

​Informações Técnicas

​Status e Restrições

​Códigos de Resposta HTTP

​200 - Sucesso

​400 - Bad Request

​401 - Unauthorized

​404 - Not Found

​429 - Too Many Requests

​500 - Internal Server Error

​503 - Service Unavailable

​Casos de Uso

​Boas Práticas

​Limitações e Considerações

​Próximos Passos

Consultar Débitos

Fluxo Completo

Webhooks

Autenticação

Authorizations

Path Parameters

Query Parameters

Response

Descrição

Quando Usar

Parâmetros

Path Parameters

Query Parameters

Informações Retornadas

Dados Básicos

Características do Veículo

Classificação

Informações Técnicas

Status e Restrições

Códigos de Resposta HTTP

200 - Sucesso

400 - Bad Request

401 - Unauthorized

404 - Not Found

429 - Too Many Requests

500 - Internal Server Error

503 - Service Unavailable

Casos de Uso

Boas Práticas

Limitações e Considerações

Próximos Passos