Simulação de Parcelas

Visão Geral

A API de Simulação de Parcelas permite calcular as opções de parcelamento disponíveis para um determinado valor, incluindo juros e valores totais. Esta funcionalidade é essencial para apresentar ao usuário as opções de pagamento antes de finalizar a transação.

Transparência: Mostre ao usuário todas as opções de parcelamento com valores exatos antes de processar o pagamento.

Importante: Todos os pagamentos possuem juros aplicados, incluindo pagamento à vista (1x) e PIX. As taxas variam conforme o método de pagamento e número de parcelas.

Quando Usar

A simulação de parcelas deve ser usada:

Antes do Checkout

Mostre as opções de parcelamento antes do usuário confirmar a compra

Cálculo de Juros

Apresente de forma transparente os juros aplicados em cada opção

Comparação de Valores

Permita que o usuário compare o valor à vista vs parcelado

Melhor Experiência

Ofereça uma experiência completa mostrando todas as possibilidades

Endpoint

POST /uvvi/v1/installments

Parâmetros

amount

number

required

Valor total a ser parcelado em reais (formato decimal)Exemplo: 1302.86

paymentMethod

string

required

Método de pagamento para simular. Atualmente suportado: credit_card

Limites e Restrições

Valor Mínimo por Parcela

R$ 5,00Cada parcela deve ter no mínimo R$ 5,00. Parcelas com valores inferiores não serão disponibilizadas.

Quantidade de Parcelas

1 a 12 parcelasO número máximo de parcelas depende do valor total dividido pelo valor mínimo de R$ 5,00.

Juros Aplicados

Todos os pagamentosJuros são aplicados em todas as formas de pagamento, incluindo 1x e PIX.

Cálculo Dinâmico

AutomáticoA API retorna apenas as opções de parcelamento válidas conforme o valor informado.

Exemplo de Requisição

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

Resposta

{
  "success": true,
  "amount": 1302.86,
  "installments": [
    {
      "number": 1,
      "installmentAmount": 1342.95,
      "totalAmount": 1342.95,
      "interestRate": 3.08,
      "interestAmount": 40.09
    },
    {
      "number": 2,
      "installmentAmount": 676.49,
      "totalAmount": 1352.98,
      "interestRate": 3.84,
      "interestAmount": 50.12
    },
    {
      "number": 3,
      "installmentAmount": 467.95,
      "totalAmount": 1403.85,
      "interestRate": 7.75,
      "interestAmount": 100.99
    },
    {
      "number": 4,
      "installmentAmount": 363.46,
      "totalAmount": 1453.84,
      "interestRate": 11.59,
      "interestAmount": 150.98
    },
    {
      "number": 5,
      "installmentAmount": 301.18,
      "totalAmount": 1505.90,
      "interestRate": 15.58,
      "interestAmount": 203.04
    },
    {
      "number": 6,
      "installmentAmount": 259.65,
      "totalAmount": 1557.90,
      "interestRate": 19.57,
      "interestAmount": 255.04
    },
    {
      "number": 7,
      "installmentAmount": 229.93,
      "totalAmount": 1609.51,
      "interestRate": 23.53,
      "interestAmount": 306.65
    },
    {
      "number": 8,
      "installmentAmount": 207.64,
      "totalAmount": 1661.12,
      "interestRate": 27.49,
      "interestAmount": 358.26
    },
    {
      "number": 9,
      "installmentAmount": 190.74,
      "totalAmount": 1716.66,
      "interestRate": 31.76,
      "interestAmount": 413.80
    },
    {
      "number": 10,
      "installmentAmount": 177.56,
      "totalAmount": 1775.60,
      "interestRate": 36.29,
      "interestAmount": 472.74
    },
    {
      "number": 11,
      "installmentAmount": 167.00,
      "totalAmount": 1837.00,
      "interestRate": 41.00,
      "interestAmount": 534.14
    },
    {
      "number": 12,
      "installmentAmount": 158.40,
      "totalAmount": 1900.80,
      "interestRate": 45.90,
      "interestAmount": 597.94
    }
  ]
}

Exemplos de Valores e Parcelas Disponíveis

A quantidade de parcelas disponíveis varia conforme o valor total:

Valor Total	Parcelas Disponíveis	Motivo
R$ 30,00	1x a 6x	Máximo 6x (R $30,00 ÷ R$ 5,00 = 6)
R$ 50,00	1x a 10x	Máximo 10x (R $50,00 ÷ R$ 5,00 = 10)
R$ 100,00	1x a 12x	Valor permite 20x, mas limite é 12x
R$ 1.302,86	1x a 12x	Valor permite todas as 12 parcelas

Importante: A API retorna automaticamente apenas as opções válidas. Não é necessário calcular manualmente quais parcelas estão disponíveis.

Estrutura da Resposta

success

boolean

Indica se a simulação foi realizada com sucesso

amount

number

Valor original solicitado para simulação

installments

array

Lista de opções de parcelamento disponíveis

Objeto Installment

Cada opção de parcelamento contém:

number

Número de parcelas (1 a 12)

installmentAmount

number

Valor de cada parcela em reais

totalAmount

number

Valor total a ser pago (com juros)

interestRate

number

Taxa de juros aplicada em percentual

interestAmount

number

Valor total dos juros em reais

Regras de Parcelamento

Valor Mínimo da Parcela

O valor mínimo permitido por parcela é de R$ 5,00

Parcelas inferiores a R$ 5,00 não serão retornadas na simulação
O número máximo de parcelas é calculado automaticamente com base no valor total
Exemplo: Um valor de R $30,00 permite no máximo 6 parcelas de R$ 5,00 cada

Quantidade de Parcelas

O parcelamento é limitado entre 1 e 12 parcelas

Mínimo: 1 parcela (pagamento à vista)
Máximo: 12 parcelas
A quantidade disponível depende do valor total e do valor mínimo por parcela
Apenas parcelas válidas são retornadas na resposta da API

Aplicação de Juros

Todos os métodos de pagamento possuem juros aplicados

Pagamento à vista (1x): Taxa de juros aplicada
Parcelamento (2x a 12x): Taxa de juros progressiva conforme número de parcelas
PIX: Taxa de juros aplicada no momento do pagamento
As taxas são calculadas e retornadas automaticamente pela API

Cálculo Automático

A API calcula automaticamente as opções disponíveis

Considera o valor total informado
Aplica o valor mínimo de R$ 5,00 por parcela
Calcula juros conforme tabela vigente
Retorna apenas opções válidas e disponíveis

Exemplo de Interface

Veja como apresentar as opções de parcelamento ao usuário:

import React, { useState, useEffect } from 'react';

function InstallmentSelector({ amount, onSelect }) {
  const [installments, setInstallments] = useState([]);
  const [selected, setSelected] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetchInstallments();
  }, [amount]);

  const fetchInstallments = async () => {
    try {
      const response = await fetch('/api/installments', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ 
          amount, 
          paymentMethod: 'credit_card' 
        })
      });
      
      const data = await response.json();
      setInstallments(data.installments);
      setSelected(data.installments[0]); // Seleciona 1x por padrão
    } catch (error) {
      console.error('Erro ao buscar parcelas:', error);
    } finally {
      setLoading(false);
    }
  };

  const handleSelect = (option) => {
    setSelected(option);
    onSelect(option);
  };

  if (loading) return <div>Carregando opções...</div>;

  return (
    <div className="installment-selector">
      <h3>Escolha a forma de pagamento</h3>
      
      {installments.map((option) => (
        <div
          key={option.number}
          className={`installment-option ${selected?.number === option.number ? 'selected' : ''}`}
          onClick={() => handleSelect(option)}
        >
          <div className="installment-info">
            <strong>
              {option.number}x de R$ {option.installmentAmount.toFixed(2)}
            </strong>
            <span className="interest">
              Total: R$ {option.totalAmount.toFixed(2)} 
              ({option.interestRate.toFixed(2)}% de juros)
            </span>
          </div>
        </div>
      ))}
    </div>
  );
}

export default InstallmentSelector;

Boas Práticas

Simule Antes do Checkout

Sempre simule as parcelas antes de criar o checkout para mostrar opções atualizadas ao usuário.

Destaque a Melhor Opção

Evidencie visualmente a opção com menor taxa de juros ou mais vantajosa para o cliente.

Mostre o Total

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

Seja Transparente

Mostre claramente a taxa de juros e o valor dos juros em reais.

Pré-selecione uma Opção

Deixe uma opção pré-selecionada (recomendado: 1x ou a opção mais popular).

Cache Inteligente

Considere cachear a simulação por alguns minutos para o mesmo valor, evitando chamadas desnecessárias.

Códigos de Erro

400

Bad Request

Parâmetros inválidos (valor negativo, método de pagamento não suportado, etc.)

401

Unauthorized

API Key inválida ou ausente

429

Too Many Requests

Limite de requisições excedido

500

Server Error

Erro interno do servidor

Exemplo de Erro

{
  "success": false,
  "error": "Bad Request",
  "message": "O valor deve ser maior que zero",
  "statusCode": 400
}

Fluxo Recomendado

Integração com Checkout

Após o usuário selecionar a opção de parcelamento, use o número de parcelas no pagamento:

// 1. Simular parcelas
const simulacao = await simularParcelas(1302.86);

// 2. Usuário seleciona 3 parcelas
const parcelasSelecionadas = 3;

// 3. Criar checkout
const checkout = await criarCheckout({ debts: [...] });

// 4. Efetuar pagamento com as parcelas selecionadas
const pagamento = await efetuarPagamento({
  checkoutId: checkout.checkoutId,
  paymentMethod: 'credit_card',
  cardToken: token,
  installments: parcelasSelecionadas  // Usa o número selecionado
});

Próximos Passos

Fluxo Completo

Veja como integrar a simulação no fluxo completo de pagamento

Efetuar Pagamento

Aprenda como processar o pagamento com as parcelas selecionadas

Autenticação

Configure sua API Key para começar

Tratamento de Erros

Aprenda a lidar com erros

Começando

Funcionalidades

Referência

Simulação de Parcelas

Visão Geral

Quando Usar

Antes do Checkout

Cálculo de Juros

Comparação de Valores

Melhor Experiência

Endpoint

Parâmetros

Limites e Restrições

Valor Mínimo por Parcela

Quantidade de Parcelas

Juros Aplicados

Cálculo Dinâmico

Exemplo de Requisição

Resposta

Exemplos de Valores e Parcelas Disponíveis

Estrutura da Resposta

Objeto Installment

Regras de Parcelamento

Exemplo de Interface

Boas Práticas

Códigos de Erro

Exemplo de Erro

Fluxo Recomendado

Integração com Checkout

Próximos Passos

Fluxo Completo

Efetuar Pagamento

Autenticação

Tratamento de Erros

Começando

Funcionalidades

Referência

​Visão Geral

​Quando Usar

Antes do Checkout

Cálculo de Juros

Comparação de Valores

Melhor Experiência

​Endpoint

​Parâmetros

​Limites e Restrições

Valor Mínimo por Parcela

Quantidade de Parcelas

Juros Aplicados

Cálculo Dinâmico

​Exemplo de Requisição

​Resposta

​Exemplos de Valores e Parcelas Disponíveis

​Estrutura da Resposta

​Objeto Installment

​Regras de Parcelamento

​Exemplo de Interface

​Boas Práticas

​Códigos de Erro

​Exemplo de Erro

​Fluxo Recomendado

​Integração com Checkout

​Próximos Passos

Fluxo Completo

Efetuar Pagamento

Autenticação

Tratamento de Erros

Visão Geral

Quando Usar

Endpoint

Parâmetros

Limites e Restrições

Exemplo de Requisição

Resposta

Exemplos de Valores e Parcelas Disponíveis

Estrutura da Resposta

Objeto Installment

Regras de Parcelamento

Exemplo de Interface

Boas Práticas

Códigos de Erro

Exemplo de Erro

Fluxo Recomendado

Integração com Checkout

Próximos Passos