Exemplo: Empréstimo Pessoal

Este guia demonstra como criar um produto de empréstimo pessoal completo, incluindo configuração de taxas, tarifas (TAC), IOF e cálculo do CET.

Visão Geral

Para simular um empréstimo pessoal completo, utilizamos dois Building Blocks:

Building Block	Função
Products	Armazena a configuração do produto (taxas, limites, tarifas)
Calculations Engine	Realiza os cálculos financeiros (parcela, IOF, CET, amortização)

Fluxo Completo

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   1. Criar      │     │   2. Simular     │     │   3. Calcular   │
│    Produto      │────▶│    Parcela       │────▶│   IOF e CET     │
│   (Products)    │     │  (Calculations)  │     │  (Calculations) │
└─────────────────┘     └──────────────────┘     └─────────────────┘

Passo 1: Autenticação

Primeiro, faça login para obter o token de acesso. É necessário informar o organizationId para ter as permissões corretas.

cURL
JavaScript

curl -X POST 'https://iam.stg.catalisa.app/api/v1/users/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "seu-email@empresa.com",
    "password": "sua-senha",
    "organizationId": "b0000000-0000-0000-0000-000000000001"
  }'

const loginResponse = await fetch('https://iam.stg.catalisa.app/api/v1/users/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'seu-email@empresa.com',
    password: 'sua-senha',
    organizationId: 'b0000000-0000-0000-0000-000000000001',
  }),
});

const { accessToken } = await loginResponse.json();

Importante

O organizationId é obrigatório para obter as permissões necessárias (PRODUCTS_CREATE, CALCULATIONS_EXECUTE).

Passo 2: Criar Produto de Empréstimo Pessoal

Crie o produto com todas as configurações de taxas, tarifas e IOF.

Configurações Típicas para Empréstimo Pessoal

Campo	Descrição	Valor Típico
`minInterestRate` / `maxInterestRate`	Taxa de juros mensal	1,5% a 4,5% a.m.
`registrationTariffRate`	TAC (Taxa de Abertura de Crédito)	2% a 5%
`insuranceRate`	Seguro prestamista	0,3% a 0,8%
`iofAdditionalRate`	IOF adicional (fixo por lei)	0,38%
`iofDailyRate`	IOF diário (máx 3% a.a.)	0,0082%/dia
`amortizationMethod`	Sistema de amortização	`PRICE` ou `SAC`

cURL
JavaScript

curl -X POST 'https://products.stg.catalisa.app/api/v1/products' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "attributes": {
        "name": "Crédito Pessoal Plus",
        "productType": "PERSONAL_LOAN",
        "description": "Empréstimo pessoal com taxas competitivas. Ideal para realização de sonhos e projetos pessoais.",
        "active": true,
        "minAmount": { "amount": 1000, "currency": "BRL" },
        "maxAmount": { "amount": 100000, "currency": "BRL" },
        "minInterestRate": 0.015,
        "maxInterestRate": 0.045,
        "minInstallments": 6,
        "maxInstallments": 84,
        "registrationTariffRate": 0.02,
        "insuranceRate": 0.005,
        "iofAdditionalRate": 0.0038,
        "iofDailyRate": 0.000082,
        "amortizationMethod": "PRICE"
      }
    }
  }'

const productResponse = await fetch('https://products.stg.catalisa.app/api/v1/products', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      attributes: {
        name: 'Crédito Pessoal Plus',
        productType: 'PERSONAL_LOAN',
        description: 'Empréstimo pessoal com taxas competitivas.',
        active: true,
        minAmount: { amount: 1000, currency: 'BRL' },
        maxAmount: { amount: 100000, currency: 'BRL' },
        minInterestRate: 0.015,
        maxInterestRate: 0.045,
        minInstallments: 6,
        maxInstallments: 84,
        registrationTariffRate: 0.02,
        insuranceRate: 0.005,
        iofAdditionalRate: 0.0038,
        iofDailyRate: 0.000082,
        amortizationMethod: 'PRICE',
      },
    },
  }),
});

const product = await productResponse.json();
console.log('Produto criado:', product.data.id);

Response (201 Created)

{
  "data": {
    "type": "products",
    "id": "a86d7851-a21b-4f0e-ab72-37fc95159919",
    "attributes": {
      "name": "Crédito Pessoal Plus",
      "productType": "PERSONAL_LOAN",
      "active": true,
      "minAmount": { "amount": 1000, "currency": "BRL" },
      "maxAmount": { "amount": 100000, "currency": "BRL" },
      "minInterestRate": 0.015,
      "maxInterestRate": 0.045,
      "minInstallments": 6,
      "maxInstallments": 84,
      "registrationTariffRate": 0.02,
      "insuranceRate": 0.005,
      "iofAdditionalRate": 0.0038,
      "iofDailyRate": 0.000082,
      "amortizationMethod": "PRICE",
      "createdAt": "2026-01-25T18:02:11.835Z"
    }
  }
}

Passo 3: Calcular Parcela Mensal (PMT)

Com o produto configurado, calcule a parcela mensal para uma simulação específica.

Cenário: Empréstimo de R$ 50.000,00 a 2% a.m. em 48 meses.

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": {
      "attributes": {
        "interestRate": 0.02,
        "numberOfPayments": 48,
        "presentValue": 50000
      }
    }
  }'

const pmtResponse = await fetch(
  'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-payment-calculator/calculations',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        attributes: {
          interestRate: 0.02,
          numberOfPayments: 48,
          presentValue: 50000,
        },
      },
    }),
  }
);

const { data } = await pmtResponse.json();
console.log('Parcela mensal: R$', data.attributes.payment);

Response

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

Resultado: Parcela mensal de R$ 1.630,09

Passo 4: Gerar Cronograma de Amortização

Gere a tabela completa de amortização para visualizar a evolução do saldo devedor.

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": {
      "attributes": {
        "principal": 50000,
        "interestRate": 0.02,
        "numberOfPayments": 48,
        "firstPaymentDate": "2026-02-25T00:00:00.000Z",
        "method": "PRICE"
      }
    }
  }'

const amortResponse = await fetch(
  'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-amortization-schedule-calculator/calculations',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        attributes: {
          principal: 50000,
          interestRate: 0.02,
          numberOfPayments: 48,
          firstPaymentDate: '2026-02-25T00:00:00.000Z',
          method: 'PRICE',
        },
      },
    }),
  }
);

const amortization = await amortResponse.json();
console.log('Total pago:', amortization.data.attributes.totalAmount);
console.log('Total juros:', amortization.data.attributes.totalInterest);

Response (resumido)

{
  "data": {
    "type": "loan-amortization-schedule",
    "attributes": {
      "totalAmount": 78244.41,
      "totalInterest": 28244.41,
      "amortizationSchedule": [
        {
          "paymentNumber": 1,
          "paymentDate": "2026-02-25T00:00:00.000Z",
          "beginningBalance": 50000,
          "payment": 1630.09,
          "principalPayment": 630.09,
          "interestPayment": 1000,
          "remainingBalance": 49369.91
        },
        {
          "paymentNumber": 2,
          "paymentDate": "2026-03-25T00:00:00.000Z",
          "beginningBalance": 49369.91,
          "payment": 1630.09,
          "principalPayment": 642.69,
          "interestPayment": 987.40,
          "remainingBalance": 48727.21
        }
      ]
    }
  }
}

Passo 5: Calcular IOF

O IOF é calculado com base no cronograma de amortização. São duas componentes:

IOF Adicional: 0,38% fixo sobre o valor financiado
IOF Diário: 0,0082% por dia, calculado sobre cada parcela de principal

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": {
      "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": 50000,
            "payment": 1630.09,
            "principalPayment": 630.09,
            "interestPayment": 1000,
            "remainingBalance": 49369.91
          }
        ]
      }
    }
  }'

// Use o cronograma completo obtido no passo anterior
const iofResponse = await fetch(
  'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-iof-calculator/calculations',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      '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": 190.00,
        "dailyTotal": 1385.00,
        "total": 1575.00
      },
      "iofFinanced": {
        "additionalTotal": 196.18,
        "dailyTotal": 1430.05,
        "total": 1626.23
      }
    }
  }
}

IOF Financiado

O campo iofFinanced mostra o valor do IOF caso ele seja incluído no valor financiado (IOF sobre IOF).

Passo 6: Calcular CET (Custo Efetivo Total)

O CET representa o custo total do crédito para o cliente, expresso em taxa anual.

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": {
      "attributes": {
        "payment": 1630.09,
        "numberOfPayments": 48,
        "chosenAmount": 50000
      }
    }
  }'

const cetResponse = await fetch(
  'https://calculations-engine.stg.catalisa.app/api/v1/calculations/loan-cet-rate-calculator/calculations',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        attributes: {
          payment: 1630.09,
          numberOfPayments: 48,
          chosenAmount: 50000,
        },
      },
    }),
  }
);

const cet = await cetResponse.json();
console.log('CET Mensal:', (cet.data.attributes.cetMonthlyRate.rounded * 100) + '% a.m.');
console.log('CET Anual:', (cet.data.attributes.cetYearlyRate.rounded * 100) + '% a.a.');

Response

{
  "data": {
    "type": "loan-cet-calculation",
    "attributes": {
      "cetMonthlyRate": {
        "highPrecision": 0.019999946416723174,
        "rounded": 0.02
      },
      "cetYearlyRate": {
        "highPrecision": 0.26824099507393795,
        "rounded": 0.2682
      }
    }
  }
}

Resultado: CET de 2,00% a.m. ou 26,82% a.a.

Resumo da Simulação

Item	Valor
Valor Solicitado	R$ 50.000,00
Taxa de Juros	2,00% a.m.
Prazo	48 meses
Parcela Mensal	R$ 1.630,09
Total de Parcelas	R$ 78.244,41
Total de Juros	R$ 28.244,41
TAC (2%)	R$ 1.000,00
Seguro (0,5%)	R$ 250,00
IOF Adicional (0,38%)	R$ 190,00
IOF Diário	R$ 1.385,00
IOF Total	R$ 1.575,00
CET Mensal	2,00% a.m.
CET Anual	26,82% a.a.

Endpoints Utilizados

Operação	Endpoint	Permissão
Login	`POST /iam/api/v1/users/login`	-
Criar Produto	`POST /products/api/v1/products`	`PRODUCTS_CREATE`
Calcular Parcela	`POST /calculations-engine/api/v1/calculations/loan-payment-calculator/calculations`	`CALCULATIONS_EXECUTE`
Cronograma	`POST /calculations-engine/api/v1/calculations/loan-amortization-schedule-calculator/calculations`	`CALCULATIONS_EXECUTE`
Calcular IOF	`POST /calculations-engine/api/v1/calculations/loan-iof-calculator/calculations`	`CALCULATIONS_EXECUTE`
Calcular CET	`POST /calculations-engine/api/v1/calculations/loan-cet-rate-calculator/calculations`	`CALCULATIONS_EXECUTE`

Próximos Passos

Configure Pricing Rules para definir regras de TAC por faixa de risco
Use Risk Bands para taxas de juros baseadas em score de crédito
Integre com Decision Engine para automação de análise de crédito

Visão Geral​

Fluxo Completo​

Passo 1: Autenticação​

Passo 2: Criar Produto de Empréstimo Pessoal​

Configurações Típicas para Empréstimo Pessoal​

Response (201 Created)​

Passo 3: Calcular Parcela Mensal (PMT)​

Response​

Passo 4: Gerar Cronograma de Amortização​

Response (resumido)​

Passo 5: Calcular IOF​

Response​

Passo 6: Calcular CET (Custo Efetivo Total)​

Response​

Resumo da Simulação​

Endpoints Utilizados​

Próximos Passos​

Visão Geral

Fluxo Completo

Passo 1: Autenticação

Passo 2: Criar Produto de Empréstimo Pessoal

Configurações Típicas para Empréstimo Pessoal

Response (201 Created)

Passo 3: Calcular Parcela Mensal (PMT)

Response

Passo 4: Gerar Cronograma de Amortização

Response (resumido)

Passo 5: Calcular IOF

Response

Passo 6: Calcular CET (Custo Efetivo Total)

Response

Resumo da Simulação

Endpoints Utilizados

Próximos Passos