Início rápido

Esta página leva você de um banco de dados vazio a um empréstimo desembolsado em seis chamadas. Cada chamada envia application/json. Envie cada campo de dinheiro e de taxa como string decimal, nunca como número JSON. Faça primeiro os Pré-requisitos. Envie o mesmo token bearer nas seis chamadas. O Lender pega o analista do subject do token. Sob o perfil genérico, apenas esse analista pode aprovar e desembolsar a proposta.

Use a jurisdição XX neste passo a passo. XX é o perfil genérico do Lender e não calcula retenções, o que mantém simples os valores do passo 6. Um empréstimo brasileiro regulado carrega divulgação do CET e consentimento de capitalização. Leia o Pacote regulatório Brasil para esse caminho. Um contrato com desconto em folha pertence ao contexto delimitado do consignado privado. Leia Consignado privado para o vocabulário e os tópicos de ciclo de vida dele.

As seis chamadas

POST /api/v1/loan-products                          → productId
POST /api/v1/loan-products/{productId}/versions     → versionId
POST /api/v1/loan-products/{productId}/accounting-profiles
POST /api/v1/loan-applications                      → pending_approval
POST /api/v1/loan-applications/{id}/approve         → approved
POST /api/v1/loan-applications/{id}/disburse        → disbursed

1. Crie o produto

POST /api/v1/loan-products

{
  "name": "Personal loan — generic",
  "loanType": "personal",
  "jurisdictionCode": "XX"
}

loanType aceita personal, commercial ou card. jurisdictionCode aceita um código que o registro carrega: XX ou BR. Qualquer outro código retorna 422. A resposta carrega o novo id. O produto fica em draft, que é tudo o que este passo a passo precisa: uma proposta se prende a uma versão, então você não ativa o produto para originar.

2. Crie uma versão

POST /api/v1/loan-products/{productId}/versions

{
  "jurisdictionCode": "XX",
  "changeReason": "initial version",
  "currency": "USD",
  "rateMode": "fixed",
  "fixedAnnualRateBps": 1800
}

A versão é o retrato imutável dos termos a que uma proposta se prende.

currency não tem padrão. Forneça um código ISO-4217 válido em maiúsculas. A versão é a fonte da verdade da moeda daqui até o ledger.
Uma versão fixa não carrega vínculo flutuante. Com rateMode: fixed, omita floatingRateTableId, floatingSpreadBps e requiresFloatingRate. O Lender rejeita uma versão fixa que carregue qualquer um deles.
jurisdictionCode é obrigatório, e deve bater com o do produto. Uma versão não pode mover um produto para outra jurisdição.

A resposta carrega o versionId.

3. Prenda um perfil contábil

POST /api/v1/loan-products/{productId}/accounting-profiles O perfil mapeia cada evento contábil em contas contábeis. O Lender precisa do perfil no desembolso, então prenda o perfil agora.

{
  "loanProductVersionId": "<versionId>",
  "accountingMode": "accrual",
  "postingRules": [
    {
      "eventType": "disbursement",
      "legs": [
        { "account": "1100.10.001", "role": "principal", "side": "debit" },
        { "account": "1000.10.001", "role": "cash", "side": "credit" }
      ]
    },
    {
      "eventType": "repayment",
      "legs": [
        { "account": "1000.10.001", "role": "cash", "side": "debit" },
        { "account": "1100.10.001", "role": "principal", "side": "credit" }
      ]
    },
    {
      "eventType": "prepayment",
      "legs": [
        { "account": "1000.10.001", "role": "cash", "side": "debit" },
        { "account": "4200.10.001", "component": "charge_rebate", "side": "debit", "optional": true },
        { "account": "4300.10.001", "component": "iof_refund", "side": "debit", "optional": true },
        { "account": "1100.10.001", "role": "principal", "side": "credit" },
        { "account": "2400.10.001", "component": "iof_due", "side": "credit", "optional": true }
      ]
    },
    {
      "eventType": "accrual",
      "legs": [
        { "account": "1200.10.001", "role": "interest", "side": "debit" },
        { "account": "4100.10.001", "role": "interest", "side": "credit" }
      ]
    },
    {
      "eventType": "collection_unapplied",
      "legs": [
        { "account": "1000.10.001", "role": "cash", "side": "debit" },
        { "account": "2100.10.001", "role": "unapplied_cash", "side": "credit" }
      ]
    },
    {
      "eventType": "collection_reapply",
      "legs": [
        { "account": "2100.10.001", "role": "unapplied_cash", "side": "debit" },
        { "account": "1100.10.001", "role": "principal", "side": "credit" }
      ]
    },
    {
      "eventType": "collection_refund",
      "legs": [
        { "account": "2100.10.001", "role": "unapplied_cash", "side": "debit" },
        { "account": "1000.10.001", "role": "cash", "side": "credit" }
      ]
    }
  ]
}

Envie sete ou oito regras, uma por evento contábil. Sete eventos precisam de regra: disbursement, repayment, prepayment, accrual, collection_unapplied, collection_reapply e collection_refund. accrual_tax é a oitava, opcional. Menos de sete regras é rejeitado antes de o handler rodar. Cada perna declara exatamente um entre role e component, e nenhuma conta aparece nos dois lados da mesma regra. Quatro eventos também carregam um formato fixo de pernas:

Evento	Pernas
`accrual`	Exatamente um débito e um crédito.
`prepayment`	Exatamente cinco, nesta ordem: débito de `cash`, débito opcional de `charge_rebate`, débito opcional de `iof_refund`, crédito de `principal`, crédito opcional de `iof_due`.
`collection_unapplied`	Exatamente duas: débito de `cash`, crédito de `unapplied_cash`.
`collection_refund`	Exatamente duas: débito de `unapplied_cash`, crédito de `cash`.

collection_reapply aceita unapplied_cash como único débito. Cada crédito que ela carrega deve aparecer também como crédito em repayment ou prepayment, com a mesma conta e o mesmo papel. disbursement e repayment precisam, cada um, de pelo menos um débito e um crédito. Mantenha a regra disbursement com duas pernas, como acima. O Lender preenche a perna cash com o valor líquido e cada outra perna estrutural com o valor bruto. Uma perna component recebe uma retenção calculada, e o perfil genérico não calcula nenhuma, então a regra de duas pernas é a que balanceia sob XX. No modo multi-tenant o perfil também precisa de midazOrganizationId e midazLedgerId. Leia Defina um produto de empréstimo para a superfície mais ampla do produto.

4. Crie a proposta

POST /api/v1/loan-applications

{
  "loanProductVersionId": "<versionId>",
  "borrowerId": "borrower-0001",
  "requestedPrincipalAmount": "50000.00",
  "requestedInterestRate": "0.01500000",
  "requestedInstallments": 24,
  "expectedDisbursementDate": "2026-08-01T12:00:00Z",
  "previewScheduleSnapshotId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

requestedInterestRate é a taxa mensal como string decimal na escala 8. Ela deve ser maior que 0 e não maior que 1. O Lender monta o cronograma a partir dessa taxa: "0.01500000" ao mês é 1800 bps ao ano.
requestedInstallments fica entre 1 e 600.
previewScheduleSnapshotId é um UUID que você gera para identificar a cotação que você mostrou ao tomador. O Lender registra esse UUID na proposta. Calcule o cronograma que você mostra com POST /api/v1/loan-applications/preview-schedule. Essa chamada não persiste nada e não retorna identificador. Gere o identificador do seu lado e guarde junto com o seu próprio registro de cotação.
Não existe campo assignedOfficerId. O Lender define esse dado a partir do subject do token.

A proposta volta em pending_approval, carregando o código de jurisdição e a versão de perfil que o Lender resolveu a partir da versão do produto.

5. Aprove

POST /api/v1/loan-applications/{id}/approve

{
  "approvedAmount": "48000.00",
  "decisionAt": "2026-08-01T12:00:00Z",
  "note": "within policy"
}

approvedAmount vira o teto de tudo o que você desembolsa. Sob XX, apenas o analista que criou a proposta pode aprová-la. A proposta passa para approved e carrega o registro da decisão.

6. Desembolse

POST /api/v1/loan-applications/{id}/disburse Envie o header X-Idempotency. O Lender exige esse header. Uma nova tentativa com o mesmo valor repete a primeira resposta, e não registra um segundo desembolso.

{
  "loanAccountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "grossRequestedAmount": "48000.00",
  "netDeliveredAmount": "48000.00",
  "disbursedAt": "2026-08-01T13:00:00Z"
}

Sob XX, netDeliveredAmount deve ser igual a grossRequestedAmount. O lançamento de desembolso balanceia com o líquido igual ao bruto menos as retenções, e o perfil genérico não calcula retenções. Qualquer líquido menor deixa o lançamento desbalanceado e o Lender rejeita o desembolso.

loanAccountId é um UUID que você fornece. O Lender não gera esse UUID. Ele identifica a conta de empréstimo sob a qual este contrato é gerido, e é imutável nas tranches posteriores da mesma proposta. O Lender também confere que:

netDeliveredAmount não excede grossRequestedAmount.
grossRequestedAmount, e o total corrente entre as tranches, não excede approvedAmount.
disbursedAt não é anterior à decisão de aprovação.
A jurisdição e a versão de perfil ainda batem com o par que o Lender resolveu no passo 4.

originationFeeAmount é opcional. Ele carrega metadados de custo que a apropriação lê. O Lender não trata esse campo como retenção, então ele não muda a relação entre líquido e bruto.

Confirme que o empréstimo existe

A resposta do desembolso carrega a proposta em disbursed com o evento de desembolso dela. Depois, leia a conta de empréstimo:

Chamada	O que ela retorna
`GET /api/v1/loan-accounts/{loanAccountId}`	A conta de empréstimo ativa: status, saldo de principal, saldo em aberto e data de desembolso.
`GET /api/v1/loan-accounts/{loanAccountId}/schedule`	O cronograma de originação: uma entrada por parcela, todas não pagas.

A resposta também carrega profileVersion, a versão do perfil de jurisdição, não uma versão de produto. Ela não carrega moeda. O empréstimo usa a currency que você definiu na versão do produto de empréstimo no passo 2. Guarde esse valor junto com o seu próprio registro de produto. Se você configurou o Midaz, o lançamento de desembolso chega ao ledger assim que o dispatcher do outbox repassa a intenção. Isso acontece logo depois da chamada, não dentro dela.

Próximos passos

Faça a gestão de um empréstimo

Registre pagamentos, antecipe, reprograme e corrija uma conta de empréstimo viva.

Como funciona a apropriação

O reconhecimento de juros roda no agendamento próprio. Comece uma rodada de apropriação, ou habilite o heartbeat.

Visão geral

Primeiros passos

Conceitos

Guias

Integração

Operações

Início rápido

As seis chamadas

1. Crie o produto

2. Crie uma versão

3. Prenda um perfil contábil

4. Crie a proposta

5. Aprove

6. Desembolse

Confirme que o empréstimo existe

Próximos passos

Faça a gestão de um empréstimo

Como funciona a apropriação

​As seis chamadas

​1. Crie o produto

​2. Crie uma versão

​3. Prenda um perfil contábil

​4. Crie a proposta

​5. Aprove

​6. Desembolse

​Confirme que o empréstimo existe

​Próximos passos

Faça a gestão de um empréstimo

Como funciona a apropriação

As seis chamadas

1. Crie o produto

2. Crie uma versão

3. Prenda um perfil contábil

4. Crie a proposta

5. Aprove

6. Desembolse

Confirme que o empréstimo existe

Próximos passos