5.1. Simular¶

Especificação — em construção

Os serviços descritos nesta área ainda não estão disponíveis.

🔗 Endpoint¶

Método	URL
	`/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 — que é assíncrona.

🔹 Path Parameter¶

Parâmetro	Tipo	Descrição
idEsteira	integer	Identificador da esteira, obtido em 3.1

📤 Requisição¶

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

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

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

🧪 Exemplo de cURL¶

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¶

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

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

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