---
title: 5.1. Simular
url: https://docs.vehub.com.br/Emiss%C3%A3o%20de%20Ativos/API/Cr%C3%A9dito/5.%20Simula%C3%A7%C3%A3o/5.1.%20Simular/
---
# 5.1. Simular

!!! warning "Especificação — em construção"
    Os serviços descritos nesta área ainda não estão disponíveis.

## 🔗 Endpoint

| Método | URL |
|--------|-----|
| ![POST](https://img.shields.io/badge/POST-blue) | `/credito/esteiras/{idEsteira}/simulacao` |

---

## 🧾 Descrição

Calcula uma operação de crédito e devolve o **fluxo completo de parcelas**, o CET, o IOF e os totais.

Este endpoint é **síncrono** e de **leitura apenas** — não cria proposta, não cadastra tomador, não
deixa nenhum registro. É o serviço para negociar com o cliente: itere valor, prazo e taxa quantas
vezes precisar e só crie a proposta quando as condições forem aceitas.

Para gravar as condições em uma proposta existente, use
[6.2. Simulação da Proposta](../6.%20Proposta/6.2.%20Simulação%20da%20Proposta.md) — que é
assíncrona.

### 🔹 Path Parameter

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| idEsteira | integer | Identificador da esteira, obtido em [3.1](../3.%20Referências/3.1.%20Esteiras.md) |

---

## 📤 Requisição

### 📋 Payload — por valor financiado (`tipoSimulacao = 1`)

```json
{
  "tipoPessoa": 1,
  "tipoSimulacao": 1,
  "valor": 18000.00,
  "taxa": 1.99,
  "quantidadeParcelas": 24,
  "dataPrimeiroVencimento": "2026-10-10",
  "fluxoIrregular": false,
  "valorSeguro": null,
  "valorOutrasDespesas": null,
  "valorOutrosServicos": null
}
```

### 📋 Payload — por valor da parcela (`tipoSimulacao = 2`)

Quando o cliente chega pela parcela — *"quanto cabe no meu bolso por mês?"* — informe a PMT desejada
e receba o valor financiável.

```json
{
  "tipoPessoa": 1,
  "tipoSimulacao": 2,
  "valorParcela": 850.00,
  "taxa": 1.99,
  "quantidadeParcelas": 24,
  "dataPrimeiroVencimento": "2026-10-10"
}
```

### 🧾 Detalhamento dos Campos

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| tipoPessoa | integer | Sim | `1` PF, `2` PJ. Precisa respeitar `tipoPessoaPermitida` da esteira |
| tipoSimulacao | integer | Não | `1` por valor financiado (padrão), `2` por valor da parcela |
| valor | number | Se `tipoSimulacao = 1` | Valor financiado. Dentro de `valorMinimo`..`valorMaximo` |
| valorParcela | number | Se `tipoSimulacao = 2` | Valor da prestação desejada. Maior que zero |
| taxa | number | Sim | Taxa de juros **mensal** em percentual (`1.99` = 1,99% a.m.). Dentro de `jurosMinimo`..`jurosMaximo` |
| quantidadeParcelas | integer | Sim | Número de parcelas. Dentro de `prazoMinimoMeses`..`prazoMaximoMeses` |
| dataPrimeiroVencimento | string | Não | Vencimento da 1ª parcela. **Vale nos dois modos**. Ajustada para o próximo dia útil |
| fluxoIrregular | boolean | Não | `false` por padrão. **Não é compatível com `tipoSimulacao = 2`** |
| nroDiasIntervaloPrazo | integer | Se `fluxoIrregular = true` | Intervalo em dias entre parcelas. Ver [5.2](5.2.%20Fluxo%20Regular%20e%20Irregular.md) |
| valorSeguro | number | Não | Ausente ⇒ usa o default da esteira. `0` ⇒ zero |
| valorOutrasDespesas | number | Não | Ausente ⇒ default da esteira. `0` ⇒ zero |
| valorOutrosServicos | number | Não | Ausente ⇒ default da esteira. `0` ⇒ zero |

> **Sobre os custos:** os três campos entram no cálculo do **IOF e do CET**. Omitir é diferente de
> zerar: omitido aplica o valor configurado na esteira, `0` força zero. Se você quer o CET real da
> operação, informe os custos que vai cobrar.

> **Sobre a taxa:** você informa livremente dentro da faixa da esteira. Se não tem taxa negociada,
> use `jurosPadrao` de
> [3.2](../3.%20Referências/3.2.%20Parâmetros%20da%20Esteira.md).

---

## 🧪 Exemplo de cURL

```bash
curl -X POST "https://api.vehub.com.br/credito/esteiras/12/simulacao" \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Content-Type: application/json" \
  -d '{
    "tipoPessoa": 1,
    "tipoSimulacao": 1,
    "valor": 18000.00,
    "taxa": 1.99,
    "quantidadeParcelas": 24,
    "dataPrimeiroVencimento": "2026-10-10"
  }'
```

---

## 📥 Responses

### ✅ 200 OK

```json
{
  "sucesso": true,
  "mensagem": null,
  "dados": {
    "taxa": 1.99,
    "valorSolicitado": 18000.00,
    "quantidadeParcelas": 24,
    "cet": {
      "valor": 2563.20,
      "percentualMensal": 2.10,
      "percentualAnual": 28.30
    },
    "juros": {
      "valor": 2150.60,
      "percentualMensal": 1.99,
      "percentualAnual": 26.65
    },
    "iof": {
      "valor": 412.30,
      "percentual": 2.31
    },
    "totais": {
      "parcela": 850.00,
      "valorTotal": 20400.00,
      "valorDesembolso": 18000.00
    },
    "parcelas": [
      {
        "numero": 1,
        "dataVencimento": "2026-10-13",
        "valor": 850.00,
        "amortizacao": 495.28,
        "juros": 354.72,
        "saldoDevedor": 17325.17
      },
      {
        "numero": 2,
        "dataVencimento": "2026-11-10",
        "valor": 850.00,
        "amortizacao": 505.14,
        "juros": 344.86,
        "saldoDevedor": 16820.03
      }
    ]
  }
}
```

### 🧾 Detalhamento — `dados`

| Campo | Tipo | Descrição |
|-------|------|-----------|
| taxa | number | Taxa mensal aplicada |
| valorSolicitado | number | Valor financiado. No modo `2`, é o valor **calculado** a partir da parcela |
| quantidadeParcelas | integer | Número de parcelas |
| cet | object | Custo Efetivo Total |
| juros | object | Juros da operação |
| iof | object | IOF |
| totais | object | Valores consolidados |
| parcelas | array | Fluxo de pagamento parcela a parcela |

### 🧾 Detalhamento — `cet` e `juros`

| Campo | Tipo | Descrição |
|-------|------|-----------|
| valor | number | Valor em reais |
| percentualMensal | number | Percentual ao mês |
| percentualAnual | number | Percentual ao ano |

### 🧾 Detalhamento — `iof`

| Campo | Tipo | Descrição |
|-------|------|-----------|
| valor | number | IOF em reais |
| percentual | number | IOF em percentual sobre a operação |

### 🧾 Detalhamento — `totais`

| Campo | Tipo | Descrição |
|-------|------|-----------|
| parcela | number | Valor da prestação |
| valorTotal | number | Total a pagar ao longo da operação |
| valorDesembolso | number | Valor efetivamente liberado ao destinatário do desembolso |

### 🧾 Detalhamento — `parcelas[]`

| Campo | Tipo | Descrição |
|-------|------|-----------|
| numero | integer | Número sequencial da parcela |
| dataVencimento | string | Vencimento, já ajustado para dia útil |
| valor | number | Valor da prestação |
| amortizacao | number | Parcela de amortização do principal |
| juros | number | Parcela de juros |
| saldoDevedor | number | Saldo devedor após o pagamento |

### ❌ 400 Bad Request

```json
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "status": 400,
  "errors": [
    { "campo": "taxa", "mensagem": "Deve estar entre 1,50 e 3,50." },
    { "campo": "quantidadeParcelas", "mensagem": "Deve estar entre 6 e 48." }
  ]
}
```

### ❌ 422 Unprocessable Entity

Erro de política devolvido pela bancarizadora:

```json
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.21",
  "status": 422,
  "errors": [
    { "campo": null, "mensagem": "Prazo informado é inválido para o produto." }
  ]
}
```

---

## ⚠️ Observações

- **PRICE é o único sistema de amortização.** SAC não está disponível em EP/CDC. Carência também
  não.
- **Cada chamada consome cota do convênio com a bancarizadora**, inclusive em homologação. Respeite
  o limite de 100 requisições por minuto e evite laços de simulação automatizados.
- A `dataVencimento` da resposta pode diferir da `dataPrimeiroVencimento` que você informou, porque
  as datas são ajustadas para o **próximo dia útil**.
- No modo `2` (por valor da parcela) o `valorSolicitado` devolvido é o resultado do cálculo. Verifique
  se ele está dentro de `valorMinimo`..`valorMaximo` da esteira antes de criar a proposta — a
  simulação avulsa não bloqueia esse caso.