Calculadoras

Endpoints de cálculo financeiro no Calculations Engine.

Todas as calculadoras requerem a permissão CALCULATIONS_EXECUTE.

Calcular Parcela

POST /loan-payment-calculator/calculations

Calcula o valor da parcela mensal (PMT).

Request

Campo	Tipo	Obrigatório	Descrição
`interestRate`	number	Sim	Taxa de juros mensal (decimal)
`numberOfPayments`	integer	Sim	Número de parcelas
`presentValue`	number	Sim	Valor financiado

cURL
JavaScript

curl -X POST 'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-payment-calculator/calculations' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "loan-payment-calculation",
      "attributes": {
        "interestRate": 0.0199,
        "numberOfPayments": 24,
        "presentValue": 10000
      }
    }
  }'

const response = await fetch(
  'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-payment-calculator/calculations',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        type: 'loan-payment-calculation',
        attributes: {
          interestRate: 0.0199,
          numberOfPayments: 24,
          presentValue: 10000,
        },
      },
    }),
  }
);

const result = await response.json();
console.log('Parcela:', result.data.attributes.payment);

Response

{
  "data": {
    "type": "loan-payment-calculation",
    "attributes": {
      "payment": 508.76
    }
  }
}

Calcular Coeficiente

POST /loan-coefficient-calculator/calculations

Calcula o coeficiente de amortização.

Request

Campo	Tipo	Obrigatório	Descrição
`interestRate`	number	Sim	Taxa de juros mensal
`numberOfPayments`	integer	Sim	Número de parcelas

cURL
JavaScript

curl -X POST 'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-coefficient-calculator/calculations' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "loan-coefficient-calculation",
      "attributes": {
        "interestRate": 0.0199,
        "numberOfPayments": 24
      }
    }
  }'

const response = await fetch(
  'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-coefficient-calculator/calculations',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        type: 'loan-coefficient-calculation',
        attributes: {
          interestRate: 0.0199,
          numberOfPayments: 24,
        },
      },
    }),
  }
);

const result = await response.json();

Response

{
  "data": {
    "type": "loan-coefficient-calculation",
    "attributes": {
      "coefficient": 0.050876
    }
  }
}

Calcular Custos

POST /loan-costs-calculator/calculations

Soma os custos de um empréstimo.

Request

Campo	Tipo	Obrigatório	Descrição
`costs`	array	Sim	Lista de custos
`costs[].description`	string	Sim	Descrição do custo
`costs[].amount`	number	Sim	Valor do custo

cURL
JavaScript

curl -X POST 'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-costs-calculator/calculations' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "loan-costs-calculation",
      "attributes": {
        "costs": [
          { "description": "Taxa de cadastro", "amount": 200 },
          { "description": "Seguro", "amount": 150 },
          { "description": "IOF", "amount": 38 }
        ]
      }
    }
  }'

const response = await fetch(
  'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-costs-calculator/calculations',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        type: 'loan-costs-calculation',
        attributes: {
          costs: [
            { description: 'Taxa de cadastro', amount: 200 },
            { description: 'Seguro', amount: 150 },
            { description: 'IOF', amount: 38 },
          ],
        },
      },
    }),
  }
);

const result = await response.json();

Response

{
  "data": {
    "type": "loan-costs-calculation",
    "attributes": {
      "totalCosts": 388
    }
  }
}

Calcular Taxa de Juros

POST /loan-interest-rate-calculator/calculations

Converte entre taxa mensal e anual.

Request

Campo	Tipo	Obrigatório	Descrição
`monthlyRate`	number	Condicional	Taxa mensal (se converter para anual)
`yearlyRate`	number	Condicional	Taxa anual (se converter para mensal)

cURL
JavaScript

curl -X POST 'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-interest-rate-calculator/calculations' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "loan-interest-rate-calculation",
      "attributes": {
        "monthlyRate": 0.0199
      }
    }
  }'

const response = await fetch(
  'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-interest-rate-calculator/calculations',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        type: 'loan-interest-rate-calculation',
        attributes: {
          monthlyRate: 0.0199,
        },
      },
    }),
  }
);

const result = await response.json();

Response

{
  "data": {
    "type": "loan-interest-rate-calculation",
    "attributes": {
      "monthlyRate": {
        "highPrecision": 0.0199,
        "rounded": 0.02
      },
      "yearlyRate": {
        "highPrecision": 0.26679,
        "rounded": 0.27
      }
    }
  }
}

Calcular Datas de Pagamento

POST /loan-payment-dates-calculator/calculations

Gera as datas de pagamento.

Request

Campo	Tipo	Obrigatório	Descrição
`firstPaymentDate`	string	Sim	Data do primeiro pagamento (ISO 8601)
`numberOfPayments`	integer	Sim	Número de parcelas

cURL
JavaScript

curl -X POST 'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-payment-dates-calculator/calculations' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "loan-payment-dates-calculation",
      "attributes": {
        "firstPaymentDate": "2024-02-15T00:00:00Z",
        "numberOfPayments": 12
      }
    }
  }'

const response = await fetch(
  'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-payment-dates-calculator/calculations',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        type: 'loan-payment-dates-calculation',
        attributes: {
          firstPaymentDate: '2024-02-15T00:00:00Z',
          numberOfPayments: 12,
        },
      },
    }),
  }
);

const result = await response.json();

Response

{
  "data": {
    "type": "loan-payment-dates-calculation",
    "attributes": {
      "paymentDates": [
        "2024-02-15T00:00:00Z",
        "2024-03-15T00:00:00Z",
        "2024-04-15T00:00:00Z",
        "..."
      ]
    }
  }
}

Calcular CET

POST /loan-cet-rate-calculator/calculations

Calcula o Custo Efetivo Total.

Request

Campo	Tipo	Obrigatório	Descrição
`payment`	number	Sim	Valor da parcela
`numberOfPayments`	integer	Sim	Número de parcelas
`chosenAmount`	number	Sim	Valor liquido liberado

cURL
JavaScript

curl -X POST 'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-cet-rate-calculator/calculations' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "loan-cet-calculation",
      "attributes": {
        "payment": 508.76,
        "numberOfPayments": 24,
        "chosenAmount": 9500
      }
    }
  }'

const response = await fetch(
  'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-cet-rate-calculator/calculations',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        type: 'loan-cet-calculation',
        attributes: {
          payment: 508.76,
          numberOfPayments: 24,
          chosenAmount: 9500,
        },
      },
    }),
  }
);

const result = await response.json();

Response

{
  "data": {
    "type": "loan-cet-calculation",
    "attributes": {
      "cetMonthlyRate": {
        "highPrecision": 0.024567,
        "rounded": 0.0246
      },
      "cetYearlyRate": {
        "highPrecision": 0.335678,
        "rounded": 0.3357
      }
    }
  }
}

Calcular IOF

POST /loan-iof-calculator/calculations

Calcula o IOF do empréstimo com base no cronograma de amortização.

informação

O cálculo do IOF requer o cronograma de amortização completo para calcular corretamente o IOF diário sobre cada parcela de principal. Veja o exemplo completo de empréstimo pessoal para um fluxo integrado.

Request

Campo	Tipo	Obrigatório	Descrição
`additionalIofRate`	number	Sim	IOF adicional (0.0038 = 0,38%)
`dailyIofRate`	number	Sim	IOF diário (0.000082 = 0,0082%/dia)
`contractDate`	string	Sim	Data do contrato (ISO 8601)
`amortizationSchedule`	array	Sim	Cronograma de amortização

Estrutura do amortizationSchedule

Campo	Tipo	Descrição
`paymentNumber`	integer	Número da parcela
`paymentDate`	string	Data do pagamento (ISO 8601)
`beginningBalance`	number	Saldo inicial
`payment`	number	Valor da parcela
`principalPayment`	number	Amortização
`interestPayment`	number	Juros
`remainingBalance`	number	Saldo final

cURL
JavaScript

curl -X POST 'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-iof-calculator/calculations' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "loan-iof-calculation",
      "attributes": {
        "additionalIofRate": 0.0038,
        "dailyIofRate": 0.000082,
        "contractDate": "2026-01-25T00:00:00.000Z",
        "amortizationSchedule": [
          {
            "paymentNumber": 1,
            "paymentDate": "2026-02-25T00:00:00.000Z",
            "beginningBalance": 10000,
            "payment": 932.66,
            "principalPayment": 733.66,
            "interestPayment": 199.00,
            "remainingBalance": 9266.34
          },
          {
            "paymentNumber": 2,
            "paymentDate": "2026-03-25T00:00:00.000Z",
            "beginningBalance": 9266.34,
            "payment": 932.66,
            "principalPayment": 748.26,
            "interestPayment": 184.40,
            "remainingBalance": 8518.08
          }
        ]
      }
    }
  }'

// Primeiro, obtenha o cronograma de amortização
const amortResponse = await fetch(
  'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-amortization-schedule-calculator/calculations',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        attributes: {
          principal: 10000,
          interestRate: 0.0199,
          numberOfPayments: 12,
          firstPaymentDate: '2026-02-25T00:00:00.000Z',
          method: 'PRICE',
        },
      },
    }),
  }
);

const amortization = await amortResponse.json();

// Depois, calcule o IOF
const iofResponse = await fetch(
  'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-iof-calculator/calculations',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        attributes: {
          additionalIofRate: 0.0038,
          dailyIofRate: 0.000082,
          contractDate: '2026-01-25T00:00:00.000Z',
          amortizationSchedule: amortization.data.attributes.amortizationSchedule,
        },
      },
    }),
  }
);

const iof = await iofResponse.json();
console.log('IOF Total:', iof.data.attributes.iof.total);

Response

{
  "data": {
    "type": "loan-iof-calculation",
    "attributes": {
      "iof": {
        "additionalTotal": 38.00,
        "dailyTotal": 114.30,
        "total": 152.30
      },
      "iofFinanced": {
        "additionalTotal": 38.15,
        "dailyTotal": 114.75,
        "total": 152.90
      }
    }
  }
}

IOF Financiado

O campo iofFinanced mostra o valor do IOF caso ele seja incluído no valor financiado, calculando o IOF sobre o IOF (cenário comum em operações de crédito).

Gerar Tabela de Amortização

POST /loan-amortization-schedule-calculator/calculations

Gera a tabela completa de amortização com suporte a múltiplos métodos.

Request

Campo	Tipo	Obrigatório	Descrição
`principal`	number	Sim	Valor principal
`interestRate`	number	Sim	Taxa de juros mensal
`numberOfPayments`	integer	Sim	Número de parcelas
`firstPaymentDate`	string	Sim	Data do primeiro pagamento
`method`	string	Sim	Método de amortização
`gracePeriodMonths`	integer	Não	Meses de carência
`balloonConfig`	object	Condicional	Config para BALLOON
`interestOnlyConfig`	object	Condicional	Config para INTEREST_ONLY
`stepConfig`	object	Condicional	Config para STEP_UP/STEP_DOWN
`customConfig`	object	Condicional	Config para CUSTOM

Métodos Suportados

Método	Descrição	Configuração
`PRICE`	Tabela Price - parcelas fixas	Nenhuma
`SAC`	Sistema de Amortização Constante	Nenhuma
`BALLOON`	Parcelas menores + balão no final	`balloonConfig`
`BULLET`	Apenas juros até o vencimento	Nenhuma
`INTEREST_ONLY`	Carência de amortização	`interestOnlyConfig`
`STEP_UP`	Parcelas crescentes	`stepConfig`
`STEP_DOWN`	Parcelas decrescentes	`stepConfig`
`CUSTOM`	Cronograma personalizado	`customConfig`

cURL
JavaScript

curl -X POST 'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-amortization-schedule-calculator/calculations' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "loan-amortization-schedule",
      "attributes": {
        "principal": 10000,
        "interestRate": 0.0199,
        "numberOfPayments": 12,
        "firstPaymentDate": "2024-02-15T00:00:00Z",
        "method": "PRICE"
      }
    }
  }'

const response = await fetch(
  'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-amortization-schedule-calculator/calculations',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        type: 'loan-amortization-schedule',
        attributes: {
          principal: 10000,
          interestRate: 0.0199,
          numberOfPayments: 12,
          firstPaymentDate: '2024-02-15T00:00:00Z',
          method: 'PRICE',
        },
      },
    }),
  }
);

const result = await response.json();

Response

{
  "data": {
    "type": "loan-amortization-schedule",
    "attributes": {
      "amortizationSchedule": [
        {
          "paymentNumber": 1,
          "paymentDate": "2024-02-15T00:00:00Z",
          "beginningBalance": 10000.00,
          "payment": 932.66,
          "principalPayment": 733.66,
          "interestPayment": 199.00,
          "remainingBalance": 9266.34
        },
        {
          "paymentNumber": 2,
          "paymentDate": "2024-03-15T00:00:00Z",
          "beginningBalance": 9266.34,
          "payment": 932.66,
          "principalPayment": 748.26,
          "interestPayment": 184.40,
          "remainingBalance": 8518.08
        }
      ],
      "totalAmount": 11191.92,
      "totalInterest": 1191.92
    }
  }
}

Exemplos de Métodos Avançados

BALLOON - Parcela Balão

Parcelas menores durante o contrato com pagamento grande no final.

cURL

curl -X POST 'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-amortization-schedule-calculator/calculations' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "loan-amortization-schedule",
      "attributes": {
        "principal": 100000,
        "interestRate": 0.01,
        "numberOfPayments": 24,
        "firstPaymentDate": "2024-02-15T00:00:00Z",
        "method": "BALLOON",
        "balloonConfig": {
          "balloonPercentage": 0.30
        }
      }
    }
  }'

informação

Com balloonPercentage: 0.30, 30% do principal será pago na última parcela (balão). As demais parcelas amortizam os outros 70%.

BULLET - Principal no Vencimento

Paga apenas juros mensais e o principal integral no vencimento.

cURL

curl -X POST 'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-amortization-schedule-calculator/calculations' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "loan-amortization-schedule",
      "attributes": {
        "principal": 50000,
        "interestRate": 0.02,
        "numberOfPayments": 12,
        "firstPaymentDate": "2024-02-15T00:00:00Z",
        "method": "BULLET"
      }
    }
  }'

Uso Comum

O método BULLET é comum em operações de capital de giro onde a empresa espera um recebimento futuro para quitar o principal.

INTEREST_ONLY - Carência de Amortização

Período inicial pagando apenas juros, depois amortização normal.

cURL

curl -X POST 'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-amortization-schedule-calculator/calculations' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "loan-amortization-schedule",
      "attributes": {
        "principal": 100000,
        "interestRate": 0.015,
        "numberOfPayments": 24,
        "firstPaymentDate": "2024-02-15T00:00:00Z",
        "method": "INTEREST_ONLY",
        "interestOnlyConfig": {
          "interestOnlyPeriod": 6,
          "postGraceMethod": "PRICE"
        }
      }
    }
  }'

informação

Com interestOnlyPeriod: 6, as primeiras 6 parcelas pagam apenas juros (R$ 1.500,00/mês). A partir da 7ª parcela, inicia a amortização pelo método postGraceMethod (PRICE ou SAC).

STEP_UP - Parcelas Crescentes

Parcelas que aumentam periodicamente, ideal para quem espera crescimento de renda.

cURL

curl -X POST 'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-amortization-schedule-calculator/calculations' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "loan-amortization-schedule",
      "attributes": {
        "principal": 50000,
        "interestRate": 0.02,
        "numberOfPayments": 36,
        "firstPaymentDate": "2024-02-15T00:00:00Z",
        "method": "STEP_UP",
        "stepConfig": {
          "stepPercentage": 0.05,
          "stepInterval": 12
        }
      }
    }
  }'

informação

Com stepPercentage: 0.05 e stepInterval: 12, as parcelas aumentam 5% a cada 12 meses:

Meses 1-12: parcela base
Meses 13-24: parcela base × 1.05
Meses 25-36: parcela base × 1.1025

STEP_DOWN - Parcelas Decrescentes

Parcelas que diminuem periodicamente, ideal para quem quer pagar mais no início.

cURL

curl -X POST 'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-amortization-schedule-calculator/calculations' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "loan-amortization-schedule",
      "attributes": {
        "principal": 50000,
        "interestRate": 0.02,
        "numberOfPayments": 36,
        "firstPaymentDate": "2024-02-15T00:00:00Z",
        "method": "STEP_DOWN",
        "stepConfig": {
          "stepPercentage": 0.05,
          "stepInterval": 12
        }
      }
    }
  }'

CUSTOM - Cronograma Personalizado

Permite definir o valor exato de cada parcela.

cURL

curl -X POST 'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-amortization-schedule-calculator/calculations' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "loan-amortization-schedule",
      "attributes": {
        "principal": 10000,
        "interestRate": 0.02,
        "numberOfPayments": 6,
        "firstPaymentDate": "2024-02-15T00:00:00Z",
        "method": "CUSTOM",
        "customConfig": {
          "paymentSchedule": [1500, 1600, 1700, 1800, 1900, 2500]
        }
      }
    }
  }'

aviso

O total das parcelas no paymentSchedule deve ser suficiente para quitar o principal + juros. Se insuficiente, o sistema ajustará a última parcela.

Erros Comuns

Código	Erro	Descrição
400	`VALIDATION`	Parametros inválidos
403	`FORBIDDEN`	Sem permissão CALCULATIONS_EXECUTE

Calcular Parcela​

Request​

Response​

Calcular Coeficiente​

Request​

Response​

Calcular Custos​

Request​

Response​

Calcular Taxa de Juros​

Request​

Response​

Calcular Datas de Pagamento​

Request​

Response​

Calcular CET​

Request​

Response​

Calcular IOF​

Request​

Estrutura do amortizationSchedule​

Response​

Gerar Tabela de Amortização​

Request​

Métodos Suportados​

Response​

Exemplos de Métodos Avançados​

BALLOON - Parcela Balão​

BULLET - Principal no Vencimento​

INTEREST_ONLY - Carência de Amortização​

STEP_UP - Parcelas Crescentes​

STEP_DOWN - Parcelas Decrescentes​

CUSTOM - Cronograma Personalizado​

Erros Comuns​

Calcular Parcela

Request

Response

Calcular Coeficiente

Request

Response

Calcular Custos

Request

Response

Calcular Taxa de Juros

Request

Response

Calcular Datas de Pagamento

Request

Response

Calcular CET

Request

Response

Calcular IOF

Request

Estrutura do amortizationSchedule

Response

Gerar Tabela de Amortização

Request

Métodos Suportados

Response

Exemplos de Métodos Avançados

BALLOON - Parcela Balão

BULLET - Principal no Vencimento

INTEREST_ONLY - Carência de Amortização

STEP_UP - Parcelas Crescentes

STEP_DOWN - Parcelas Decrescentes

CUSTOM - Cronograma Personalizado

Erros Comuns