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

# ENUMs e Tipos

> Referência completa de todos os enumeradores e tipos de dados utilizados na API Uvvipague

## Visão Geral

Esta página documenta todos os ENUMs (enumeradores) e tipos de dados utilizados na API Uvvipague. Use esta referência para garantir que está enviando os valores corretos nas requisições.

## Status de Pagamento

### Payment Status

Status possíveis para transações de pagamento com cartão de crédito:

| Status             | Descrição                                          | Ação Recomendada                           |
| ------------------ | -------------------------------------------------- | ------------------------------------------ |
| `paid`             | Pagamento aprovado e processado com sucesso        | Liberar produto/serviço                    |
| `in_analysis`      | Transação em análise pelo antifraude               | Aguardar atualização via webhook           |
| `refused`          | Transação recusada pela operadora ou antifraude    | Informar cliente e oferecer nova tentativa |
| `processing`       | Transação sendo processada                         | Aguardar atualização                       |
| `awaiting_payment` | Aguardando confirmação de pagamento (comum em PIX) | Aguardar pagamento do cliente              |
| `cancelled`        | Pagamento cancelado                                | Transação encerrada                        |
| `refunded`         | Pagamento estornado                                | Valor devolvido ao cliente                 |
| `chargeback`       | Contestação de pagamento                           | Analisar disputa                           |

<CodeGroup>
  ```javascript JavaScript theme={null}
  const PaymentStatus = {
    PAID: 'paid',
    IN_ANALYSIS: 'in_analysis',
    REFUSED: 'refused',
    PROCESSING: 'processing',
    AWAITING_PAYMENT: 'awaiting_payment',
    CANCELLED: 'cancelled',
    REFUNDED: 'refunded',
    CHARGEBACK: 'chargeback'
  };
  ```

  ```python Python theme={null}
  from enum import Enum

  class PaymentStatus(str, Enum):
      PAID = "paid"
      IN_ANALYSIS = "in_analysis"
      REFUSED = "refused"
      PROCESSING = "processing"
      AWAITING_PAYMENT = "awaiting_payment"
      CANCELLED = "cancelled"
      REFUNDED = "refunded"
      CHARGEBACK = "chargeback"
  ```

  ```typescript TypeScript theme={null}
  enum PaymentStatus {
    PAID = 'paid',
    IN_ANALYSIS = 'in_analysis',
    REFUSED = 'refused',
    PROCESSING = 'processing',
    AWAITING_PAYMENT = 'awaiting_payment',
    CANCELLED = 'cancelled',
    REFUNDED = 'refunded',
    CHARGEBACK = 'chargeback'
  }
  ```
</CodeGroup>

### Liquidation Status

Status de liquidação dos débitos junto aos Detrans:

| Status       | Descrição                    |
| ------------ | ---------------------------- |
| `pending`    | Liquidação pendente          |
| `processing` | Liquidação em processamento  |
| `settled`    | Débito liquidado com sucesso |
| `failed`     | Falha na liquidação          |
| `cancelled`  | Liquidação cancelada         |

<CodeGroup>
  ```javascript JavaScript theme={null}
  const LiquidationStatus = {
    PENDING: 'pending',
    PROCESSING: 'processing',
    SETTLED: 'settled',
    FAILED: 'failed',
    CANCELLED: 'cancelled'
  };
  ```

  ```python Python theme={null}
  class LiquidationStatus(str, Enum):
      PENDING = "pending"
      PROCESSING = "processing"
      SETTLED = "settled"
      FAILED = "failed"
      CANCELLED = "cancelled"
  ```
</CodeGroup>

## Tipos de Débito

### Debt Type

Tipos de débitos veiculares disponíveis:

| Tipo        | Descrição                                                | Exemplo                                    |
| ----------- | -------------------------------------------------------- | ------------------------------------------ |
| `ticket`    | Multa de trânsito                                        | Multas de velocidade, estacionamento, etc. |
| `ipva`      | IPVA (Imposto sobre Propriedade de Veículos Automotores) | IPVA anual, cota única ou parcelada        |
| `licensing` | Taxa de licenciamento                                    | Taxa anual de licenciamento                |
| `service`   | Taxa de serviço                                          | Multa de pátio, taxas diversas             |

<CodeGroup>
  ```javascript JavaScript theme={null}
  const DebtType = {
    TICKET: 'ticket',
    IPVA: 'ipva',
    LICENSING: 'licensing',
    SERVICE: 'service'
  };
  ```

  ```python Python theme={null}
  class DebtType(str, Enum):
      TICKET = "ticket"
      IPVA = "ipva"
      LICENSING = "licensing"
      SERVICE = "service"
  ```

  ```typescript TypeScript theme={null}
  enum DebtType {
    TICKET = 'ticket',
    IPVA = 'ipva',
    LICENSING = 'licensing',
    SERVICE = 'service'
  }
  ```
</CodeGroup>

## Métodos de Pagamento

### Payment Method

Métodos de pagamento aceitos:

| Método        | Descrição         | Características                            |
| ------------- | ----------------- | ------------------------------------------ |
| `credit_card` | Cartão de crédito | Parcelamento disponível (1x a 12x)         |
| `pix`         | PIX               | Pagamento instantâneo, aguarda confirmação |

<CodeGroup>
  ```javascript JavaScript theme={null}
  const PaymentMethod = {
    CREDIT_CARD: 'credit_card',
    PIX: 'pix'
  };
  ```

  ```python Python theme={null}
  class PaymentMethod(str, Enum):
      CREDIT_CARD = "credit_card"
      PIX = "pix"
  ```

  ```typescript TypeScript theme={null}
  enum PaymentMethod {
    CREDIT_CARD = 'credit_card',
    PIX = 'pix'
  }
  ```
</CodeGroup>

## Tipos de Resposta de Consulta

### Search Response Type

Tipos de resposta ao consultar débitos:

| Tipo                  | Descrição                                            |
| --------------------- | ---------------------------------------------------- |
| `debts`               | Veículo possui débitos pendentes                     |
| `VehicleWithoutDebts` | Veículo sem débitos                                  |
| `VehicleNotFound`     | Veículo não encontrado nos sistemas do Detran        |
| `search-error-event`  | Erro na consulta (indisponibilidade do Detran, etc.) |

<CodeGroup>
  ```javascript JavaScript theme={null}
  const SearchResponseType = {
    DEBTS: 'debts',
    VEHICLE_WITHOUT_DEBTS: 'VehicleWithoutDebts',
    VEHICLE_NOT_FOUND: 'VehicleNotFound',
    SEARCH_ERROR: 'search-error-event'
  };
  ```

  ```python Python theme={null}
  class SearchResponseType(str, Enum):
      DEBTS = "debts"
      VEHICLE_WITHOUT_DEBTS = "VehicleWithoutDebts"
      VEHICLE_NOT_FOUND = "VehicleNotFound"
      SEARCH_ERROR = "search-error-event"
  ```
</CodeGroup>

## Estados (UF)

### Brazilian States

Siglas dos estados brasileiros suportados:

<Tabs>
  <Tab title="Lista Completa">
    | UF   | Estado              |
    | ---- | ------------------- |
    | `AC` | Acre                |
    | `AL` | Alagoas             |
    | `AP` | Amapá               |
    | `AM` | Amazonas            |
    | `BA` | Bahia               |
    | `CE` | Ceará               |
    | `DF` | Distrito Federal    |
    | `ES` | Espírito Santo      |
    | `GO` | Goiás               |
    | `MA` | Maranhão            |
    | `MT` | Mato Grosso         |
    | `MS` | Mato Grosso do Sul  |
    | `MG` | Minas Gerais        |
    | `PA` | Pará                |
    | `PB` | Paraíba             |
    | `PR` | Paraná              |
    | `PE` | Pernambuco          |
    | `PI` | Piauí               |
    | `RJ` | Rio de Janeiro      |
    | `RN` | Rio Grande do Norte |
    | `RS` | Rio Grande do Sul   |
    | `RO` | Rondônia            |
    | `RR` | Roraima             |
    | `SC` | Santa Catarina      |
    | `SP` | São Paulo           |
    | `SE` | Sergipe             |
    | `TO` | Tocantins           |
  </Tab>

  <Tab title="Código">
    ```javascript JavaScript theme={null}
    const BrazilianStates = [
      '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'
    ];
    ```
  </Tab>
</Tabs>

<Note>
  **Limitações por Estado**: Alguns estados (GO, MA, MS, RS) retornam apenas IPVA em cota única. Consulte a [documentação de consulta de débitos](/consulta-debitos#limitacoes-por-estado) para mais detalhes.
</Note>

## Bandeiras de Cartão

### Card Brand

Bandeiras de cartão de crédito aceitas:

| Bandeira         | Código       |
| ---------------- | ------------ |
| Visa             | `visa`       |
| Mastercard       | `mastercard` |
| American Express | `amex`       |
| Elo              | `elo`        |
| Hipercard        | `hipercard`  |
| Diners Club      | `diners`     |

<CodeGroup>
  ```javascript JavaScript theme={null}
  const CardBrand = {
    VISA: 'visa',
    MASTERCARD: 'mastercard',
    AMEX: 'amex',
    ELO: 'elo',
    HIPERCARD: 'hipercard',
    DINERS: 'diners'
  };
  ```

  ```python Python theme={null}
  class CardBrand(str, Enum):
      VISA = "visa"
      MASTERCARD = "mastercard"
      AMEX = "amex"
      ELO = "elo"
      HIPERCARD = "hipercard"
      DINERS = "diners"
  ```
</CodeGroup>

## Códigos de Erro

### Error Codes

Códigos de erro específicos da API:

| Código | Descrição                                   | Solução                              |
| ------ | ------------------------------------------- | ------------------------------------ |
| `900`  | Serviço indisponível                        | Aguardar e tentar novamente          |
| `901`  | Timeout na consulta ao Detran               | Tentar novamente após alguns minutos |
| `902`  | Dados inconsistentes retornados pelo Detran | Verificar dados do veículo           |
| `903`  | Manutenção programada do Detran             | Aguardar fim da manutenção           |

<CodeGroup>
  ```javascript JavaScript theme={null}
  const ErrorCode = {
    SERVICE_UNAVAILABLE: '900',
    TIMEOUT: '901',
    INCONSISTENT_DATA: '902',
    SCHEDULED_MAINTENANCE: '903'
  };
  ```

  ```python Python theme={null}
  class ErrorCode(str, Enum):
      SERVICE_UNAVAILABLE = "900"
      TIMEOUT = "901"
      INCONSISTENT_DATA = "902"
      SCHEDULED_MAINTENANCE = "903"
  ```
</CodeGroup>

## HTTP Status Codes

### Status Codes Comuns

Códigos HTTP utilizados pela API:

<AccordionGroup>
  <Accordion title="2xx - Sucesso" icon="circle-check">
    | Código | Descrição                            |
    | ------ | ------------------------------------ |
    | `200`  | OK - Requisição bem-sucedida         |
    | `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>

## Validações e Regras

### Formatos de Dados

Formatos esperados para diferentes tipos de dados:

<CardGroup cols={2}>
  <Card title="Placa de Veículo" icon="car">
    **Formato**: `ABC1234` ou `ABC1D23` (Mercosul)

    * 7 caracteres
    * Com ou sem hífen
    * Letras maiúsculas
  </Card>

  <Card title="RENAVAM" icon="hashtag">
    **Formato**: `12345678901`

    * 11 dígitos numéricos
    * Validação de dígito verificador
  </Card>

  <Card title="CPF" icon="id-card">
    **Formato**: `12345678900`

    * 11 dígitos numéricos
    * Apenas números, sem pontos ou hífen
  </Card>

  <Card title="CNPJ" icon="building">
    **Formato**: `12345678000100`

    * 14 dígitos numéricos
    * Apenas números, sem pontos, barra ou hífen
  </Card>
</CardGroup>

### Limites e Restrições

| Campo                    | Limite     | Descrição                     |
| ------------------------ | ---------- | ----------------------------- |
| Parcelas                 | 1 a 12     | Número de parcelas permitido  |
| Valor mínimo por parcela | R\$ 5,00   | Valor mínimo de cada parcela  |
| Timeout de checkout      | 24 horas   | Tempo de validade do checkout |
| Timeout de PIX           | 30 minutos | Tempo para pagamento via PIX  |

## Exemplos de Uso

### Validação de Enum

<CodeGroup>
  ```javascript JavaScript theme={null}
  function isValidPaymentStatus(status) {
    const validStatuses = [
      'paid', 'in_analysis', 'refused', 'processing',
      'awaiting_payment', 'cancelled', 'refunded', 'chargeback'
    ];
    return validStatuses.includes(status);
  }

  // Uso
  if (isValidPaymentStatus(payment.status)) {
    console.log('Status válido:', payment.status);
  }
  ```

  ```python Python theme={null}
  def is_valid_debt_type(debt_type: str) -> bool:
      valid_types = ['ticket', 'ipva', 'licensing', 'service']
      return debt_type in valid_types

  # Uso
  if is_valid_debt_type(debt['type']):
      print(f'Tipo válido: {debt["type"]}')
  ```

  ```typescript TypeScript theme={null}
  function isValidPaymentMethod(method: string): method is PaymentMethod {
    return ['credit_card', 'pix'].includes(method);
  }

  // Uso com type guard
  if (isValidPaymentMethod(paymentData.method)) {
    processPayment(paymentData.method);
  }
  ```
</CodeGroup>

### Switch Case com ENUMs

<CodeGroup>
  ```javascript JavaScript theme={null}
  function handlePaymentStatus(status) {
    switch (status) {
      case 'paid':
        return liberarProduto();
      case 'in_analysis':
        return aguardarAnalise();
      case 'refused':
        return notificarRecusa();
      case 'awaiting_payment':
        return aguardarPagamento();
      default:
        return handleUnknownStatus(status);
    }
  }
  ```

  ```python Python theme={null}
  def handle_debt_type(debt_type: str):
      match debt_type:
          case 'ticket':
              return process_ticket()
          case 'ipva':
              return process_ipva()
          case 'licensing':
              return process_licensing()
          case 'service':
              return process_service()
          case _:
              raise ValueError(f'Tipo de débito desconhecido: {debt_type}')
  ```
</CodeGroup>

## Próximos Passos

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

  <Card title="Consulta de Débitos" icon="file-invoice" href="/consulta-debitos">
    Entenda os tipos de débito e status de resposta
  </Card>

  <Card title="Autenticação" icon="key" href="/autenticacao">
    Configure sua API Key para começar
  </Card>

  <Card title="Tratamento de Erros" icon="triangle-exclamation" href="/tratamento-erros">
    Aprenda a lidar com códigos de erro
  </Card>
</CardGroup>