Skip to main content
POST
/
uvvi
/
v1
/
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

1

Consultar Débitos

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

Simular Parcelas

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

Exibir ao Cliente

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

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
Para um valor de R$ 1.000,00:
  • 1x: R1.010,00(1 1.010,00 (1% de juros) = R 1.010,00/mês
  • 3x: R1.030,00(3 1.030,00 (3% de juros) = R 343,33/mês
  • 6x: R1.060,00(6 1.060,00 (6% de juros) = R 176,67/mês
  • 12x: R1.120,00(12 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 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>
))}
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>
Seja transparente sobre os juros aplicados:
{option.interestRate > 0 && (
  <span className="interest">
    + {option.interestRate}% de juros
  </span>
)}
Use uma tabela ou lista para facilitar comparação:
ParcelasValor/ParcelaTotalJuros
1xR$ 1.315,89R$ 1.315,891%
3xR$ 448,30R$ 1.344,903,23%
6xR$ 231,65R$ 1.389,906,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

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