Simular Parcelas

curl --request POST \
  --url https://api.uvvipague.com.br/uvvi/v1/installments \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "amount": 1302.86,
  "paymentMethod": "credit_card"
}
'

{
  "success": true,
  "data": {
    "amount": 1302.86,
    "installments": [
      {
        "number": 1,
        "installmentAmount": 1315.89,
        "totalAmount": 1315.89,
        "interestRate": 1,
        "interestAmount": 13.03
      }
    ]
  }
}

POST

uvvi

installments

Simular Parcelas

curl --request POST \
  --url https://api.uvvipague.com.br/uvvi/v1/installments \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "amount": 1302.86,
  "paymentMethod": "credit_card"
}
'

{
  "success": true,
  "data": {
    "amount": 1302.86,
    "installments": [
      {
        "number": 1,
        "installmentAmount": 1315.89,
        "totalAmount": 1315.89,
        "interestRate": 1,
        "interestAmount": 13.03
      }
    ]
  }
}

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.

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

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

Consultar Débitos

Primeiro, consulte os débitos do veículo para obter o valor total.

Simular Parcelas

Envie o valor total para este endpoint para obter as opções de parcelamento.

Exibir ao Cliente

Mostre as opções de parcelamento para o cliente escolher.

Processar Pagamento

Use o número de parcelas escolhido no endpoint de pagamento.

Regras de Parcelamento

Limites de Parcelas

Mínimo

1 parcela (à vista)Pode incluir desconto ou juros mínimos

Máximo

12 parcelasLimite padrão para cartão de crédito

Valor Mínimo por Parcela

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

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

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

As taxas são exemplificativas e podem variar conforme o contrato.

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

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

{
  "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

Destaque a Melhor Opção

Destaque visualmente a opção mais vantajosa (geralmente à vista ou com menos juros):

{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>
))}

Mostre o Total com Juros

Sempre exiba o valor total a ser pago, não apenas o valor da parcela:

<div>
  <strong>{option.number}x de R$ {option.installmentAmount}</strong>
  <small>Total: R$ {option.totalAmount}</small>
</div>

Indique Juros Claramente

Seja transparente sobre os juros aplicados:

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

Permita Comparação Fácil

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%

Métodos de Pagamento

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

{
  "paymentMethod": "credit_card"
}

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

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

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.

// 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:

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

Tokenizar Cartão

Tokenize o cartão do cliente de forma segura

Processar Pagamento

Efetue o pagamento com as parcelas escolhidas

Criar Checkout

Crie um checkout antes de processar o pagamento

Fluxo Completo

Veja o fluxo completo de integração

Suporte

Dúvidas sobre Parcelamento?

Entre em contato para esclarecer dúvidas sobre taxas, limites e parcelamento.

Authorizations

x-api-key

string

header

required

API Key fornecida no painel administrativo da Uvvipague

Body

application/json

amount

number<double>

required

Valor total a ser parcelado

Example:

1302.86

paymentMethod

enum<string>

required

Método de pagamento

Available options:

credit_card

Example:

"credit_card"

Response

Simulação realizada com sucesso

success

boolean

Example:

true

data

object

Show child attributes

Tokenizar Cartão Processar Pagamento

​Descrição

​Quando Usar

​Fluxo de Uso

​Regras de Parcelamento

​Limites de Parcelas

Mínimo

Máximo

​Valor Mínimo por Parcela

​Cálculo de Juros

​Estrutura da Resposta

​Exemplo de Uso

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

​Exemplo de Resposta

​Interface de Usuário

​Boas Práticas para Exibição

​Métodos de Pagamento

​Códigos de Resposta HTTP

​200 - Sucesso

​400 - Bad Request

​422 - Unprocessable Entity

​Cache e Performance

​Integração com Checkout

​Próximos Passos

Tokenizar Cartão

Processar Pagamento

Criar Checkout

Fluxo Completo

​Suporte

Dúvidas sobre Parcelamento?

Authorizations

Body

Response

Descrição

Quando Usar

Fluxo de Uso

Regras de Parcelamento

Limites de Parcelas

Valor Mínimo por Parcela

Cálculo de Juros

Estrutura da Resposta

Exemplo de Uso

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

Exemplo de Resposta

Interface de Usuário

Boas Práticas para Exibição

Métodos de Pagamento

Códigos de Resposta HTTP

200 - Sucesso

400 - Bad Request

422 - Unprocessable Entity

Cache e Performance

Integração com Checkout

Próximos Passos

Suporte