Enriquecimento de Placa
curl --request GET \
--url https://api.uvvipague.com.br/api/v1/vehicle/enrichment/{licensePlate} \
--header 'x-api-key: <api-key>'import requests
url = "https://api.uvvipague.com.br/api/v1/vehicle/enrichment/{licensePlate}"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.uvvipague.com.br/api/v1/vehicle/enrichment/{licensePlate}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.uvvipague.com.br/api/v1/vehicle/enrichment/{licensePlate}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.uvvipague.com.br/api/v1/vehicle/enrichment/{licensePlate}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.uvvipague.com.br/api/v1/vehicle/enrichment/{licensePlate}")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.uvvipague.com.br/api/v1/vehicle/enrichment/{licensePlate}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"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": []
}
}{
"success": false,
"error": {
"code": "INVALID_REQUEST",
"message": "Parâmetros inválidos na requisição",
"details": {}
}
}{
"success": false,
"error": {
"code": "INVALID_REQUEST",
"message": "Parâmetros inválidos na requisição",
"details": {}
}
}Veículos
Enriquecimento de Placa
Consulta informações completas e atualizadas sobre um veículo utilizando apenas a placa
GET
/
api
/
v1
/
vehicle
/
enrichment
/
{licensePlate}
Enriquecimento de Placa
curl --request GET \
--url https://api.uvvipague.com.br/api/v1/vehicle/enrichment/{licensePlate} \
--header 'x-api-key: <api-key>'import requests
url = "https://api.uvvipague.com.br/api/v1/vehicle/enrichment/{licensePlate}"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.uvvipague.com.br/api/v1/vehicle/enrichment/{licensePlate}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.uvvipague.com.br/api/v1/vehicle/enrichment/{licensePlate}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.uvvipague.com.br/api/v1/vehicle/enrichment/{licensePlate}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.uvvipague.com.br/api/v1/vehicle/enrichment/{licensePlate}")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.uvvipague.com.br/api/v1/vehicle/enrichment/{licensePlate}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"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": []
}
}{
"success": false,
"error": {
"code": "INVALID_REQUEST",
"message": "Parâmetros inválidos na requisição",
"details": {}
}
}{
"success": false,
"error": {
"code": "INVALID_REQUEST",
"message": "Parâmetros inválidos na requisição",
"details": {}
}
}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
string
required
Placa do veículo no formato ABC1234 ou ABC1D23 (Mercosul). Pode ser informada com ou sem hífen.Exemplos válidos:
ABC1234ABC-1234ABC1D23ABC-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
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
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
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
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
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
1
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, ''));
}
2
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.3
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;
}
4
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);
}
}
5
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
API Key fornecida no painel administrativo da Uvvipague
Path Parameters
Placa do veículo no formato ABC1234 ou ABC1D23 (Mercosul)
Example:
"ABC1234"
Query Parameters
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"