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

# Referência da API

> Documentação completa dos endpoints da API Uvvipague para consulta e pagamento de débitos veiculares

## Visão Geral

A API Uvvipague oferece endpoints RESTful para integração completa com o sistema de consulta e pagamento de débitos veiculares. Esta seção contém a referência técnica detalhada de todos os endpoints disponíveis.

<Info>
  **Base URL**: `https://api.uvvipague.com.br`

  Todos os endpoints utilizam HTTPS e retornam respostas em formato JSON.
</Info>

## Estrutura da API

A API está organizada em módulos funcionais:

<CardGroup cols={2}>
  <Card title="Consulta de Veículos" icon="car" href="/api-reference/endpoint/get">
    Endpoints para enriquecimento de dados e consulta de débitos veiculares
  </Card>

  <Card title="Pagamentos" icon="credit-card" href="/api-reference/endpoint/create">
    Endpoints para processamento de pagamentos e tokenização de cartões
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/endpoint/webhook">
    Configuração e gerenciamento de notificações automáticas
  </Card>

  <Card title="Utilitários" icon="wrench" href="/api-reference/endpoint/delete">
    Endpoints auxiliares para simulação de parcelas e consultas de status
  </Card>
</CardGroup>

## Autenticação

Todos os endpoints da API requerem autenticação via **API Key**.

<Steps>
  <Step title="Obtenha sua API Key">
    Acesse o [painel administrativo](https://dashboard.uvvipague.com.br) e gere sua chave de API na seção de configurações.
  </Step>

  <Step title="Inclua o Header">
    Adicione o header `x-api-key` em todas as requisições:

    ```http theme={null}
    x-api-key: SUA_API_KEY_AQUI
    ```
  </Step>

  <Step title="Teste a Autenticação">
    Faça uma requisição de teste para validar sua chave:

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

<Warning>
  **Segurança**: Nunca exponha sua API Key em código client-side ou repositórios públicos. Mantenha-a sempre em variáveis de ambiente no backend.
</Warning>

Para mais detalhes sobre autenticação, consulte a [documentação completa de autenticação](/autenticacao).

## Ambientes

A API Uvvipague oferece dois ambientes:

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

    * Transações reais e cobradas
    * Dados reais dos Detrans
    * API Key de produção (começa com `sk_live_`)

    ```bash theme={null}
    # Exemplo de requisição em produção
    curl --request GET \
      --url 'https://api.uvvipague.com.br/api/v1/health' \
      --header 'x-api-key: sk_live_...'
    ```
  </Tab>

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

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

    ```bash theme={null}
    # Exemplo de requisição em sandbox
    curl --request GET \
      --url 'https://sandbox-api.uvvipague.com.br/api/v1/health' \
      --header 'x-api-key: sk_test_...'
    ```

    <Tip>
      Use o ambiente sandbox durante o desenvolvimento para testar diferentes cenários sem custos.
    </Tip>
  </Tab>
</Tabs>

## Formato de Requisições

Todas as requisições devem seguir o formato padrão:

### Headers Obrigatórios

```http theme={null}
x-api-key: SUA_API_KEY_AQUI
Content-Type: application/json
```

### Corpo da Requisição

```json theme={null}
{
  "campo1": "valor1",
  "campo2": "valor2"
}
```

## Formato de Respostas

### Resposta de Sucesso (2xx)

```json theme={null}
{
  "success": true,
  "data": {
    // Dados da resposta
  }
}
```

### Resposta de Erro (4xx, 5xx)

```json theme={null}
{
  "success": false,
  "error": "TipoDoErro",
  "message": "Descrição detalhada do erro",
  "statusCode": 400
}
```

## Códigos de Status HTTP

<AccordionGroup>
  <Accordion title="2xx - Sucesso" icon="circle-check">
    | Código | Descrição                              |
    | ------ | -------------------------------------- |
    | `200`  | OK - Requisição processada com sucesso |
    | `201`  | Created - Recurso criado com sucesso   |
  </Accordion>

  <Accordion title="4xx - Erro do Cliente" icon="circle-xmark">
    | Código | Descrição                                              |
    | ------ | ------------------------------------------------------ |
    | `400`  | Bad Request - Dados inválidos na requisição            |
    | `401`  | Unauthorized - API Key inválida ou ausente             |
    | `404`  | Not Found - Recurso não encontrado                     |
    | `422`  | Unprocessable Entity - Dados não podem ser processados |
    | `429`  | Too Many Requests - Limite de requisições excedido     |
  </Accordion>

  <Accordion title="5xx - Erro do Servidor" icon="server">
    | Código | Descrição                                                  |
    | ------ | ---------------------------------------------------------- |
    | `500`  | Internal Server Error - Erro interno do servidor           |
    | `503`  | Service Unavailable - Serviço temporariamente indisponível |
  </Accordion>
</AccordionGroup>

## Rate Limiting

A API implementa limites de requisições para garantir a qualidade do serviço:

<CardGroup cols={2}>
  <Card title="Limite Padrão" icon="gauge">
    **1000 requisições/minuto**

    Limite padrão para contas standard
  </Card>

  <Card title="Limite Enterprise" icon="rocket">
    **5000 requisições/minuto**

    Limite para contas enterprise
  </Card>
</CardGroup>

Quando o limite é excedido, você receberá:

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

<Tip>
  Implemente retry com backoff exponencial para lidar com erros 429 de forma elegante.
</Tip>

## Versionamento

A API utiliza versionamento na URL:

```
https://api.uvvipague.com.br/uvvi/v1/...
```

* **v1**: Versão atual e estável da API
* Mudanças breaking serão introduzidas em novas versões (v2, v3, etc.)
* Versões antigas serão mantidas por pelo menos 12 meses após deprecação

## Idempotência

Para operações críticas, use o campo `externalId` para garantir idempotência:

```json theme={null}
{
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  // ... outros campos
}
```

<Note>
  O `externalId` deve ser um UUID único gerado pelo seu sistema. A API usará este ID para evitar processamento duplicado e para correlacionar webhooks.
</Note>

## Especificação OpenAPI

<Card title="OpenAPI Specification" icon="file-code" href="/api-reference/openapi.json">
  Baixe a especificação OpenAPI completa para importar em ferramentas como Postman, Insomnia ou gerar SDKs automaticamente.
</Card>

## Próximos Passos

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

  <Card title="Autenticação" icon="key" href="/autenticacao">
    Entenda como autenticar suas requisições
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks">
    Configure notificações automáticas
  </Card>
</CardGroup>

## Suporte

Precisa de ajuda com a API?

<CardGroup cols={2}>
  <Card title="Documentação Completa" icon="book" href="/index">
    Consulte a documentação completa
  </Card>

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