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

# Simular Parcelas

> Simula opções de parcelamento para um determinado valor, incluindo juros e valores totais

## Descrição

Simula opções de parcelamento para um determinado valor, retornando todas as possibilidades de parcelas disponíveis com seus respectivos valores, juros e totais.

<Info>
  **Transparência Total**: A simulação mostra exatamente quanto o cliente pagará em cada parcela, incluindo juros e valor total da transação.
</Info>

## Quando Usar

Use este endpoint para:

* Exibir opções de parcelamento antes do checkout
* Calcular valores com juros para diferentes números de parcelas
* Permitir que o cliente escolha a melhor opção de pagamento
* Validar se o valor pode ser parcelado

## Fluxo de Uso

<Steps>
  <Step title="Consultar Débitos">
    Primeiro, consulte os débitos do veículo para obter o valor total.
  </Step>

  <Step title="Simular Parcelas">
    Envie o valor total para este endpoint para obter as opções de parcelamento.
  </Step>

  <Step title="Exibir ao Cliente">
    Mostre as opções de parcelamento para o cliente escolher.
  </Step>

  <Step title="Processar Pagamento">
    Use o número de parcelas escolhido no endpoint de pagamento.
  </Step>
</Steps>

## Regras de Parcelamento

### Limites de Parcelas

<CardGroup cols={2}>
  <Card title="Mínimo" icon="1">
    **1 parcela** (à vista)

    Pode incluir desconto ou juros mínimos
  </Card>

  <Card title="Máximo" icon="hashtag">
    **12 parcelas**

    Limite padrão para cartão de crédito
  </Card>
</CardGroup>

### Valor Mínimo por Parcela

<Warning>
  **Atenção**: O valor mínimo por parcela é de **R\$ 5,00**. Parcelas com valores inferiores não serão retornadas na simulação.
</Warning>

### Cálculo de Juros

Os juros são calculados de forma composta e variam conforme:

* **Número de parcelas**: Quanto mais parcelas, maior a taxa
* **Bandeira do cartão**: Algumas bandeiras têm taxas diferenciadas
* **Perfil do cliente**: Clientes enterprise podem ter taxas negociadas

<Accordion title="Exemplo de Cálculo de Juros">
  Para um valor de **R\$ 1.000,00**:

  * **1x**: R$ 1.010,00 (1% de juros) = R$ 1.010,00/mês
  * **3x**: R$ 1.030,00 (3% de juros) = R$ 343,33/mês
  * **6x**: R$ 1.060,00 (6% de juros) = R$ 176,67/mês
  * **12x**: R$ 1.120,00 (12% de juros) = R$ 93,33/mês

  <Note>
    As taxas são exemplificativas e podem variar conforme o contrato.
  </Note>
</Accordion>

## Estrutura da Resposta

Cada opção de parcelamento retorna:

* **number**: Número de parcelas
* **installmentAmount**: Valor de cada parcela
* **totalAmount**: Valor total a ser pago (com juros)
* **interestRate**: Taxa de juros aplicada (%)
* **interestAmount**: Valor total dos juros

## Exemplo de Uso

### Cenário: Cliente com débitos de R\$ 1.302,86

```javascript theme={null}
// 1. Consultar débitos (valor total: R$ 1.302,86)
const debts = await consultarDebitos(placa);

// 2. Simular parcelas
const response = await fetch('https://api.uvvipague.com.br/uvvi/v1/installments', {
  method: 'POST',
  headers: {
    'x-api-key': 'sua-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 1302.86,
    paymentMethod: 'credit_card'
  })
});

const { data } = await response.json();

// 3. Exibir opções ao cliente
data.installments.forEach(option => {
  console.log(`${option.number}x de R$ ${option.installmentAmount.toFixed(2)}`);
  console.log(`Total: R$ ${option.totalAmount.toFixed(2)}`);
  console.log(`Juros: ${option.interestRate}% (R$ ${option.interestAmount.toFixed(2)})`);
  console.log('---');
});
```

### Exemplo de Resposta

```json theme={null}
{
  "success": true,
  "data": {
    "amount": 1302.86,
    "installments": [
      {
        "number": 1,
        "installmentAmount": 1315.89,
        "totalAmount": 1315.89,
        "interestRate": 1.0,
        "interestAmount": 13.03
      },
      {
        "number": 2,
        "installmentAmount": 664.95,
        "totalAmount": 1329.90,
        "interestRate": 2.07,
        "interestAmount": 27.04
      },
      {
        "number": 3,
        "installmentAmount": 448.30,
        "totalAmount": 1344.90,
        "interestRate": 3.23,
        "interestAmount": 42.04
      }
      // ... até 12 parcelas
    ]
  }
}
```

## Interface de Usuário

### Boas Práticas para Exibição

<AccordionGroup>
  <Accordion title="Destaque a Melhor Opção" icon="star">
    Destaque visualmente a opção mais vantajosa (geralmente à vista ou com menos juros):

    ```jsx theme={null}
    {installments.map(option => (
      <div className={option.number === 1 ? 'highlight' : ''}>
        <span>{option.number}x de R$ {option.installmentAmount}</span>
        {option.number === 1 && <Badge>Recomendado</Badge>}
      </div>
    ))}
    ```
  </Accordion>

  <Accordion title="Mostre o Total com Juros" icon="calculator">
    Sempre exiba o valor total a ser pago, não apenas o valor da parcela:

    ```jsx theme={null}
    <div>
      <strong>{option.number}x de R$ {option.installmentAmount}</strong>
      <small>Total: R$ {option.totalAmount}</small>
    </div>
    ```
  </Accordion>

  <Accordion title="Indique Juros Claramente" icon="percent">
    Seja transparente sobre os juros aplicados:

    ```jsx theme={null}
    {option.interestRate > 0 && (
      <span className="interest">
        + {option.interestRate}% de juros
      </span>
    )}
    ```
  </Accordion>

  <Accordion title="Permita Comparação Fácil" icon="arrows-left-right">
    Use uma tabela ou lista para facilitar comparação:

    | Parcelas | Valor/Parcela | Total        | Juros |
    | -------- | ------------- | ------------ | ----- |
    | 1x       | R\$ 1.315,89  | R\$ 1.315,89 | 1%    |
    | 3x       | R\$ 448,30    | R\$ 1.344,90 | 3,23% |
    | 6x       | R\$ 231,65    | R\$ 1.389,90 | 6,68% |
  </Accordion>
</AccordionGroup>

## Métodos de Pagamento

Atualmente, apenas cartão de crédito é suportado:

```json theme={null}
{
  "paymentMethod": "credit_card"
}
```

<Note>
  **Em Breve**: Suporte para PIX e boleto bancário será adicionado em versões futuras da API.
</Note>

## Códigos de Resposta HTTP

### 200 - Sucesso

Simulação realizada com sucesso. Todas as opções de parcelamento disponíveis são retornadas.

### 400 - Bad Request

Dados inválidos na requisição. Possíveis motivos:

* Valor inválido ou negativo
* Método de pagamento não suportado
* Formato de dados incorreto

### 422 - Unprocessable Entity

Valor não pode ser parcelado:

* Valor muito baixo (mínimo R\$ 5,00)
* Valor excede limite de parcelamento

## Cache e Performance

<Tip>
  **Otimização**: Os resultados de simulação podem ser cacheados por alguns minutos, pois as taxas de juros não mudam frequentemente. Isso melhora a performance da sua aplicação.
</Tip>

```javascript theme={null}
// Exemplo de cache simples
const cacheKey = `installments_${amount}`;
const cached = cache.get(cacheKey);

if (cached) {
  return cached;
}

const result = await simularParcelas(amount);
cache.set(cacheKey, result, 300); // Cache por 5 minutos
return result;
```

## Integração com Checkout

Após o cliente escolher o número de parcelas:

```javascript theme={null}
// Cliente escolheu 3 parcelas
const selectedInstallments = 3;

// Processar pagamento com o número de parcelas escolhido
const payment = await fetch('https://api.uvvipague.com.br/uvvi/v1/payment', {
  method: 'POST',
  headers: {
    'x-api-key': 'sua-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    checkoutId: 'chk_abc123',
    cardToken: 'tok_xyz789',
    installments: selectedInstallments
  })
});
```

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Tokenizar Cartão" icon="credit-card" href="/api-reference/endpoint/card-token">
    Tokenize o cartão do cliente de forma segura
  </Card>

  <Card title="Processar Pagamento" icon="money-bill-wave" href="/api-reference/endpoint/payment">
    Efetue o pagamento com as parcelas escolhidas
  </Card>

  <Card title="Criar Checkout" icon="shopping-cart" href="/api-reference/endpoint/create">
    Crie um checkout antes de processar o pagamento
  </Card>

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

## Suporte

<Card title="Dúvidas sobre Parcelamento?" icon="headset" href="mailto:suporte@uvvipague.com.br">
  Entre em contato para esclarecer dúvidas sobre taxas, limites e parcelamento.
</Card>


## OpenAPI

````yaml POST /uvvi/v1/installments
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:
  /uvvi/v1/installments:
    post:
      tags:
        - Pagamentos
      summary: Simular Parcelas
      description: >-
        Simula opções de parcelamento para um determinado valor, incluindo juros
        e valores totais
      operationId: simulateInstallments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstallmentsRequest'
      responses:
        '200':
          description: Simulação realizada com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallmentsResponse'
        '400':
          description: Requisição inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    InstallmentsRequest:
      type: object
      required:
        - amount
        - paymentMethod
      properties:
        amount:
          type: number
          format: double
          description: Valor total a ser parcelado
          example: 1302.86
        paymentMethod:
          type: string
          description: Método de pagamento
          enum:
            - credit_card
          example: credit_card
    InstallmentsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            amount:
              type: number
              example: 1302.86
            installments:
              type: array
              items:
                type: object
                properties:
                  number:
                    type: integer
                    example: 1
                  installmentAmount:
                    type: number
                    example: 1315.89
                  totalAmount:
                    type: number
                    example: 1315.89
                  interestRate:
                    type: number
                    example: 1
                  interestAmount:
                    type: number
                    example: 13.03
    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

````