> ## 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

> Consulta informações completas e atualizadas sobre um veículo utilizando apenas a 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**.

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

## 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

<Tip>
  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](/api-reference/endpoint/create).
</Tip>

## Parâmetros

### Path Parameters

<ParamField path="licensePlate" type="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`
</ParamField>

### Query Parameters

<ParamField query="uf" type="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, TO

  **Recomendação:** Sempre informe a UF quando disponível para melhor performance.
</ParamField>

## 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.

```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": []
  }
}
```

### 400 - Bad Request

Requisição inválida:

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

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

```json theme={null}
{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "API Key inválida ou ausente"
}
```

### 404 - Not Found

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

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

### 429 - Too Many Requests

Limite de requisições excedido.

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

```json theme={null}
{
  "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).

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

## 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.

    ```javascript theme={null}
    // 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
    }
    ```
  </Accordion>

  <Accordion title="Obter RENAVAM para Consulta de Débitos" icon="file-invoice">
    Use o enriquecimento para obter o RENAVAM quando você só tem a placa, facilitando a consulta de débitos posterior.

    ```javascript theme={null}
    // 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'
    });
    ```
  </Accordion>

  <Accordion title="Enriquecer Cadastro de Clientes" icon="database">
    Enriqueça automaticamente o cadastro de clientes com dados oficiais dos veículos, melhorando a qualidade das informações.
  </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>
</AccordionGroup>

## 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.

    ```javascript theme={null}
    function validarPlaca(placa) {
      const regex = /^[A-Z]{3}[0-9][A-Z0-9][0-9]{2}$/;
      return regex.test(placa.replace(/[-\s]/g, ''));
    }
    ```
  </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.

    ```javascript theme={null}
    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;
    }
    ```
  </Step>

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

    ```javascript theme={null}
    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);
      }
    }
    ```
  </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)
  * O tempo de resposta varia entre 1-5 segundos dependendo do Detran consultado
</Note>

## Próximos Passos

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

<CardGroup cols={2}>
  <Card title="Consultar Débitos" icon="file-invoice" href="/api-reference/endpoint/create">
    Use os dados obtidos para consultar débitos pendentes do veículo
  </Card>

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

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

  <Card title="Autenticação" icon="key" href="/autenticacao">
    Aprenda como obter e usar seu token de autenticação
  </Card>
</CardGroup>


## OpenAPI

````yaml GET /api/v1/vehicle/enrichment/{licensePlate}
openapi: 3.1.0
info:
  title: Uvvipague API
  description: >-
    API completa para consulta e pagamento de débitos veiculares em todo o
    Brasil
  version: 1.0.0
  contact:
    name: Suporte Uvvipague
    email: suporte@uvvipague.com.br
    url: https://uvvipague.com.br
servers:
  - url: https://api.uvvipague.com.br
    description: Servidor de Produção
  - url: https://api-sandbox.uvvipague.com.br
    description: Servidor de Homologação/Sandbox
security:
  - apiKey: []
tags:
  - name: Veículos
    description: Endpoints para consulta e enriquecimento de informações de veículos
  - name: Débitos
    description: Endpoints para consulta de débitos veiculares
  - name: Pagamentos
    description: Endpoints para processamento de pagamentos
  - name: Webhooks
    description: Endpoints para configuração e gerenciamento de webhooks
paths:
  /api/v1/vehicle/enrichment/{licensePlate}:
    get:
      tags:
        - Veículos
      summary: Enriquecimento de Placa
      description: >-
        Consulta informações completas e atualizadas sobre um veículo utilizando
        apenas a placa
      operationId: enrichVehicle
      parameters:
        - name: licensePlate
          in: path
          required: true
          description: Placa do veículo no formato ABC1234 ou ABC1D23 (Mercosul)
          schema:
            type: string
            example: ABC1234
        - name: uf
          in: query
          required: false
          description: Sigla do estado (UF) onde o veículo está registrado
          schema:
            type: string
            enum:
              - 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
      responses:
        '200':
          description: Dados do veículo retornados com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichmentResponse'
        '400':
          description: Requisição inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Veículo não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    EnrichmentResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            placa:
              type: string
              example: ABC1234
            renavam:
              type: string
              example: '12345678901'
            chassi:
              type: string
              example: 9BWZZZ377VT004251
            uf:
              type: string
              example: SP
            municipio:
              type: string
              example: São Paulo
            marca:
              type: string
              example: VOLKSWAGEN
            modelo:
              type: string
              example: GOL 1.0
            anoFabricacao:
              type: string
              example: '2020'
            anoModelo:
              type: string
              example: '2021'
            cor:
              type: string
              example: PRATA
            combustivel:
              type: string
              example: FLEX
            categoria:
              type: string
              example: PARTICULAR
            especie:
              type: string
              example: PASSAGEIRO
            tipo:
              type: string
              example: AUTOMOVEL
            carroceria:
              type: string
              example: HATCH
            potencia:
              type: string
              example: '75'
            cilindradas:
              type: string
              example: '999'
            capacidadePassageiros:
              type: integer
              example: 5
            procedencia:
              type: string
              example: NACIONAL
            situacao:
              type: string
              example: CIRCULACAO
            dataRegistro:
              type: string
              format: date
              example: '2020-08-15'
            restricoes:
              type: array
              items:
                type: string
              example: []
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - INVALID_REQUEST
                - UNAUTHORIZED
                - NOT_FOUND
                - VALIDATION_ERROR
                - RATE_LIMIT_EXCEEDED
                - SERVICE_UNAVAILABLE
              example: INVALID_REQUEST
              description: Código do erro
            message:
              type: string
              example: Parâmetros inválidos na requisição
            details:
              type: object
              description: Detalhes adicionais sobre o erro
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API Key fornecida no painel administrativo da Uvvipague

````