Simulações

Módulo de simulação de empréstimo. É o motor de cálculo financeiro (parcelas, IOF, CET, cenários de desembolso) usado tanto por POST /v5/loan-simulations quanto internamente por POST /v5/loans (Empréstimos). A simulação é gravada e pode ser consultada depois, mas não cria contrato.

Rota base v5/loan-simulations.

Autenticação

API Key. Exige permissão de criação de simulações. Ver Autenticação.

Rotas implementadas

Rota	Verbo	Resumo
/v5/loan-simulations	POST	Calcula e persiste uma simulação.

Leitura, edição, cópia, exclusão e busca de simulações ficam no portal da Semear e não são expostas na API de integração: guarde a resposta do POST se precisar dela depois.

Convenções gerais reutilizadas nesta página: Tratamento de erros, Objeto de domínio. Valores fixos em Domínios › Empréstimos.

Três modos de simular

Você informa prazo e taxa e escolhe qual valor fixar. simulationMode é inferido pelo campo enviado:

Você envia	simulationMode.key	A API calcula
installmentAmount	term_rate_installment	Quanto o trabalhador recebe em conta (disbursementAmount)
disbursementAmount	term_rate_disbursement	Qual será a parcela (installmentAmount)
principalAmount	term_rate_principal	A parcela e o líquido a partir do valor contratado

Envie apenas um dos três. No consignado, o mais comum é fixar a parcela igual à availableMarginAmount obtida em Dados do trabalhador; quando a operação tem garantia de FGTS, fixar o principalAmount facilita casar o contratado com a garantia exigida na averbação. Os demais modos de LoanSimulationMode não são usados na collection.

O produto private_payroll

product: "private_payroll" identifica o produto de empréstimo cadastrado para a sua empresa. Ele define os padrões aplicados quando o campo não é enviado. Valores observados no exemplo da collection:

Parâmetro	Valor do produto	Campo na resposta
Tipo de produto / entidade	private_payroll_loan (300) / private_company (300)	productType, payrollEntity
Operação	new	operationType
Amortização / juros / base	price / pre_fixed_days / calendar_days_365	amortizationSystem, interestType, interestBase
Frequência	monthly, 30 dias	paymentFrequencyType, paymentFrequency
IOF	0,38% fixo + 0,0082% ao dia, teto 365 dias, não financiado	iofBaseRate, iofDailyRate, iofDailyMaxDays, iofIsFinanced
Atraso	multa 2% sobre saldo devedor; mora 1% ao mês sobre saldo devedor	latePenaltyRule/Value, lateInterestRule/Value
Dia de corte / prazo mínimo / dia útil	10 / 30 dias / próximo dia útil	cutoffDay, firstInstallmentMinDays, businessDayAdjustmentRule
Cenários de desembolso	5	numberOfDisbursementOptions
Pagamento / desembolso	direct_loan / ted	paymentMethod, disbursementMethod

Campos da entidade

Classificação

Campo	Entrada	Tipo	Descrição
id, code	—	string (uuid), integer	Identificadores da simulação.
type	type	object (code/key/name)	loan. Ver LoanType.
simulationMode	simulationMode (inferido)	object (code/key/name)	Ver Três modos.
lender, fund, productRule	lenderId, fundId, ruleId	object (Referência)	Não preenchidos no consignado privado.
productType, operationType, payrollEntity, product	productType, operationType, payrollEntity, product/productId	object	Herdados do produto.
description, parties[], step, status	idem	—	Simulações não têm tomador nem status (status vem com valores nulos). step = formalization.

Datas

Campo	Entrada	Tipo	Descrição
disbursementDate	disbursementDate	string (date)	Data prevista do desembolso.
firstDueDate	firstDueDate	string (date)	Primeiro vencimento ajustado pelas regras do produto (pode diferir do enviado).
lastDueDate	—	string (date)	Último vencimento.
calendarDays, businessDays	—	integer	Dias corridos e úteis do desembolso ao último vencimento.
dueDay, cutoffDay, firstInstallmentMinDays, businessDayAdjustmentRule	idem	—	Regras do produto que moveram firstDueDate. Em dueDay e cutoffDay, enviar 0 equivale a não enviar: vale o padrão do produto. dueDay devolve o valor configurado (ou 0), e não o dia calculado pelo calendário de competências — o dia efetivo está em firstDueDate.

Valores

Campo	Entrada	Tipo	Descrição
baseAmount, principalAmount, originationAmount	baseAmount, principalAmount	decimal	Valor financiado. Iguais quando não há tarifas nem entrada.
disbursementAmount	disbursementAmount	decimal	Valor líquido em conta: o principal já descontado do IOF e das tarifas que não foram financiados.
downPaymentAmount, discountAmount	idem	decimal	Entrada e desconto.
feeAmount, financedFeeAmount, unfundedFeeAmount, fees[]	fees[]	—	Tarifas totais, financiadas e não financiadas.
numberOfInstallments, installmentAmount	idem	integer, decimal	Prazo e parcela.
totalReceivableAmount	—	decimal	Total a receber ao longo de todo o contrato.
outstandingAmount	—	decimal	Saldo devedor inicial, antes de qualquer pagamento. Corresponde ao principal.
fixedInterestAmount, floatingInterestAmount	—	decimal	Total de juros prefixados e pós-fixados.

Taxas

Campo	Entrada	Tipo	Descrição
rate, monthlyRate, dailyRate, annualRate, fixedRate	monthlyRate	decimal	Taxa contratual expressa em diferentes periodicidades — diária, mensal e anual — todas equivalentes entre si. Envie a mensal; as demais vêm calculadas.
floatingIndexType, floatingIndexMultiplier, floatingIndexSpread	idem	—	Índice pós-fixado (none no consignado). Ver LoanFloatingIndexType.
effectiveInterestRate, monthlyEffectiveInterestRate, annualEffectiveInterestRate	—	decimal	Custo Efetivo Total (CET), considerando juros, IOF e tarifas ao longo de todo o fluxo do contrato. A versão mensal e a anual são equivalentes entre si — expressam o mesmo custo em periodicidades diferentes. É o valor a exibir ao tomador. Os antigos campos cet, monthlyCet e annualCet não são mais devolvidos nas rotas v5.
iofIsFinanced, iofBaseRate, iofDailyRate, iofDailyMaxDays, iofAmount, iofFinancedAmount	iofIsFinanced, iofBaseRate, iofDailyRate, iofDailyMaxDays	—	IOF. Com iofIsFinanced = false, iofAmount é descontado do líquido.
latePenaltyRule, latePenaltyRuleValue, lateInterestRule, lateInterestRuleValue	idem	—	Regras de multa e mora. Ver LatePenaltyRule e LateInterestRule.

Configuração

Campo	Entrada	Tipo	Descrição
graceType, graceDays, interestGracePeriod, principalGracePeriod	graceType, graceDays	—	Carência. Ver LoanGraceType.
interestType, interestBase, amortizationSystem	idem	object	Ver LoanInterestType, LoanInterestBase, LoanAmortizationSystem.
paymentFrequencyType, paymentFrequency, factor	idem	—	Frequência de pagamento.
card	card	object	Limites de cartão consignado. Zerados em empréstimo.
originContracts[]	originContracts[]	array	Contratos de origem (portabilidade/refinanciamento). Vazio em operação nova.

installments[] — somente saída

Omitido quando resultOptions.disableInstallments = true.

Campo	Tipo	Descrição
id, key, installmentNumber	uuid, uuid, integer	Identificação da parcela.
dueDate, businessDueDate	date	Vencimento contratual e ajustado para dia útil.
periodStartDate, periodEndDate, calendarDays, businessDays	—	Período de competência da parcela.
installmentAmount, amortizationAmount, interestAmount	decimal	Valor da parcela e sua composição entre amortização e juros do período (Price).
principalAmount, outstandingAmount, dueBalanceAmount	decimal	Saldo devedor antes da parcela.
fixedRate, fixedInterestAmount, floatingRate, floatingInterestAmount	decimal	Taxa e juros do período. Na 1ª parcela, com mais dias, fixedRate supera a mensal.
iofBaseAmount, iofDailyAmount, iofAmount, iofDays, accumulatedCalendarDays	—	IOF da parcela e dias acumulados (IOF diário limitado a 365 dias).
feeAmount, interestType, note	—	Tarifa da parcela, tipo de juros e observação.

disbursementOptions[] — somente saída

numberOfDisbursementOptions cenários, um por dia a partir de disbursementDate, cada um com o mesmo conjunto de valores e taxas do cabeçalho recalculado para aquela data (id, nid, disbursementDate, firstDueDate, lastDueDate, simulationAmount, principalAmount, disbursementAmount, installmentAmount, iofAmount, taxas, fees[], note). São usados por PUT /v5/loans/{id}/disbursements quando a data efetiva difere da prevista.

Datas e regras do produto

O produto aplica regras que podem mover o primeiro vencimento. No exemplo da collection, o pedido foi firstDueDate: 2026-03-10 e a API devolveu 2026-04-21:

Regra	Campo	Efeito
Prazo mínimo até a 1ª parcela	firstInstallmentMinDays: 30	O primeiro vencimento precisa estar ao menos 30 dias após o desembolso.
Calendário de competências	—	O primeiro vencimento cai no dia de vencimento do mês seguinte à competência da Dataprev em que está o desembolso. A janela de cada competência vem do calendário oficial do Crédito do Trabalhador, consultado no momento da simulação.
Dia de corte	cutoffDay: 10	Usado só quando o calendário da Dataprev não está disponível: datas após o corte empurram o vencimento para o ciclo seguinte da folha.
Ajuste de dia útil	businessDayAdjustmentRule: next_business_day	Vencimentos em fim de semana/feriado vão para o próximo dia útil (businessDueDate).

Em disbursementOptions[], cada data de desembolso usa a competência em que ela cai, por isso cenários de dias seguidos podem ter primeiros vencimentos diferentes quando atravessam a virada da competência.

Use sempre as datas devolvidas ao apresentar a proposta e ao emitir o contrato.

---

POST /v5/loan-simulations

Calcula e persiste uma simulação.

Autenticação: API Key. Exige permissão de criação de simulações.

Payload de entrada

Campos enviados pelas requisições Simulação por Valor de Parcela e Simulação por Valor do Desembolso da collection. As duas diferem só no valor de referência: installmentAmount ou disbursementAmount (envie apenas um).

Visualizar parâmetros

Campo	Tipo	Obrigatório	Descrição
product	string	Sim	key do produto. Use private_payroll. Alternativa: productId (uuid, inválido → 1010010). Desconhecido → 1010003.
disbursementDate	string (date)	Sim	Data prevista do desembolso.
firstDueDate	string (date)	Sim	Primeiro vencimento desejado (ajustável).
numberOfInstallments	integer	Sim	Quantidade de parcelas. Inválido → 1010004.
installmentAmount	decimal	Um dos três	Fixa a parcela. Inválido → 1010006.
monthlyRate	decimal	Sim	Taxa mensal em fração. Ausente/zero → 1010005/1010009.
resultOptions.disableInstallments	boolean | null	Não	true devolve installments: []. Reduz o corpo em dezenas de KB.
disbursementAmount	decimal	Um dos três	Fixa o líquido em conta. Inválido → 1010007.

Outros campos aceitos (não usados na collection)

Campo	Tipo	Obrigatório	Descrição
principalAmount	decimal	Um dos três	Fixa o valor contratado.
Demais campos	—	Não	type, productType, operationType, payrollEntity, description, borrower, parties[], graceType, graceDays, dueDay, cutoffDay, firstInstallmentMinDays, businessDayAdjustmentRule, floatingIndexType/Multiplier/Spread, iofIsFinanced, iofBaseRate, iofDailyRate, iofDailyMaxDays, latePenaltyRule/Value, lateInterestRule/Value, interestType, interestBase, amortizationSystem, paymentFrequencyType, paymentFrequency, fees[], originContracts[], numberOfDisbursementOptions, paymentMethod, paymentBankAccount, paymentPix, disbursementMethod, disbursementBankAccount, disbursementPix, currency, refCode, note, card, unitId, partnerId, branchId, agentId, userId. Padrões vêm do produto. loanAmount e debitAmount são obsoletos — use disbursementAmount.

Exemplo de Requisição e Resposta

Body (por Valor de Parcela)

Visualizar Body

{
  "product": "private_payroll",
  "disbursementDate": "2026-10-16",
  "firstDueDate": "2026-10-16",
  "numberOfInstallments": 96,
  "installmentAmount": 100.00,
  "monthlyRate": 0.018,
  "resultOptions": {
    "disableInstallments": true
  }
}

Body (por Valor do Desembolso)

Visualizar Body

{
  "product": "private_payroll",
  "disbursementDate": "2026-02-22",
  "firstDueDate": "2026-03-10",
  "numberOfInstallments": 96,
  "disbursementAmount": 5000.00,
  "monthlyRate": 0.018,
  "resultOptions": {
    "disableInstallments": true
  }
}

cURL

curl --request POST \
  --url '{{baseUrl}}/v5/loan-simulations' \
  --header 'X-Api-Key: {{x_api_key}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "product": "private_payroll",
    "disbursementDate": "2026-10-16",
    "firstDueDate": "2026-10-16",
    "numberOfInstallments": 96,
    "installmentAmount": 100.00,
    "monthlyRate": 0.018,
    "resultOptions": {
      "disableInstallments": true
    }
  }'

201 - Created

Exemplo do modo por parcela com disableInstallments: true e disbursementOptions[] reduzido a um item.

Visualizar Response

{
  "id": "00000000-0000-7000-8000-000000000601",
  "code": 1,
  "type": { "code": 1, "key": "loan", "name": "Empréstimo" },
  "simulationMode": { "code": 1, "key": "term_rate_installment", "name": "Prazo, Taxa e Valor da Parcela" },
  "lender": { "code": null, "key": null, "name": null },
  "fund": { "code": null, "key": null, "name": null },
  "productType": { "code": 300, "key": "private_payroll_loan", "name": "Crédito Consignado Privado" },
  "operationType": { "code": 10, "key": "new", "name": "Novo" },
  "payrollEntity": { "code": 300, "key": "private_company", "name": "Empresa Privada" },
  "product": { "code": 40, "key": "private_payroll", "name": "Consignado Privado" },
  "productRule": { "code": null, "key": null, "name": null },
  "description": null,
  "parties": [],
  "step": { "code": 1, "key": "formalization", "name": "Formalização" },
  "status": { "code": null, "key": null, "name": null, "date": null, "color": null, "note": null },
  "disbursementDate": "2026-02-22",
  "firstDueDate": "2026-04-21",
  "lastDueDate": "2034-03-21",
  "baseAmount": 4437.230000,
  "principalAmount": 4437.230000,
  "originationAmount": 4437.230000,
  "disbursementAmount": 4288.560000,
  "downPaymentAmount": 0.000000,
  "discountAmount": 0.000000,
  "feeAmount": 0.000000,
  "financedFeeAmount": 0.000000,
  "unfundedFeeAmount": 0.000000,
  "numberOfInstallments": 96,
  "installmentAmount": 100.000000,
  "totalReceivableAmount": 9600.000000,
  "outstandingAmount": 4437.230000,
  "fixedInterestAmount": 5162.770000,
  "floatingInterestAmount": 0.000000,
  "graceType": { "code": 1, "key": "principal", "name": "Principal" },
  "graceDays": 0,
  "interestGracePeriod": 0,
  "principalGracePeriod": 0,
  "calendarDays": 2949,
  "businessDays": 2063,
  "rate": 0.018,
  "dailyRate": 0.000594840785263617,
  "monthlyRate": 0.018,
  "annualRate": 0.238720531575528,
  "fixedRate": 0.018,
  "floatingIndexType": { "code": 0, "key": "none", "name": "Não Definido" },
  "floatingIndexMultiplier": 0,
  "floatingIndexSpread": 0,
  "effectiveInterestRate": 0.01922,
  "monthlyEffectiveInterestRate": 0.01922,
  "annualEffectiveInterestRate": 0.25665,
  "iofIsFinanced": false,
  "iofBaseRate": 0.0038,
  "iofDailyRate": 0.000082,
  "iofDailyMaxDays": 365,
  "iofAmount": 148.660000,
  "iofFinancedAmount": 0.000000,
  "latePenaltyRule": { "code": 3, "key": "percentage_of_outstanding_balance", "name": "Percentual sobre o saldo devedor" },
  "latePenaltyRuleValue": 0.02,
  "lateInterestRule": { "code": 2, "key": "monthly_percentage_of_outstanding_balance", "name": "Percentual mensal sobre o saldo devedor" },
  "lateInterestRuleValue": 0.01,
  "interestType": { "code": 1, "key": "pre_fixed_days", "name": "Prefixados Dia" },
  "interestBase": { "code": 2, "key": "calendar_days_365", "name": "Dias corridos base 365" },
  "amortizationSystem": { "code": 10, "key": "price", "name": "Price" },
  "paymentFrequencyType": { "code": 1, "key": "monthly", "name": "Mensal" },
  "paymentFrequency": 30,
  "factor": 0,
  "dueDay": 0,
  "cutoffDay": 10,
  "firstInstallmentMinDays": 30,
  "businessDayAdjustmentRule": { "code": 1, "key": "next_business_day", "name": "Próximo dia útil" },
  "card": { "limitBaseAmount": 0.000000, "limitPercentage": 0, "limitAmount": 0.000000, "availableLimitAmount": 0.000000, "currentDiscountAmount": 0.000000, "limitMultiplier": 0, "totalMarginAmount": 0.000000, "withdrawalLimitPercentage": 0, "withdrawalMarginAmount": 0.000000, "withdrawalLimitAmount": 0.000000, "purchaseMarginAmount": 0.000000, "purchaseLimitAmount": 0.000000 },
  "fees": [],
  "originContracts": [],
  "installments": [],
  "numberOfDisbursementOptions": 5,
  "disbursementOptions": [
    {
      "id": "00000000-0000-7000-8000-000000000611",
      "nid": 100001,
      "disbursementDate": "2026-02-22",
      "firstDueDate": "2026-04-21",
      "lastDueDate": "2034-03-21",
      "simulationAmount": 4437.230000,
      "baseAmount": 4437.230000,
      "principalAmount": 4437.230000,
      "originationAmount": 4437.230000,
      "disbursementAmount": 4288.560000,
      "downPaymentAmount": 0.000000,
      "discountAmount": 0.000000,
      "feeAmount": 0.000000,
      "financedFeeAmount": 0.000000,
      "unfundedFeeAmount": 0.000000,
      "numberOfInstallments": 96,
      "installmentAmount": 100.000000,
      "totalReceivableAmount": 9600.000000,
      "outstandingAmount": 4437.230000,
      "fixedInterestAmount": 5162.770000,
      "floatingInterestAmount": 0.000000,
      "graceDays": 0,
      "calendarDays": 2949,
      "businessDays": 2063,
      "rate": 0.018,
      "dailyRate": 0.000594840785263617,
      "monthlyRate": 0.018,
      "annualRate": 0.238720531575528,
      "fixedRate": 0.018,
      "effectiveInterestRate": 0.01922,
      "monthlyEffectiveInterestRate": 0.01922,
      "annualEffectiveInterestRate": 0.25665,
      "iofBaseRate": 0.0038,
      "iofDailyRate": 0.000082,
      "iofAmount": 148.660000,
      "iofFinancedAmount": 0.000000,
      "factor": 0,
      "fees": [],
      "note": null
    }
  ]
}

400 - Erro

Produto inválido (1010003), validações financeiras (1010004–1010011), erro de cálculo (1010012, ex.: parcela menor que os juros do período), ou exceção não tratada (9999999).

Visualizar Response

{ "messages": [ { "code": "1010003", "text": "Produto inválido" } ] }

401 - Não autorizado

API Key ausente, inválida ou expirada.

403 - Proibido

Usuário autenticado sem permissão de criação de simulações. Corpo vazio.

Postman

As requisições Simulação por Valor de Parcela e Simulação por Valor do Desembolso da collection trazem um script de Visualizer que renderiza a resposta em tabelas (valores, parcelas, taxas, IOF). Abra a aba "Visualize" no Postman após executar.