Guide

Simulação FGTS

Este endpoint permite simular o valor que o cliente poderá receber com base nas parcelas futuras do FGTS, considerando a taxa de juros, seguro (se aplicado) e a instituição financeira (provider).

Endpoint

  • URL: https://bff.v8sistema.com/fgts/simulations

  • Método: POST

  • Autenticação: Requer token JWT válido no header da requisição.

Requisição

Headers obrigatórios:

Authorization: Bearer <access_token>
Content-Type: application/json

Body da Requisição

{
  "simulationFeesId": "f6d779ed-52bf-42f2-9dbc-3125fe6491ba",
  "balanceId": "r6d779ed-52bf-42f2-9d2bc-3121246491ba"
  "targetAmount": 0,
  "documentNumber": "2115",
  "desiredInstallments": [
    {
      "totalAmount": 33.64,
      "dueDate": "2025-02-01"
    },
    {
      "totalAmount": 31.95,
      "dueDate": "2026-02-01"
    }
  ],
  "provider": "cartos"
}

Parâmetros da Requisição

  • simulationFeesId: string (UUID)
    Identificador da tabela de taxas obtido previamente através do endpoint /fgts/simulations/fees. Este campo é obrigatório.

  • balanceId: string (UUID)

    Id disponibilizado na consulta de saldo do cliente.

  • targetAmount: number
    Valor desejado para o cliente. Caso não haja um valor específico, deve ser enviado como 0. Este campo é obrigatório.

  • documentNumber: string
    Número do documento do cliente, geralmente o CPF. Este campo é obrigatório.

  • desiredInstallments: array
    Lista das parcelas desejadas. Cada item da lista deve conter dois campos:

    • totalAmount: number
      Valor da parcela.

    • dueDate: string (data no formato YYYY-MM-DD)
      Data de vencimento da parcela.

  • provider: string
    A instituição financeira responsável pela operação. Aceita os valores "qi" ou "cartos". Este campo é obrigatório.

Exemplo de Resposta 

{
  "cet": 0.04,
  "annualCet": 0.54,
  "availableBalance": 486.17,
  "emissionAmount": 539.93,
  "iof": 10.56,
  "tax": 1.8,
  "tc": 7.4,
  "totalBalance": 606.99,
  "totalInstallments": 2,
  "id": "74e22e17-37cf-4a28-9182-3abd462b3168"
}

Campos da Resposta

  • cet: decimal
    Custo Efetivo Total mensal da operação.

  • annualCet: decimal
    Custo Efetivo Total anual.

  • availableBalance: decimal
    Valor líquido disponível para o cliente após deduções e taxas.

  • emissionAmount: decimal
    Valor da operação, considerando todas as taxas e encargos.

  • iof: decimal
    Valor do IOF aplicado na operação.

  • tax: decimal
    Taxa de juros mensal aplicada ao saldo.

  • tc: decimal
    Valor referente à tarifa de cadastro.

  • totalBalance: decimal
    Valor total da operação bloqueado na conta FGTS do cliente.

  • totalInstallments: integer
    Quantidade de parcelas na simulação.

  • id: string
    Identificador único da simulação.

Considerações

  • targetAmount: Caso não seja especificado, o valor deve ser enviado como 0.

  • desiredInstallments: A lista de parcelas deve sempre conter pelo menos 2 parcelas com os campos totalAmount e dueDate.

  • simulationFeesId: Este valor deve ser obtido a partir do endpoint /fgts/simulations/fees.

  • O valor de availableBalance pode ser utilizado para exibir o valor que o cliente pode efetivamente retirar.