> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uvvipague.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Enriquecimento de Placa

> Consulte informações detalhadas de veículos através da placa utilizando a API Uvvipague

## O que é Enriquecimento de Placa?

O serviço de Enriquecimento de Placa permite consultar 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).

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

## Informações Disponíveis

Ao consultar uma placa, você terá acesso a diversas informações do veículo:

<CardGroup cols={2}>
  <Card title="Dados do Veículo" icon="car">
    * Marca e modelo
    * Ano de fabricação e modelo
    * Cor do veículo
    * Tipo e categoria
    * Chassi e RENAVAM
  </Card>

  <Card title="Dados de Registro" icon="file-lines">
    * UF de registro
    * Município de emplacamento
    * Data de registro
    * Situação do veículo
    * Restrições (se houver)
  </Card>

  <Card title="Características Técnicas" icon="engine">
    * Potência do motor
    * Cilindradas
    * Capacidade de passageiros
    * Capacidade de carga
    * Combustível
  </Card>

  <Card title="Informações Adicionais" icon="circle-info">
    * Espécie do veículo
    * Procedência (nacional/importado)
    * Carroceria
    * Eixos
  </Card>
</CardGroup>

## Como Usar

### Endpoint

```http theme={null}
GET /api/v1/vehicle/enrichment/{licensePlate}
```

### Parâmetros

<ParamField path="placa" type="string" required>
  Placa do veículo no formato ABC1234 ou ABC1D23 (Mercosul). Pode ser informada com ou sem hífen.
</ParamField>

<ParamField query="uf" type="string">
  Sigla do estado (opcional). Quando informado, otimiza a consulta direcionando para o Detran específico.
</ParamField>

### Exemplo de Requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.uvvipague.com.br/api/v1/vehicle/enrichment/ABC1234?uf=SP' \
    --header 'x-api-key: SUA_API_KEY_AQUI' \
    --header 'Content-Type: application/json'
  ```

  ```javascript JavaScript theme={null}
  const options = {
    method: 'GET',
    headers: {
      'x-api-key': 'SUA_API_KEY_AQUI',
      'Content-Type': 'application/json'
    }
  };

  fetch('https://api.uvvipague.com.br/api/v1/vehicle/enrichment/ABC1234?uf=SP', options)
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Erro:', error));
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.uvvipague.com.br/api/v1/vehicle/enrichment/ABC1234"
  headers = {
      "x-api-key": "SUA_API_KEY_AQUI",
      "Content-Type": "application/json"
  }
  params = {
      "uf": "SP"
  }

  response = requests.get(url, headers=headers, params=params)
  data = response.json()
  print(data)
  ```

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.uvvipague.com.br/api/v1/vehicle/enrichment/ABC1234?uf=SP",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
      "x-api-key: SUA_API_KEY_AQUI",
      "Content-Type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  curl_close($curl);

  $data = json_decode($response, true);
  print_r($data);
  ?>
  ```
</CodeGroup>

### Exemplo de Resposta

```json theme={null}
{
  "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": []
  }
}
```

## Casos de Uso

<AccordionGroup>
  <Accordion title="Validação de Dados em Financiamentos" icon="hand-holding-dollar">
    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.
  </Accordion>

  <Accordion title="Sistemas de Estacionamento" icon="square-parking">
    Identifique automaticamente veículos que entram em estacionamentos e colete informações para controle de acesso e cobrança.
  </Accordion>

  <Accordion title="Seguradoras" icon="shield-halved">
    Obtenha dados precisos do veículo para cálculo de apólices e validação de informações em processos de sinistro.
  </Accordion>

  <Accordion title="Marketplaces de Veículos" icon="store">
    Enriqueça anúncios automaticamente com informações oficiais do veículo, aumentando a confiança dos compradores.
  </Accordion>

  <Accordion title="Gestão de Frotas" icon="truck-fast">
    Mantenha um cadastro atualizado e completo de todos os veículos da frota com dados oficiais dos Detrans.
  </Accordion>

  <Accordion title="Consulta de Débitos" icon="file-invoice-dollar">
    Utilize o enriquecimento como primeiro passo antes de consultar débitos veiculares, garantindo que está consultando o veículo correto.
  </Accordion>
</AccordionGroup>

## Códigos de Resposta

<ResponseField name="200" type="Success">
  Consulta realizada com sucesso. Os dados do veículo foram encontrados e retornados.
</ResponseField>

<ResponseField name="400" type="Bad Request">
  Requisição inválida. Verifique se a placa foi informada no formato correto.
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Token de autenticação inválido ou ausente. Verifique suas credenciais.
</ResponseField>

<ResponseField name="404" type="Not Found">
  Veículo não encontrado. A placa informada não existe nos registros dos Detrans.
</ResponseField>

<ResponseField name="429" type="Too Many Requests">
  Limite de requisições excedido. Aguarde antes de fazer novas consultas.
</ResponseField>

<ResponseField name="500" type="Server Error">
  Erro interno do servidor. Entre em contato com o suporte se o problema persistir.
</ResponseField>

## Boas Práticas

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Implemente Cache">
    Considere cachear os resultados por um período razoável (ex: 24-48 horas) para evitar consultas duplicadas do mesmo veículo.
  </Step>

  <Step title="Trate Erros Adequadamente">
    Implemente tratamento de erros robusto, especialmente para casos de placa não encontrada ou timeout de conexão.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Limitações e Considerações

<Warning>
  **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.
</Warning>

<Note>
  * 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)
</Note>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Consulta de Débitos" icon="file-invoice" href="/consulta-debitos">
    Após enriquecer os dados, consulte os débitos pendentes do veículo.
  </Card>

  <Card title="Autenticação" icon="key" href="/api-reference/introduction">
    Aprenda como obter e usar seu token de autenticação.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/endpoint/webhook">
    Configure notificações para eventos importantes.
  </Card>

  <Card title="Fluxo Completo" icon="diagram-project" href="/fluxo-completo">
    Veja o fluxo completo de consulta e pagamento.
  </Card>
</CardGroup>