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

# Autenticação

> Aprenda como autenticar suas requisições na API Uvvipague usando API Key

## Visão Geral

A API da **Uvvipague** utiliza autenticação baseada em **API Key** para garantir a segurança e identificação de cada cliente. Todas as requisições HTTP devem incluir sua chave de API no header para serem processadas.

<Info>
  **Autenticação Simples e Segura**: Basta incluir sua API Key no header `x-api-key` de todas as requisições.
</Info>

## Como Funciona

### Header Obrigatório

Todas as requisições à API devem incluir o seguinte header:

```http theme={null}
x-api-key: SUA_API_KEY_AQUI
```

### Exemplo de Requisição Autenticada

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.uvvipague.com.br/api/v1/vehicle/enrichment/ABC1234' \
    --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', 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"
  }

  response = requests.get(url, headers=headers)
  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",
    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);
  ?>
  ```

  ```java Java theme={null}
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.URI;

  HttpClient client = HttpClient.newHttpClient();
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.uvvipague.com.br/api/v1/vehicle/enrichment/ABC1234"))
      .header("x-api-key", "SUA_API_KEY_AQUI")
      .header("Content-Type", "application/json")
      .GET()
      .build();

  HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "io/ioutil"
  )

  func main() {
      url := "https://api.uvvipague.com.br/api/v1/vehicle/enrichment/ABC1234"
      
      req, _ := http.NewRequest("GET", url, nil)
      req.Header.Add("x-api-key", "SUA_API_KEY_AQUI")
      req.Header.Add("Content-Type", "application/json")
      
      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()
      
      body, _ := ioutil.ReadAll(resp.Body)
      fmt.Println(string(body))
  }
  ```
</CodeGroup>

## Obtendo sua API Key

<Steps>
  <Step title="Acesse o Painel">
    Faça login no painel administrativo da Uvvipague em [dashboard.uvvipague.com.br](https://dashboard.uvvipague.com.br)
  </Step>

  <Step title="Navegue até Configurações">
    No menu lateral, acesse a seção **Configurações** > **API Keys**
  </Step>

  <Step title="Gere ou Copie sua Chave">
    * Se você ainda não tem uma API Key, clique em **"Gerar Nova Chave"**
    * Se já possui, copie a chave existente
    * Guarde a chave em local seguro
  </Step>

  <Step title="Configure em sua Aplicação">
    Adicione a API Key nas variáveis de ambiente da sua aplicação
  </Step>
</Steps>

## Detalhes Importantes

<CardGroup cols={2}>
  <Card title="Chave Única" icon="fingerprint">
    Cada cliente possui uma **API Key única** associada à sua conta. Não compartilhe sua chave com terceiros.
  </Card>

  <Card title="Identificação" icon="id-card">
    A API Key é utilizada para **autenticação**, **identificação do cliente** e aplicação de regras de segurança.
  </Card>

  <Card title="Obrigatória" icon="exclamation-triangle">
    Todas as requisições **devem** incluir o header `x-api-key`. Requisições sem o header resultarão em erro.
  </Card>

  <Card title="Rate Limiting" icon="gauge-high">
    Sua API Key está associada aos limites de requisições do seu plano contratado.
  </Card>
</CardGroup>

## Erros de Autenticação

### HTTP 401 - Unauthorized

Este erro ocorre quando há problemas com a autenticação:

<AccordionGroup>
  <Accordion title="API Key ausente" icon="circle-xmark">
    **Causa**: O header `x-api-key` não foi incluído na requisição.

    **Solução**: Adicione o header com sua API Key válida.

    ```json theme={null}
    {
      "error": "Unauthorized",
      "message": "API Key não fornecida",
      "statusCode": 401
    }
    ```
  </Accordion>

  <Accordion title="API Key inválida" icon="key-skeleton">
    **Causa**: A API Key fornecida não existe ou está incorreta.

    **Solução**: Verifique se copiou a chave corretamente do painel.

    ```json theme={null}
    {
      "error": "Unauthorized",
      "message": "API Key inválida",
      "statusCode": 401
    }
    ```
  </Accordion>

  <Accordion title="API Key expirada" icon="clock">
    **Causa**: A API Key foi revogada ou expirou.

    **Solução**: Gere uma nova API Key no painel administrativo.

    ```json theme={null}
    {
      "error": "Unauthorized",
      "message": "API Key expirada ou revogada",
      "statusCode": 401
    }
    ```
  </Accordion>

  <Accordion title="Conta suspensa" icon="ban">
    **Causa**: Sua conta foi suspensa por violação dos termos ou falta de pagamento.

    **Solução**: Entre em contato com o suporte.

    ```json theme={null}
    {
      "error": "Unauthorized",
      "message": "Conta suspensa",
      "statusCode": 401
    }
    ```
  </Accordion>
</AccordionGroup>

### HTTP 429 - Too Many Requests

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Limite de requisições excedido",
  "statusCode": 429,
  "retryAfter": 60
}
```

Este erro indica que você excedeu o limite de requisições do seu plano. Aguarde o tempo indicado em `retryAfter` (em segundos) antes de fazer novas requisições.

## Segurança e Boas Práticas

<Warning>
  **Nunca exponha sua API Key**: Não inclua sua API Key diretamente no código-fonte, especialmente em repositórios públicos ou aplicações client-side (frontend).
</Warning>

### Recomendações de Segurança

<Steps>
  <Step title="Use Variáveis de Ambiente">
    Armazene sua API Key em variáveis de ambiente, nunca no código-fonte.

    ```bash .env theme={null}
    UVVIPAGUE_API_KEY=sua_api_key_aqui
    ```
  </Step>

  <Step title="Backend Only">
    Faça as chamadas à API **apenas do backend**. Nunca exponha a API Key no frontend (JavaScript, apps mobile, etc.).
  </Step>

  <Step title="Rotação de Chaves">
    Considere rotacionar sua API Key periodicamente (a cada 3-6 meses) como medida preventiva de segurança.
  </Step>

  <Step title="Monitore o Uso">
    Acompanhe o uso da sua API Key no painel. Atividades suspeitas podem indicar comprometimento.
  </Step>

  <Step title="Revogue se Comprometida">
    Se suspeitar que sua API Key foi comprometida, **revogue-a imediatamente** e gere uma nova no painel.
  </Step>
</Steps>

### Práticas a Evitar

<CardGroup cols={2}>
  <Card title="Código Frontend" icon="xmark">
    ```javascript theme={null}
    // NUNCA faça isso
    const apiKey = "sk_live_abc123...";
    fetch(url, { headers: { 'x-api-key': apiKey } });
    ```
  </Card>

  <Card title="Repositórios Públicos" icon="xmark">
    ```javascript theme={null}
    // NUNCA commite isso
    const config = {
      apiKey: "sk_live_abc123..."
    };
    ```
  </Card>

  <Card title="Logs Públicos" icon="xmark">
    ```javascript theme={null}
    // NUNCA logue a API Key
    console.log('API Key:', apiKey);
    logger.info(`Using key: ${apiKey}`);
    ```
  </Card>

  <Card title="URLs ou Query Params" icon="xmark">
    ```bash theme={null}
    # NUNCA passe na URL
    curl https://api.uvvipague.com.br/api?key=sk_live_abc123
    ```
  </Card>
</CardGroup>

### Implementação Correta

<CodeGroup>
  ```javascript Node.js + Express theme={null}
  // Carregue da variável de ambiente
  require('dotenv').config();

  const express = require('express');
  const app = express();

  app.get('/api/consultar-veiculo', async (req, res) => {
    const { placa } = req.query;
    
    try {
      const response = await fetch(
        `https://api.uvvipague.com.br/api/v1/vehicle/enrichment/${placa}`,
        {
          headers: {
            'x-api-key': process.env.UVVIPAGUE_API_KEY,
            'Content-Type': 'application/json'
          }
        }
      );
      
      const data = await response.json();
      res.json(data);
    } catch (error) {
      res.status(500).json({ error: 'Erro ao consultar veículo' });
    }
  });
  ```

  ```python Python + Flask theme={null}
  # Carregue da variável de ambiente
  import os
  from flask import Flask, request, jsonify
  import requests
  from dotenv import load_dotenv

  load_dotenv()
  app = Flask(__name__)

  API_KEY = os.getenv('UVVIPAGUE_API_KEY')

  @app.route('/api/consultar-veiculo')
  def consultar_veiculo():
      placa = request.args.get('placa')
      
      try:
          response = requests.get(
              f'https://api.uvvipague.com.br/api/v1/vehicle/enrichment/{placa}',
              headers={
                  'x-api-key': API_KEY,
                  'Content-Type': 'application/json'
              }
          )
          return jsonify(response.json())
      except Exception as e:
          return jsonify({'error': 'Erro ao consultar veículo'}), 500
  ```

  ```php PHP theme={null}
  <?php
  // Carregue da variável de ambiente
  require 'vendor/autoload.php';

  use Dotenv\Dotenv;

  $dotenv = Dotenv::createImmutable(__DIR__);
  $dotenv->load();

  $apiKey = $_ENV['UVVIPAGUE_API_KEY'];

  function consultarVeiculo($placa) {
      global $apiKey;
      
      $curl = curl_init();
      curl_setopt_array($curl, [
          CURLOPT_URL => "https://api.uvvipague.com.br/api/v1/vehicle/enrichment/{$placa}",
          CURLOPT_RETURNTRANSFER => true,
          CURLOPT_HTTPHEADER => [
              "x-api-key: {$apiKey}",
              "Content-Type: application/json"
          ],
      ]);
      
      $response = curl_exec($curl);
      curl_close($curl);
      
      return json_decode($response, true);
  }
  ?>
  ```
</CodeGroup>

## Ambientes de Teste e Produção

<Tabs>
  <Tab title="Produção">
    **URL Base**: `https://api.uvvipague.com.br`

    * Use sua API Key de **produção** (começa com `sk_live_`)
    * Todas as transações são reais e cobradas
    * Dados reais dos Detrans

    ```bash theme={null}
    x-api-key: sk_live_abc123def456...
    ```
  </Tab>

  <Tab title="Sandbox (Teste)">
    **URL Base**: `https://sandbox-api.uvvipague.com.br`

    * Use sua API Key de **teste** (começa com `sk_test_`)
    * Transações simuladas, sem cobrança
    * Dados de teste para desenvolvimento

    ```bash theme={null}
    x-api-key: sk_test_xyz789uvw012...
    ```
  </Tab>
</Tabs>

<Note>
  **Dica**: Durante o desenvolvimento, sempre use o ambiente de **Sandbox** para evitar cobranças desnecessárias e testar diferentes cenários.
</Note>

## Testando sua Autenticação

Você pode testar rapidamente se sua API Key está funcionando com este comando:

```bash theme={null}
curl --request GET \
  --url 'https://api.uvvipague.com.br/api/v1/health' \
  --header 'x-api-key: SUA_API_KEY_AQUI'
```

**Resposta esperada** (200 OK):

```json theme={null}
{
  "status": "ok",
  "authenticated": true,
  "account": {
    "id": "acc_123456",
    "name": "Sua Empresa",
    "plan": "professional"
  }
}
```

## Próximos Passos

Agora que você sabe como autenticar suas requisições, explore as funcionalidades da API:

<CardGroup cols={2}>
  <Card title="Enriquecimento de Placa" icon="magnifying-glass-chart" href="/enriquecimento-placa">
    Consulte informações detalhadas de veículos através da placa.
  </Card>

  <Card title="Consulta de Débitos" icon="file-invoice" href="/consulta-debitos">
    Busque débitos pendentes de veículos.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/endpoint/webhook">
    Configure notificações automáticas de eventos.
  </Card>

  <Card title="Fluxo Completo" icon="diagram-project" href="/fluxo-completo">
    Veja o fluxo completo de integração.
  </Card>
</CardGroup>

## Suporte

Precisa de ajuda com autenticação?

<CardGroup cols={2}>
  <Card title="Documentação da API" icon="book" href="/api-reference/introduction">
    Consulte a referência completa da API.
  </Card>

  <Card title="Fale com o Suporte" icon="headset" href="mailto:suporte@uvvipague.com.br">
    Entre em contato com nossa equipe.
  </Card>
</CardGroup>