Simulações de Crédito

Visão Geral

Esta rota realiza uma simulação de proposta de crédito para um produto específico. A API retorna o id da simulação, além de todos os parâmetros calculados — como valor financiado, IOF, cronograma de parcelas e taxas — que serão utilizados na etapa de criação da solicitação formal de crédito.

Campo	Valor
Ambiente	Sandbox
Base URL	`https://sandbox.platform.flowfinance.com.br`
Autenticação	Bearer Token (OAuth2 — Keycloak)
Content-Type	`application/json`
Retorno-chave	`id` — UUID da simulação, usar em `POST /applications

Requisição

POST /banking/originator/products/{product_id}/preview

Path Parameter

Parâmetro	Tipo	Obrigatório	Descrição
`product_id`	UUID	Sim	Identificador único do produto de crédito.

Headers

Header	Tipo	Obrigatório	Descrição
`Authorization`	string	Sim	`Bearer <token>` — JWT obtido via Keycloak.
`Content-Type`	string	Sim	Deve ser `application/json`.

Body

Campo de valor — obrigatório (escolha exatamente um)

A simulação exige que exatamente um dos campos abaixo seja informado. A API utiliza o campo fornecido como âncora do cálculo e deriva os demais automaticamente.

Campo	Tipo	Descrição
`total_amount_owed`	number	Âncora pelo total a pagar: soma de todas as parcelas (principal + juros + IOF).
`financed_amount`	number	Âncora pelo valor financiado: principal acrescido do IOF capitalizado.
`payment_value`	number	Âncora pelo valor da parcela: a API calcula o contrato a partir da prestação desejada.
`requested_amount`	number	Âncora pelo valor solicitado: valor líquido a ser desembolsado ao tomador.

⚠️
Enviar mais de um desses campos ou nenhum deles resultará em erro de validação.

Demais campos obrigatórios

Campo	Tipo	Obrigatório	Descrição
`interest_rate`	number	Sim	Taxa de juros mensal (decimal). Ex.: `0.13` = 13% a.m.
`tac_amount`	number	Sim	Tarifa de cadastro (TAC). Informar `0` se isento.
`finance_fee`	number	Sim	Outros custos. Informar `0` se isento.
`insurance_amount`	number	Sim	Valor de seguro embutido. Informar `0` se isento.
`num_payments`	integer	Sim	Número de parcelas do contrato.
`first_payment_date`	string	Sim	Data do primeiro vencimento no formato `YYYY-MM-DD`.
`disbursement_date`	string	Sim	Data de desembolso do crédito no formato `YYYY-MM-DD`.
`schedule_type`	string	Sim	Frequência das parcelas. Valor aceito: `"MONTHLY"`.
`iof_type`	string	Sim	Tipo de IOF aplicado. Valores aceitos: `"PERSON"`: Pessoa Física `"BUSINESS"` : Pessoa Jurídica `"BUSINESS_SIMPLE"` : Pessoa Jurídica no Simples Nacional

Exemplos de Requisição

Modo 1 — Simulação por `total_amount_owed`

Informe o total que o tomador irá pagar ao longo do contrato.

curl --request POST \
  'https://sandbox.platform.flowfinance.com.br/banking/originator/products/87a3767c-8d12-4164-80bf-5aa0ae796f06/preview' \
  --header 'Authorization: Bearer <seu_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "total_amount_owed": 10730,
    "interest_rate": 0.13,
    "tac_amount": 0,
    "finance_fee": 0,
    "insurance_amount": 0,
    "num_payments": 12,
    "first_payment_date": "2026-06-06",
    "disbursement_date": "2026-04-17",
    "schedule_type": "MONTHLY",
    "iof_type": "PERSON"
  }'

Modo 2 — Simulação por `financed_amount`

Informe o valor que será efetivamente financiado (principal + IOF capitalizado).

curl --request POST \
  'https://sandbox.platform.flowfinance.com.br/banking/originator/products/87a3767c-8d12-4164-80bf-5aa0ae796f06/preview' \
  --header 'Authorization: Bearer <seu_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "financed_amount": 4885.49,
    "interest_rate": 0.13,
    "tac_amount": 0,
    "finance_fee": 0,
    "insurance_amount": 0,
    "num_payments": 12,
    "first_payment_date": "2026-06-06",
    "disbursement_date": "2026-04-17",
    "schedule_type": "MONTHLY",
    "iof_type": "PERSON"
  }'

Modo 3 — Simulação por `payment_value`

Informe o valor de parcela desejado e a API calcula o contrato a partir dele.

curl --request POST \
  'https://sandbox.platform.flowfinance.com.br/banking/originator/products/87a3767c-8d12-4164-80bf-5aa0ae796f06/preview' \
  --header 'Authorization: Bearer <seu_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "payment_value": 894.17,
    "interest_rate": 0.13,
    "tac_amount": 0,
    "finance_fee": 0,
    "insurance_amount": 0,
    "num_payments": 12,
    "first_payment_date": "2026-06-06",
    "disbursement_date": "2026-04-17",
    "schedule_type": "MONTHLY",
    "iof_type": "PERSON"
  }'

Modo 4 — Simulação por `requested_amount`

Informe o valor líquido que o tomador deseja receber no desembolso.

curl --request POST \
  'https://sandbox.platform.flowfinance.com.br/banking/originator/products/87a3767c-8d12-4164-80bf-5aa0ae796f06/preview' \
  --header 'Authorization: Bearer <seu_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "requested_amount": 4797.23,
    "interest_rate": 0.13,
    "tac_amount": 0,
    "finance_fee": 0,
    "insurance_amount": 0,
    "num_payments": 12,
    "first_payment_date": "2026-06-06",
    "disbursement_date": "2026-04-17",
    "schedule_type": "MONTHLY",
    "iof_type": "PERSON"
  }'

Resposta

HTTP 200 OK — Campos Principais

Campo	Tipo	Descrição
`id`	UUID	Identificador único da simulação. Usar na criação da proposta.
`financed_amount`	number	Valor total financiado, incluindo IOF capitalizado.
`requested_amount`	number	Valor líquido solicitado / desembolsado ao tomador.
`disbursement_amount`	number	Valor efetivamente liberado na data de desembolso.
`total_amount_owed`	number	Soma total das parcelas ao longo do contrato.
`payment_amount`	number	Valor de cada parcela (sistema PRICE).
`equated_monthly_installment`	number	Parcela equivalente sem IOF embutido.
`interest_rate`	number	Taxa de juros mensal informada na simulação.
`annual_interest_rate`	number	Taxa de juros anual equivalente.
`annual_effective_interest_rate`	number	CET (Custo Efetivo Total) anual.
`monthly_effective_interest_rate`	number	CET mensal.
`iof_amount`	number	Total de IOF calculado para a operação.
`iof_daily_rate`	number	Taxa diária de IOF aplicada (0,0082%).
`iof_base_rate`	number	Alíquota base de IOF (0,38%).
`num_periods`	integer	Número de parcelas do contrato.
`issue_date`	string	Data de emissão do contrato (`YYYY-MM-DD`).
`disbursement_date`	string	Data de desembolso do crédito (`YYYY-MM-DD`).
`first_payment_date`	string	Data do primeiro vencimento (`YYYY-MM-DD`).
`last_payment_date`	string	Data do último vencimento (`YYYY-MM-DD`).
`expiration_date`	string	Validade da simulação (ISO 8601).
`amortization_type`	string	`"PRICE"` — sistema de parcelas fixas.
`schedule_type`	string	`"MONTHLY"` — frequência mensal.
`schedule`	array	Array com as parcelas detalhadas (ver abaixo).

Objeto `schedule[]` — Parcela

Campo	Tipo	Descrição
`period`	integer	Número sequencial da parcela.
`payment_date`	string	Data de vencimento da parcela (`YYYY-MM-DD`).
`payment`	number	Valor total da parcela.
`principal`	number	Amortização do principal nesta parcela.
`interest`	number	Juros acumulados até esta parcela.
`iof`	number	IOF incidente nesta parcela.
`balance`	number	Saldo devedor após o pagamento.
`running_day`	integer	Número de dias corridos desde a emissão.
`status`	string	Status do pagamento (`null` = pendente).
`paid_value`	number	Valor pago (`null` enquanto não liquidado).

Exemplo de Resposta (HTTP 200)

{
  "id": "91bb507c-0196-4ffe-b4b2-4658943f93f8",
  "expiration_date": "2026-04-17T23:59:59.235014Z",
  "financed_amount": 4885.49,
  "requested_amount": 4797.23,
  "disbursement_amount": 4797.23,
  "total_amount_owed": 10730.04,
  "payment_amount": 894.17,
  "equated_monthly_installment": 717.68,
  "interest_rate": 0.13,
  "annual_interest_rate": 3.334523,
  "annual_effective_interest_rate": 3.503343,
  "monthly_effective_interest_rate": 0.133604,
  "iof_amount": 88.26,
  "num_periods": 12,
  "issue_date": "2026-04-17",
  "disbursement_date": "2026-04-17",
  "first_payment_date": "2026-06-06",
  "last_payment_date": "2027-05-06",
  "amortization_type": "PRICE",
  "schedule_type": "MONTHLY",
  "schedule": [
    {
      "period": 1,
      "payment_date": "2026-06-06",
      "payment": 894.17,
      "principal": 731.42,
      "interest": 162.75,
      "iof": 5.78,
      "balance": 4885.50,
      "running_day": 50,
      "status": null,
      "paid_value": null
    },
    { "...": "..." }
  ]
}

Próximos Passos

O id retornado deve ser armazenado e utilizado como simulation_id na criação da proposta formal de crédito:

POST /banking/originator/application

{
  "simulation_id": "91bb507c-0196-4ffe-b4b2-4658943f93f8",
  "borrower_id": "<CPF/CNPJ do tomador>",
  "..."
}

⚠️
Observações

Validade da simulação: o campo expiration_date indica que a simulação expira no final do mesmo dia em que foi gerada. Após este prazo, um novo preview deve ser solicitado.

Visão Geral

Requisição

Path Parameter

Headers

Body

Campo de valor — obrigatório (escolha exatamente um)

Enviar mais de um desses campos ou nenhum deles resultará em erro de validação.

Demais campos obrigatórios

Exemplos de Requisição

Modo 1 — Simulação por total_amount_owed

Modo 2 — Simulação por financed_amount

Modo 3 — Simulação por payment_value

Modo 4 — Simulação por requested_amount

Resposta

HTTP 200 OK — Campos Principais

Objeto schedule[] — Parcela

Exemplo de Resposta (HTTP 200)

Próximos Passos

Observações

Modo 1 — Simulação por `total_amount_owed`

Modo 2 — Simulação por `financed_amount`

Modo 3 — Simulação por `payment_value`

Modo 4 — Simulação por `requested_amount`

Objeto `schedule[]` — Parcela