Simulação de Port + REFIN

Sumário #

1. Visão Geral da API
2. Endpoints Disponíveis
3. Simulação – Cálculo do REFIN
4. Simulação – Cálculo de Parcelas – Portabilidade
5. Estruturas de Erro

1. Visão Geral da API #

A API de Simulação é responsável por executar cálculos financeiros de operações de crédito, expondo endpoints de
simulação de portabilidade e refinanciamento.

URL token #

• Homologação: https://hmlapi2.bancosemear.com.br/oauth/access-token
• Produção: https://api2.bancosemear.com.br/oauth/access-token

2. Endpoints Disponíveis #

A API possui dois endpoints principais:

Endpoint	Método	Função
https://hmlapi2.bancosemear.com.br/api-simulation/v2/public/simulation/calcular-refinanciamento	POST	Calcula a operação de REFIN
https://hmlapi2.bancosemear.com.br/api-simulation/v2/public/simulation/calcular-portabilidade	POST	Calcula a operação de PORT

3. Simulação – Cálculo do REFIN #

POST /v2/public/simulation/calcular-refinanciamento #

Descrição #

Calcula o prazo com base na taxa de juros, parcela, datas da operação e saldo devedor do cliente

Parâmetros considerados:

• Saldo devedor
• Parcela
• Taxa mensal oferta (monthlyTax)
• Datas da operação e do primeiro vencimento (operationDate / firstDueDate)

Headers Parameters #

client_id
access_token

Payload – CreateCreditCommand #

{
  "operationDate": "2025-12-17",
  "monthlyTax": 0.00109,
  "term": 10,
  "outstandingBalanceAmount": 1000,
  "installmentValue": 1000,
  "amountFinanced": 5000
}

Campos obrigatórios #

Campo	Tipo	Formato/precisão	Descrição
operationDate	string (date)	YYYY-MM-DD	Data da operação
term	number	Número inteiro	Número de parcelas
monthlyTax	number	Máximo de 4 casas decimais	Taxa nominal mensal (ex.: 1.09 = 1,09% a.m.).*
outstanding_balance_amount	number	Máximo de 2 casas decimais	Saldo devedor do cliente
installmentValue	number	Máximo de 2 casas decimais	Valor da parcela
amountFinanced	number	Máximo de 2 casas decimais	Valor total refinanciado

*A taxa inserida na API é conforme taxa simulada sem o percentual, conforme exemplo acima.

Resposta – 200 OK (exemplo)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "financedAmount": "string",
  "requestedAmount": "string",
  "installmentAmount": "string",
  "annualRate": "string",
  "monthlyRate": "string",
  "dailyRate": "string",
  "operationIOF": "string",
  "annualCET": "string",
  "monthlyCET": "string",
  "customerChangeAmount": "string",
  "installments": [
    {
      "installmentNumber": 0,
      "dueDate": "string",
      "installmentAmount": "string",
      "installmentAmountCET": "string",
      "termDays": 0,
      "cumulativeTermDays": 0,
      "installmentOutstandingBalance": "string",
      "installmentAmortizationAmount": "string",
      "installmentInterestAmount": "string",
      "installmentDailyIOF": "string",
      "installmentAdditionalIOF": "string",
      "totalIOF": "string",
      "currentInstallmentAmount": "string"
    }
  ]
}

Principais saídas: #

• financedAmount (valor financiado)
• requestedAmount (valor solicitado)
• operationIOF (IOF da operação)
• annualCET / monthlyCET (CET anual e mensal)
• installments (detalhamento de parcelas)

4. Simulação – Cálculo de Parcelas – Portabilidade #

POST /v2/public/simulation/calcular-portabilidade #

Descrição #

Calcula o fluxo de parcelas (incluindo IOF e CET) com base no valor financiado, taxa de juros, prazo e datas da operação.

Parâmetros considerados:

• Valor do saldo devedor do cliente (amountFinanced)
• Prazo (term)
• Taxa mensal (monthlyTax)
• Datas da operação e do primeiro vencimento (operationDate / firstDueDate)

Headers Parameters #

client_id
access_token

Payload – CreateInstallmentsCommand #

{
  "operationDate": "2025-12-17",
  "monthlyTax": 0.00109,
  "term": 10,
  "outstandingBalanceAmount": 1000
}

*A taxa inserida na API é conforme taxa simulada sem o percentual, conforme exemplo acima.

Campos obrigatórios #

Campo	Tipo	Descrição
operationDate	string (date)	Data da operação (formato YYYY-MM-DD).
monthlyTax	number	Taxa nominal mensal em decimal (ex.: 1.09 = 1,09% a.m.).*
term	integer	Número de parcelas.
outstandingBalanceAmount	number	Saldo devedor do cliente

Resposta – 200 OK (exemplo)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "financedAmount": "string",
  "requestedAmount": "string",
  "installmentAmount": "string",
  "annualRate": "string",
  "monthlyRate": "string",
  "dailyRate": "string",
  "operationIOF": "string",
  "annualCET": "string",
  "monthlyCET": "string",
  "customerChangeAmount": "string",
  "installments": [
    {
      "installmentNumber": 0,
      "dueDate": "string",
      "installmentAmount": "string",
      "installmentAmountCET": "string",
      "termDays": 0,
      "cumulativeTermDays": 0,
      "installmentOutstandingBalance": "string",
      "installmentAmortizationAmount": "string",
      "installmentInterestAmount": "string",
      "installmentDailyIOF": "string",
      "installmentAdditionalIOF": "string",
      "totalIOF": "string",
      "currentInstallmentAmount": "string"
    }
  ]
}

Principais saídas: #

• installmentAmount – resultado principal
• annualCET – CET anual
• monthlyCET – CET mensal
• annualRate, monthlyRate, dailyRate – Taxas efetivas (anual, mensal, diária)
• installments – Parcelas detalhadas

5. Estruturas de Erro #

Este passo tem por finalidade atualizar uma cobrança PIX imediato.

400 – Bad Request

[
  { 
    "code": 1073741824, 
    "title": null, 
    "detail": null
  }
] 

500 – Internal Server Error

{
  "code": 1073741824, 
  "title": null, 
  "detail": null 
}