Simulação e tabela de parcelas

A simulação calcula, para cada prazo, a prestação, o CET, o IOF e o cronograma completo de parcelas — sem criar proposta e sem persistir nada.

Endpoints

Endpoint	Escopo	Quando usar
`POST /v1/simulacao`	`simulacao:read`	Só os números. Não recebe CPF, então não avalia margem
`POST /v1/simulacao/margem`	`simulacao:read`	Igual, mais `cpf` + `cnpj_empregador`: cada cenário vem com `excede_margem`, avaliado contra a última consulta de margem do trio parceiro + CPF + empregador

POST /v1/simulacao/margem exige uma consulta de margem prévia para aquele empregador — sem ela, 422 CONSULTA_MARGEM_NAO_ENCONTRADA. Veja Fluxo completo.

O que cada campo monetário significa

Por cenário (item de resultados):

Campo	Significado
`valor_emprestado`	Valor líquido creditado ao trabalhador. Não é o saldo que a tabela amortiza
`iof`	IOF da operação. É financiado: entra no saldo devedor, não é descontado do líquido
`valor_juros_carencia`	Juros do período de carência (a parcela `numero: 0`). São capitalizados no saldo, não pagos
`valor_financiado`	Saldo devedor no início da amortização — o valor que a tabela de parcelas amortiza
`parcela_valor`	Prestação da primeira parcela paga (`numero: 1`)
`total_a_pagar`	Soma das prestações pagas (`numero >= 1`). A carência tem prestação zero e não soma
`cet_anual`	Custo Efetivo Total anual, em % a.a.
`taxa_mensal`	Taxa contratual usada no cálculo, em % a.m.
`excede_margem`	Só em `/v1/simulacao/margem`: `true` se `parcela_valor` supera a margem disponível

E por parcela (itens de parcelas):

Campo	Significado
`numero`	`0` é a carência; as parcelas pagas vão de `1` a `prazo`
`data_vencimento`	Vencimento da parcela (`YYYY-MM-DD`)
`dias`	Dias decorridos desde o marco anterior — na carência costuma ser > 30
`valor_saldo_anterior`	Saldo devedor antes desta parcela
`valor_juros`	Juros do período. Na carência, este valor é somado ao saldo
`valor_amortizacao`	Parte do saldo quitada por esta parcela. `0` na carência
`valor_parcela`	Prestação (juros + amortização). `0` na carência

A regra de reconciliação

Somar valor_amortizacao e comparar com valor_emprestado + iof não fecha. A diferença é exatamente valor_juros_carencia. A identidade correta é contra valor_financiado.


valor_financiado = valor_emprestado + iof + valor_juros_carencia
                   (+ CAD e seguro, quando financiados)

soma(parcelas[].valor_amortizacao) = valor_financiado

valor_financiado também é, por construção, o valor_saldo_anterior da parcela numero: 1. As duas igualdades valem a menos de centavos de arredondamento (cada parcela é arredondada em 2 casas) — ao conferir, use uma tolerância pequena, não igualdade exata.

Por que existe a carência

A primeira parcela paga não vence 30 dias após a liberação: ela vence no dia 28 da competência seguinte, respeitando o calendário de desconto em folha. O intervalo entre a liberação e esse primeiro vencimento é o período de carência e aparece como a parcela numero: 0, com valor_parcela: 0. Os juros desse período não são cobrados à vista — são capitalizados no saldo, que é o motivo de a tabela amortizar mais do que valor_emprestado + iof.

Exemplo numérico (prazo 36)

Grandeza	Valor
`valor_emprestado` (líquido)	1000,00
`iof` (financiado)	32,37
líquido + IOF	1032,37
`valor_juros_carencia` (parcela 0, 58 dias)	37,29
`valor_financiado`	1069,66
`soma(valor_amortizacao)` das 36 parcelas	1069,66 ✅
`total_a_pagar`	1460,36

Comparar 1069,66 com 1032,37 daria uma diferença de ~3,6% e pareceria erro de cálculo — mas é só a carência.


{
  "resultados": [
    {
      "prazo": 36,
      "valor_emprestado": 1000,
      "iof": 32.37,
      "valor_juros_carencia": 37.29,
      "valor_financiado": 1069.66,
      "parcela_valor": 40.56,
      "total_a_pagar": 1460.36,
      "cet_anual": 28.68,
      "taxa_mensal": 1.79,
      "parcelas": [
        {
          "numero": 0,
          "data_vencimento": "2026-09-28",
          "dias": 58,
          "valor_saldo_anterior": 1032.37,
          "valor_juros": 37.29,
          "valor_amortizacao": 0,
          "valor_parcela": 0
        },
        {
          "numero": 1,
          "data_vencimento": "2026-10-28",
          "dias": 30,
          "valor_saldo_anterior": 1069.66,
          "valor_juros": 19.15,
          "valor_amortizacao": 21.41,
          "valor_parcela": 40.56
        }
      ]
    }
  ]
}

O bloco acima está truncado: a resposta real traz as 37 linhas (carência + 36 parcelas). A soma de 1069,66 é sobre a tabela inteira.

`taxa_mensal` é opcional — e o default é do produto

taxa_mensal é enviada em percentual (1.79 = 1,79% a.m.) — a mesma unidade de todo campo de taxa da API, tanto no request quanto na resposta.

Omitida: a simulação usa a taxa contratual padrão do produto, 1,79% a.m. Ela não vem da linha de crédito nem de nenhuma configuração do seu cadastro.
Enviada: precisa respeitar a faixa taxa_minima/taxa_maxima da linha (também em percentual), senão 400 ERRO_VALIDACAO.

Recomendação: envie sempre taxa_mensal explicitamente, e use a mesma taxa na emissão (POST /v1/emprestimos) — assim a CCB sai idêntica ao que foi cotado.

Pré-requisitos e erros

Para simular basta a credencial com escopo simulacao:read e uma linha de crédito ativa. Nenhuma configuração extra do parceiro é lida na simulação — em particular, /v1/simulacao não depende de taxa padrão cadastrada.

Situação	Resposta
`numero_linha` inexistente para o parceiro	`404`
Linha inativa	`400` “Linha de crédito inativa.”
`valor` fora da faixa da linha	`400` “Valor fora da faixa permitida pela linha de crédito (mínimo/máximo: R$ …).”
Nenhum prazo dentro de `prazo_minimo`/`prazo_maximo`	`400` “Nenhum prazo válido para a linha de crédito selecionada.”
`taxa_mensal` fora da faixa da linha	`400`
`valor_seguro > 0` em linha sem seguro	`400` “Linha de crédito não aceita seguro.”
`/v1/simulacao/margem` sem consulta de margem do empregador	`422 CONSULTA_MARGEM_NAO_ENCONTRADA`

Consulte as faixas da linha em GET /v1/linhas-credito.

A cotação é reproduzível na emissão

A data do primeiro vencimento é derivada da data de liberação pela mesma regra de calendário usada na emissão da CCB (competência + dia 28). Simulando e emitindo com a mesma data_liberacao, valor, prazo e taxa_mensal, a prestação cotada é a prestação emitida.