Criar Simulação por Parcela
Simulação reversa: você informa a parcela desejada (targetInstallmentAmount) e recebe o valor máximo de empréstimo para o vínculo.
Request
POST /api/v1/originator/employees/{publicId}/simulations/by-installment
Autenticação: Authorization: Bearer {originatorToken}.
Parâmetros
publicId
path
string
Sim
Identificador público do employee
Corpo
Igual ao da simulação padrão, com targetInstallmentAmount no lugar de loanAmount.
employmentRelationshipPublicId
string (uuid)
Sim
ID do vínculo empregatício do trabalhador
targetInstallmentAmount
decimal
Sim
Valor de parcela desejado em reais (>= 0.01)
installmentCount
integer
Sim
Número de parcelas (1–99)
monthlyInterestRate
decimal
Sim
Taxa de juros mensal em percentual (>= 0.01)
loanDate
string (date)
Sim
Data do empréstimo (YYYY-MM-DD). Não pode ser no passado.
firstDueDate
string (date)
Não
Data do primeiro vencimento, sempre no dia 28. null para cálculo automático (ver regra abaixo). Não pode ser no passado.
tacAmount
decimal
Não
Taxa de Abertura de Crédito. Deve ser 0 (padrão quando omitido); valor positivo dá 400 (TAC_NOT_ALLOWED).
insuranceAmount
decimal
Não
Seguro prestamista (>= 0). Omitido ou null: usa a configuração do originador, ou zero.
feesAmount
decimal
Não
Deprecated — use tacAmount + insuranceAmount. Quando enviado isoladamente, é tratado como insuranceAmount (com tacAmount = 0).
iofFinanced
boolean
Não
IOF financiado. Omitido: configuração do originador.
feesFinanced
boolean
Não
Tarifas (TAC + seguro) financiadas. Omitido: configuração do originador.
maxEffectiveCostSpread
decimal
Não
Teto de CET relativo à taxa contratada, em pontos percentuais — mesma forma do monthlyInterestRate (1.0 = CET mensal máxima de taxa + 1 p.p.; faixa 0.01–100). O campo é aceito na simulação por parcela, mas o teto não é aplicado nem verificado: a plataforma não isenta dias de juros de carência por causa dele. O único efeito observável de enviá-lo é a resposta vir com effectiveCostWithinLimit = null (explícito no JSON). Omitido, effectiveCostWithinLimit volta true.
O vencimento automático segue a mesma regra da simulação padrão.
Response
Mesmo formato da simulação padrão. A diferença: requestedAmount é o valor máximo de empréstimo encontrado para a parcela alvo.
201 Created.
Exemplo
A resposta completa, com os valores calculados, está no exemplo do bloco de referência no fim da página.
Próximo passo
Criar Proposta com o publicId retornado como simulationPublicId. Sem simulação, o firstDueDate vira o dueDate da proposta.
Erros
Código
errorCode
Situação
400
—
Payload inválido (properties.errors): campo ausente/inválido, data no passado. Informe exatamente um identificador de vínculo
400
—
JSON malformado, data ou UUID inválidos (type: about:blank)
400
TAC_NOT_ALLOWED
tacAmount diferente de 0 (positivo ou negativo)
400
—
Vínculo empregatício não encontrado: <id> — vínculo inexistente ou de outro employee
400
—
Simulação reversa não convergiu para o valor de parcela informado. — ajuste a parcela ou o prazo
400
—
Primeiro vencimento fora do dia 28 ou antes do mínimo do calendário Dataprev; financiado abaixo do piso de Valor Presente; margem do vínculo não consultada
400
—
Parcela acima da margem: title: Elegibility Violation, properties.violations[].code = MARGIN_EXCEEDED
404
—
Employee não encontrado ou de outro originador
429
—
Mais de 100 requisições por segundo
4xx repassado
LOAN_SIMULATOR_ERROR
O simulador de crédito recusou o cálculo, com o status devolvido por ele (502 se o status não for reconhecido; 500 se a resposta vier vazia)
503
SERVICE_UNAVAILABLE_LOANSIMULATOR
Simulador de crédito indisponível. Reenvie com uma nova Idempotency-Key: com a mesma chave, a resposta guardada (este mesmo erro) é repetida por 7 dias
Erros comuns a todos os endpoints — 401, 403 de token, 409 de Idempotency-Key em processamento, 500 e 503 — e o formato ProblemDetail estão em Erros da API.
Criar Simulação por Parcela (Reversa)
Cria uma simulação reversa: dado um valor de parcela desejado (targetInstallmentAmount), o sistema encontra o valor máximo de empréstimo que o trabalhador pode obter. Utiliza convergência numérica iterativa. O primeiro vencimento segue a mesma regra do calendário Dataprev descrita em "Criar Simulação".
JWT token fornecido pelo administrador
Identificador público do employee (16 caracteres)
Chave de idempotência para evitar duplicação em retentativas. Se fornecida, o servidor retornará a mesma resposta para chamadas com a mesma chave do mesmo originador. A chave é retida por 7 dias. Depois desse prazo ela é expurgada e uma requisição com a mesma chave é tratada como nova, sendo reprocessada.
Identificador público opaco do vínculo empregatício.
0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02Valor de parcela desejado em reais (decimal com 2 casas decimais). O sistema encontra o valor máximo de empréstimo que produz essa parcela.
Quantidade de parcelas desejada para pagamento do empréstimo.
Taxa de juros mensal nominal em percentual (decimal com 4 casas decimais). Ex. 4.0
Data base de contratação considerada para cálculo da operação. Não pode ser no passado.
Data do primeiro vencimento (sempre dia 28). Não pode ser no passado.
- Se informado, deve seguir o calendário Dataprev.
- Se
null(ou omitido), o sistema aplica automaticamente o primeiro vencimento no dia 28 conforme o calendário Dataprev.
Valor de TAC (Taxa de Abertura de Crédito) em reais. Para consignado privado deve ser sempre 0 ou omitido — o backend rejeita requisições com tacAmount > 0 retornando 400 com errorCode = TAC_NOT_ALLOWED.
Valor do seguro prestamista em reais. Quando omitido, o backend usa o defaultInsuranceAmount configurado no originador.
DEPRECATED — use tacAmount + insuranceAmount separadamente. Mantido por 1 release para compatibilidade.
Quando tacAmount/insuranceAmount não vêm e apenas feesAmount vem, o backend trata como insuranceAmount=feesAmount, tacAmount=0.
Define se o IOF é financiado (embutido no valor financiado e diluído nas parcelas).
true(default): IOF financiado.false: IOF não financiado. IOF descontado do desembolso.
trueDefine se as tarifas (TAC + Seguro) é financiado (embutido no valor financiado e diluído nas parcelas).
nulloutrue(default): TAC financiado.false: TAC não financiado. O custo das tarifas é descontado do desembolso. Sobrepõe a configuração do originator se enviado explicitamente.
Teto de CET relativo à taxa contratada, em pontos percentuais — mesma forma do monthlyInterestRate
(ex.: 1.0 = CET mensal máxima de taxa + 1 p.p.). O campo é aceito na reversa, mas o teto
não é aplicado nem verificado nesta operação: o simulador não isenta dias de juros de carência
por causa dele.
O único efeito observável de enviá-lo é a resposta vir com effectiveCostWithinLimit = null
(teto não verificado). Quando omitido, effectiveCostWithinLimit volta true.
Simulação reversa criada com sucesso
Simulação criada para o vínculo do trabalhador.
Os valores do exemplo são ilustrativos: mostram a forma e as relações entre os campos, não o resultado exato do cálculo. Correspondem ao request de exemplo (R$ 5.000,00 em 12x a 1,97% a.m., loanDate 2027-01-04, 1º vencimento 2027-03-28, IOF financiado, sem tarifas): disbursementAmount = requestedAmount, financedAmount = requestedAmount + iofAmount, debitAmount = soma das parcelas e totalInterestAmount = debitAmount − financedAmount. O array installments do exemplo mostra só a 1ª, a 2ª e a última parcela.
Identificador público opaco da simulação. É este o valor a enviar em simulationPublicId na criação de proposta. Pode vir ausente em simulações antigas.
0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02Identificador público do trabalhador (16 caracteres Base64 URL-safe).
Kj8mP2xQ9nR4sT6vIdentificador público opaco do vínculo.
0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02Valor solicitado em reais (decimal com 2 casas decimais). Na simulação por parcela (reversa), é o valor de empréstimo que o cálculo encontrou para a parcela pedida.
5000Quantidade de parcelas calculada para a proposta simulada.
12Taxa de juros mensal em percentual (decimal com 4 casas decimais).
1.97Prazo total da operação em meses.
12Parcela mensal em reais (decimal com 2 casas decimais).
501.18(DEPRECATED) Valor total da operação em reais. Use financedAmount e demais campos detalhados.
5119.43Valor desembolsado em reais (decimal com 2 casas decimais).
5000Valor financiado em reais (decimal com 2 casas decimais).
5119.43Saldo devedor em reais (decimal com 2 casas decimais).
5119.43Juros totais em reais (decimal com 2 casas decimais).
894.73Total a pagar em reais (soma das parcelas, decimal com 2 casas decimais). A última parcela pode diferir das demais por arredondamento.
6014.16Data do primeiro vencimento.
2027-03-28Data do último vencimento.
2028-02-28CET mensal em percentual (decimal com 4 casas decimais).
2.2669CET anual em percentual (decimal com 4 casas decimais).
30.8643IOF estimado em reais (decimal com 2 casas decimais).
119.43TAC (Taxa de Abertura de Crédito) em reais. Para consignado privado, sempre 0.
0Seguro prestamista em reais. Snapshot do valor usado no cálculo da simulação.
0DEPRECATED — soma computada de tacAmount + insuranceAmount. Use os campos separados.
Mantido por 1 release para compatibilidade com clients legados.
0Situação da simulação no ciclo de originação.
| Valor | Significado |
|---|---|
| EPHEMERAL | Simulação ativa, ainda não convertida em proposta |
| CONVERTED_TO_PROPOSAL | Simulação já convertida em proposta |
| EXPIRED | Simulação expirada (prazo de validade ultrapassado) |
EPHEMERALValores possíveis: Data e hora limite de validade da simulação (UTC).
2027-01-11T10:00:00ZOrigem da simulação no sistema (por exemplo, ORIGINATOR).
ORIGINATORIndica se o IOF foi financiado na simulação.
trueData e hora de criação da simulação (UTC).
2027-01-04T10:00:00ZDias de juros de carência efetivamente cobrados pelo simulador.
53Dias de juros de carência isentados pela convergência do teto de CET (0 sem teto).
0Na simulação direta: true quando a CET mensal ficou dentro do teto solicitado (ou nenhum teto foi informado);
false quando nem isentando toda a carência o teto foi atingido (best-effort).
Na reversa (por parcela): o teto não é verificado. Vem true quando a requisição não trouxe maxEffectiveCostSpread;
vem null quando trouxe — o campo é serializado como null explícito no JSON (não omitido).
trueDados inválidos, corpo ilegível, regra de negócio ou parcela acima da margem.
Não autenticado
Permissão insuficiente
Employee não encontrado ou de outro originador.
Mesma Idempotency-Key ainda em processamento; tente de novo depois
Mais de 100 requisições por segundo. Aguarde o header Retry-After e reenvie com nova Idempotency-Key — com a mesma chave, o 429 gravado é repetido.
Status não reconhecido do motor de cálculo (errorCode LOAN_SIMULATOR_ERROR)
Simulador de crédito indisponível. Reenvie com nova Idempotency-Key.
Recusada pelo motor de cálculo, com o status dele (errorCode LOAN_SIMULATOR_ERROR)
POST /api/v1/originator/employees/{publicId}/simulations/by-installment HTTP/1.1
Host: ingress.gtpayroll.staging.giro.tech
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 252
{
"employmentRelationshipPublicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02",
"targetInstallmentAmount": 501.18,
"installmentCount": 12,
"monthlyInterestRate": 1.97,
"loanDate": "2027-01-04",
"firstDueDate": null,
"tacAmount": 0,
"insuranceAmount": 0,
"iofFinanced": true
}{
"publicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02",
"employeePublicId": "Kj8mP2xQ9nR4sT6v",
"employmentRelationshipPublicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02",
"requestedAmount": 5000,
"installmentCount": 12,
"monthlyInterestRate": 1.97,
"termMonths": 12,
"installmentAmount": 501.18,
"disbursementAmount": 5000,
"financedAmount": 5119.43,
"outstandingBalance": 5119.43,
"totalInterestAmount": 894.73,
"debitAmount": 6014.16,
"firstDueDate": "2027-03-28",
"lastDueDate": "2028-02-28",
"installments": [
{
"installmentNumber": 1,
"dueDate": "2027-03-28",
"installmentAmount": 501.18,
"amortizationAmount": 217.27,
"interestAmount": 283.91,
"iofAmount": 2.3,
"feesAmount": 0,
"outstandingBalance": 4902.16,
"daysToCompensate": 83
},
{
"installmentNumber": 2,
"dueDate": "2027-04-28",
"installmentAmount": 501.18,
"amortizationAmount": 401.36,
"interestAmount": 99.82,
"iofAmount": 5.28,
"feesAmount": 0,
"outstandingBalance": 4500.8,
"daysToCompensate": 31
},
{
"installmentNumber": 12,
"dueDate": "2028-02-28",
"installmentAmount": 501.18,
"amortizationAmount": 491.24,
"interestAmount": 9.94,
"iofAmount": 16.57,
"feesAmount": 0,
"outstandingBalance": 0,
"daysToCompensate": 31
}
],
"monthlyEffectiveCost": 2.2669,
"annualEffectiveCost": 30.8643,
"iofAmount": 119.43,
"tacAmount": 0,
"insuranceAmount": 0,
"feesAmount": 0,
"status": "EPHEMERAL",
"expiresAt": "2027-01-11T10:00:00Z",
"source": "ORIGINATOR",
"iofFinanced": true,
"createdDate": "2027-01-04T10:00:00Z",
"graceDaysCharged": 53,
"graceDaysWaived": 0,
"effectiveCostWithinLimit": true
}Atualizado