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"
}
'import requests
url = "https://api.uvvipague.com.br/uvvi/v1/installments"
payload = {
"amount": 1302.86,
"paymentMethod": "credit_card"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({amount: 1302.86, paymentMethod: 'credit_card'})
};
fetch('https://api.uvvipague.com.br/uvvi/v1/installments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.uvvipague.com.br/uvvi/v1/installments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => 1302.86,
'paymentMethod' => 'credit_card'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.uvvipague.com.br/uvvi/v1/installments"
payload := strings.NewReader("{\n \"amount\": 1302.86,\n \"paymentMethod\": \"credit_card\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.uvvipague.com.br/uvvi/v1/installments")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 1302.86,\n \"paymentMethod\": \"credit_card\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.uvvipague.com.br/uvvi/v1/installments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 1302.86,\n \"paymentMethod\": \"credit_card\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"amount": 1302.86,
"installments": [
{
"number": 1,
"installmentAmount": 1315.89,
"totalAmount": 1315.89,
"interestRate": 1,
"interestAmount": 13.03
}
]
}
}{
"success": false,
"error": {
"code": "INVALID_REQUEST",
"message": "Parâmetros inválidos na requisição",
"details": {}
}
}Pagamentos
Simular Parcelas
Simula opções de parcelamento para um determinado valor, incluindo juros e valores totais
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"
}
'import requests
url = "https://api.uvvipague.com.br/uvvi/v1/installments"
payload = {
"amount": 1302.86,
"paymentMethod": "credit_card"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({amount: 1302.86, paymentMethod: 'credit_card'})
};
fetch('https://api.uvvipague.com.br/uvvi/v1/installments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.uvvipague.com.br/uvvi/v1/installments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => 1302.86,
'paymentMethod' => 'credit_card'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.uvvipague.com.br/uvvi/v1/installments"
payload := strings.NewReader("{\n \"amount\": 1302.86,\n \"paymentMethod\": \"credit_card\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.uvvipague.com.br/uvvi/v1/installments")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 1302.86,\n \"paymentMethod\": \"credit_card\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.uvvipague.com.br/uvvi/v1/installments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 1302.86,\n \"paymentMethod\": \"credit_card\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"amount": 1302.86,
"installments": [
{
"number": 1,
"installmentAmount": 1315.89,
"totalAmount": 1315.89,
"interestRate": 1,
"interestAmount": 13.03
}
]
}
}{
"success": false,
"error": {
"code": "INVALID_REQUEST",
"message": "Parâmetros inválidos na requisição",
"details": {}
}
}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
Exemplo de Cálculo de Juros
Exemplo de Cálculo de Juros
Para um valor de R$ 1.000,00:
- 1x: R1.010,00(1 1.010,00/mês
- 3x: R1.030,00(3 343,33/mês
- 6x: R1.060,00(6 176,67/mês
- 12x: R1.120,00(12 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 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
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
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
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
API Key fornecida no painel administrativo da Uvvipague
Body
application/json