Pular para o conteúdo
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Parâmetro
Local
Tipo
Obrigatório
Descrição

publicId

path

string

Sim

Identificador público do employee

Corpo

Igual ao da simulação padrão, com targetInstallmentAmount no lugar de loanAmount.

Campo
Tipo
Obrigatório
Descrição

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)

post
/api/v1/originator/employees/{publicId}/simulations/by-installment

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

Autorizações
AuthorizationstringObrigatório

JWT token fornecido pelo administrador

Parâmetros de rota
publicIdstringObrigatório

Identificador público do employee (16 caracteres)

Parâmetros de cabeçalho
Idempotency-Keystring · máx: 255Opcional

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.

Corpo
employmentRelationshipPublicIdstring · uuidOpcional

Identificador público opaco do vínculo empregatício.

Example: 0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02
targetInstallmentAmountnumber · decimal · mín: 0.01Obrigatório

Valor de parcela desejado em reais (decimal com 2 casas decimais). O sistema encontra o valor máximo de empréstimo que produz essa parcela.

installmentCountinteger · mín: 1Obrigatório

Quantidade de parcelas desejada para pagamento do empréstimo.

monthlyInterestRatenumber · decimal · mín: 0.01Obrigatório

Taxa de juros mensal nominal em percentual (decimal com 4 casas decimais). Ex. 4.0

loanDatestring · dateObrigatório

Data base de contratação considerada para cálculo da operação. Não pode ser no passado.

firstDueDatestring · date · anulávelOpcional

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.
tacAmountnumber · decimal · anulávelOpcional

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.

insuranceAmountnumber · decimal · anulávelOpcional

Valor do seguro prestamista em reais. Quando omitido, o backend usa o defaultInsuranceAmount configurado no originador.

feesAmountnumber · decimal · anulávelOpcionalObsoleto

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.

iofFinancedboolean · anulávelOpcional

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.
Default: true
feesFinancedboolean · anulávelOpcional

Define se as tarifas (TAC + Seguro) é financiado (embutido no valor financiado e diluído nas parcelas).

  • null ou true (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.
maxEffectiveCostSpreadnumber · decimal · mín: 0.01 · máx: 100 · anulávelOpcional

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.

Respostas
201

Simulação reversa criada com sucesso

application/json

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.

publicIdstring · uuid · anulávelOpcional

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.

Example: 0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02
employeePublicIdstringOpcional

Identificador público do trabalhador (16 caracteres Base64 URL-safe).

Example: Kj8mP2xQ9nR4sT6v
employmentRelationshipPublicIdstring · uuidOpcional

Identificador público opaco do vínculo.

Example: 0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02
requestedAmountnumber · decimalOpcional

Valor 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.

Example: 5000
installmentCountintegerOpcional

Quantidade de parcelas calculada para a proposta simulada.

Example: 12
monthlyInterestRatenumber · decimalOpcional

Taxa de juros mensal em percentual (decimal com 4 casas decimais).

Example: 1.97
termMonthsintegerOpcional

Prazo total da operação em meses.

Example: 12
installmentAmountnumber · decimalOpcional

Parcela mensal em reais (decimal com 2 casas decimais).

Example: 501.18
totalAmountnumber · decimalOpcionalObsoleto

(DEPRECATED) Valor total da operação em reais. Use financedAmount e demais campos detalhados.

Example: 5119.43
disbursementAmountnumber · decimalOpcional

Valor desembolsado em reais (decimal com 2 casas decimais).

Example: 5000
financedAmountnumber · decimalOpcional

Valor financiado em reais (decimal com 2 casas decimais).

Example: 5119.43
outstandingBalancenumber · decimalOpcional

Saldo devedor em reais (decimal com 2 casas decimais).

Example: 5119.43
totalInterestAmountnumber · decimalOpcional

Juros totais em reais (decimal com 2 casas decimais).

Example: 894.73
debitAmountnumber · decimalOpcional

Total a pagar em reais (soma das parcelas, decimal com 2 casas decimais). A última parcela pode diferir das demais por arredondamento.

Example: 6014.16
firstDueDatestring · dateOpcional

Data do primeiro vencimento.

Example: 2027-03-28
lastDueDatestring · dateOpcional

Data do último vencimento.

Example: 2028-02-28
monthlyEffectiveCostnumber · decimalOpcional

CET mensal em percentual (decimal com 4 casas decimais).

Example: 2.2669
annualEffectiveCostnumber · decimalOpcional

CET anual em percentual (decimal com 4 casas decimais).

Example: 30.8643
iofAmountnumber · decimalOpcional

IOF estimado em reais (decimal com 2 casas decimais).

Example: 119.43
tacAmountnumber · decimalOpcional

TAC (Taxa de Abertura de Crédito) em reais. Para consignado privado, sempre 0.

Example: 0
insuranceAmountnumber · decimalOpcional

Seguro prestamista em reais. Snapshot do valor usado no cálculo da simulação.

Example: 0
feesAmountnumber · decimalOpcionalObsoleto

DEPRECATED — soma computada de tacAmount + insuranceAmount. Use os campos separados. Mantido por 1 release para compatibilidade com clients legados.

Example: 0
statusstring · enumOpcional

Situação da simulação no ciclo de originação.

ValorSignificado
EPHEMERALSimulação ativa, ainda não convertida em proposta
CONVERTED_TO_PROPOSALSimulação já convertida em proposta
EXPIREDSimulação expirada (prazo de validade ultrapassado)
Example: EPHEMERALValores possíveis:
expiresAtstring · date-timeOpcional

Data e hora limite de validade da simulação (UTC).

Example: 2027-01-11T10:00:00Z
sourcestringOpcional

Origem da simulação no sistema (por exemplo, ORIGINATOR).

Example: ORIGINATOR
iofFinancedbooleanOpcional

Indica se o IOF foi financiado na simulação.

Example: true
createdDatestring · date-timeOpcional

Data e hora de criação da simulação (UTC).

Example: 2027-01-04T10:00:00Z
graceDaysChargedinteger · int64 · anulávelOpcional

Dias de juros de carência efetivamente cobrados pelo simulador.

Example: 53
graceDaysWaivedinteger · int64 · anulávelOpcional

Dias de juros de carência isentados pela convergência do teto de CET (0 sem teto).

Example: 0
effectiveCostWithinLimitboolean · anulávelOpcional

Na 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).

Example: true
post/api/v1/originator/employees/{publicId}/simulations/by-installment
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