Exemplo: Financiamento Imobiliário

Este guia demonstra como criar um produto de financiamento imobiliário com parcela balão (BALLOON), incluindo configuração de LTV, taxas e simulação completa.

Visão Geral

O financiamento imobiliário com parcela balão é ideal para clientes que esperam uma entrada de recursos futura (venda de outro imóvel, recebimento de herança, etc.) e desejam parcelas menores durante o contrato.

Característica	Descrição
Tipo de Produto	`MORTGAGE`
Método de Amortização	`BALLOON`
Diferencial	Parcela final (balão) com percentual do principal
Campos Exclusivos	`minLtv`, `maxLtv` (Loan-to-Value)

O que é LTV (Loan-to-Value)?

O LTV representa a relação entre o valor financiado e o valor do imóvel:

LTV = Valor Financiado / Valor do Imóvel

Exemplo: Para um imóvel de R$ 500.000,00 com LTV máximo de 80%, o cliente pode financiar até R$ 400.000,00.

Passo 1: Criar Produto de Financiamento Imobiliário

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": {
      "type": "products",
      "attributes": {
        "name": "Financiamento Imobiliário Premium",
        "productType": "MORTGAGE",
        "description": "Financiamento imobiliário com parcela balão de 30%. Ideal para clientes que esperam entrada de recursos futura.",
        "active": true,
        "minAmount": { "amount": 100000, "currency": "BRL" },
        "maxAmount": { "amount": 2000000, "currency": "BRL" },
        "minInterestRate": 0.007,
        "maxInterestRate": 0.012,
        "minInstallments": 60,
        "maxInstallments": 360,
        "amortizationMethod": "BALLOON",
        "amortizationConfig": {
          "type": "BALLOON",
          "config": {
            "balloonPercentage": 0.30
          }
        },
        "gracePeriodMonths": 3,
        "minLtv": 0.50,
        "maxLtv": 0.80,
        "registrationTariffRate": 0.01,
        "insuranceRate": 0.0003,
        "iofAdditionalRate": 0.0038,
        "iofDailyRate": 0.000082,
        "metadata": {
          "segmento": "alta_renda",
          "garantia": "alienacao_fiduciaria",
          "documentacao_minima": ["matricula", "iptu", "certidoes"]
        }
      }
    }
  }'

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: {
      type: 'products',
      attributes: {
        name: 'Financiamento Imobiliário Premium',
        productType: 'MORTGAGE',
        description: 'Financiamento imobiliário com parcela balão de 30%.',
        active: true,
        minAmount: { amount: 100000, currency: 'BRL' },
        maxAmount: { amount: 2000000, currency: 'BRL' },
        minInterestRate: 0.007,
        maxInterestRate: 0.012,
        minInstallments: 60,
        maxInstallments: 360,
        amortizationMethod: 'BALLOON',
        amortizationConfig: {
          type: 'BALLOON',
          config: {
            balloonPercentage: 0.30,
          },
        },
        gracePeriodMonths: 3,
        minLtv: 0.50,
        maxLtv: 0.80,
        registrationTariffRate: 0.01,
        insuranceRate: 0.0003,
        iofAdditionalRate: 0.0038,
        iofDailyRate: 0.000082,
        metadata: {
          segmento: 'alta_renda',
          garantia: 'alienacao_fiduciaria',
        },
      },
    },
  }),
});

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

Response (201 Created)

{
  "data": {
    "type": "products",
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "attributes": {
      "name": "Financiamento Imobiliário Premium",
      "productType": "MORTGAGE",
      "active": true,
      "minAmount": { "amount": 100000, "currency": "BRL" },
      "maxAmount": { "amount": 2000000, "currency": "BRL" },
      "minInterestRate": 0.007,
      "maxInterestRate": 0.012,
      "minInstallments": 60,
      "maxInstallments": 360,
      "amortizationMethod": "BALLOON",
      "amortizationConfig": {
        "type": "BALLOON",
        "config": {
          "balloonPercentage": 0.30
        }
      },
      "gracePeriodMonths": 3,
      "minLtv": 0.50,
      "maxLtv": 0.80,
      "metadata": {
        "segmento": "alta_renda",
        "garantia": "alienacao_fiduciaria"
      },
      "createdAt": "2026-01-26T18:00:00.000Z"
    }
  }
}

Passo 2: Gerar Cronograma de Amortização BALLOON

Cenário: Financiamento de R$ 400.000,00 a 0.9% a.m. em 120 meses com balão de 30%.

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": 400000,
        "interestRate": 0.009,
        "numberOfPayments": 120,
        "firstPaymentDate": "2026-03-01T00:00:00.000Z",
        "method": "BALLOON",
        "balloonConfig": {
          "balloonPercentage": 0.30
        }
      }
    }
  }'

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: {
        type: 'loan-amortization-schedule',
        attributes: {
          principal: 400000,
          interestRate: 0.009,
          numberOfPayments: 120,
          firstPaymentDate: '2026-03-01T00:00:00.000Z',
          method: 'BALLOON',
          balloonConfig: {
            balloonPercentage: 0.30,
          },
        },
      },
    }),
  }
);

const amortization = await amortResponse.json();

Response (resumido)

{
  "data": {
    "type": "loan-amortization-schedule",
    "attributes": {
      "totalAmount": 524875.32,
      "totalInterest": 124875.32,
      "amortizationSchedule": [
        {
          "paymentNumber": 1,
          "paymentDate": "2026-03-01T00:00:00.000Z",
          "beginningBalance": 400000.00,
          "payment": 4287.93,
          "principalPayment": 687.93,
          "interestPayment": 3600.00,
          "remainingBalance": 399312.07
        },
        {
          "paymentNumber": 2,
          "paymentDate": "2026-04-01T00:00:00.000Z",
          "beginningBalance": 399312.07,
          "payment": 4287.93,
          "principalPayment": 694.12,
          "interestPayment": 3593.81,
          "remainingBalance": 398617.95
        },
        "...",
        {
          "paymentNumber": 120,
          "paymentDate": "2036-02-01T00:00:00.000Z",
          "beginningBalance": 120000.00,
          "payment": 121080.00,
          "principalPayment": 120000.00,
          "interestPayment": 1080.00,
          "remainingBalance": 0.00
        }
      ]
    }
  }
}

Parcela Balão

Note que a última parcela (nº 120) é significativamente maior: R$ 121.080,00. Isso inclui os 30% do principal (R$ 120.000,00) mais os juros do período.

Comparativo: BALLOON vs PRICE

Aspecto	BALLOON (30%)	PRICE
Parcelas 1-119	R$ 4.287,93	R$ 5.196,40
Parcela 120	R$ 121.080,00	R$ 5.196,40
Total Pago	R$ 524.875,32	R$ 623.568,00
Total de Juros	R$ 124.875,32	R$ 223.568,00

Economia de Juros

O método BALLOON pode gerar economia de juros significativa, pois o saldo devedor é reduzido mais rapidamente com o pagamento do balão.

Validações de Negócio

Regra	Validação
LTV só para MORTGAGE	Campos `minLtv`/`maxLtv` retornam erro 400 para outros tipos de produto
Balloon entre 1% e 99%	`balloonPercentage` deve estar entre 0.01 e 0.99
Config obrigatória	Método BALLOON requer `amortizationConfig` com tipo BALLOON

Erros Comuns

Código	Erro	Solução
400	"LTV fields only allowed for MORTGAGE"	Use `productType: 'MORTGAGE'`
400	"balloonPercentage must be between 0.01 and 0.99"	Ajuste o percentual do balão
400	"BALLOON method requires amortizationConfig"	Adicione `amortizationConfig` no request

Próximos Passos

Configure Pricing Rules para taxas baseadas em LTV
Use Decision Engine para análise de documentação do imóvel
Integre com E-Signature para assinatura digital do contrato

Visão Geral​

O que é LTV (Loan-to-Value)?​

Passo 1: Criar Produto de Financiamento Imobiliário​

Response (201 Created)​

Passo 2: Gerar Cronograma de Amortização BALLOON​

Response (resumido)​

Comparativo: BALLOON vs PRICE​

Validações de Negócio​

Erros Comuns​

Próximos Passos​