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 cadeia decimal, nunca como número JSON. Complete primeiro os Pré-requisitos. Envie o mesmo token bearer nas seis chamadas. O Lender toma o oficial a partir do subject do token. Sob o perfil genérico, só esse oficial pode aprovar e desembolsar a proposta.

Use a jurisdição XX neste percurso. XX é o perfil genérico do Lender, e ele não calcula retenções — o que mantém simples os valores do passo 6. Um empréstimo regulado brasileiro carrega divulgação de CET e consentimento de capitalização. Leia o Pacote regulatório do Brasil para esse caminho. Um contrato com desconto em folha pertence ao contexto delimitado de 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": "Empréstimo pessoal — genérico",
  "loanType": "personal",
  "jurisdictionCode": "XX"
}

loanType aceita personal, commercial ou card. jurisdictionCode aceita um código que o registro carregue: XX ou BR. Qualquer outro código devolve 422. A resposta carrega o novo id. O produto fica em draft, que é tudo de que este percurso precisa: uma proposta se vincula 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": "versão inicial",
  "currency": "USD",
  "rateMode": "fixed",
  "fixedAnnualRateBps": 1800
}

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

currency não tem valor padrão. Envie um código ISO-4217 válido em maiúsculas. A versão é a fonte de 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 recusa uma versão fixa que carregue qualquer um deles.
jurisdictionCode é obrigatório, e precisa coincidir com o do produto. Uma versão não pode mover um produto para outra jurisdição.

A resposta carrega o versionId.

3. Vincule um perfil contábil

POST /api/v1/loan-products/{productId}/accounting-profiles O perfil mapeia cada evento contábil para contas do livro-razão. O Lender precisa dele no desembolso, então vincule-o 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 é recusado antes de o handler rodar. Cada perna declara exatamente um entre role e component, e nenhuma conta aparece nos dois lados de uma mesma regra. Quatro eventos também carregam um formato de pernas fixo:

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

collection_reapply toma unapplied_cash como seu único débito. Cada crédito que ela carrega também precisa aparecer como crédito em repayment ou prepayment, com a mesma conta e o mesmo role. disbursement e repayment precisam cada um de pelo menos um débito e um crédito. Mantenha a regra disbursement em 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 fecha sob XX. No modo multi-tenant o perfil também precisa de midazOrganizationId e midazLedgerId. Leia Definir um produto de empréstimo para a superfície de produto mais ampla.

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 cadeia decimal em escala 8. Precisa ser maior que 0 e não maior que 1. O Lender monta o cronograma com esta taxa: "0.01500000" ao mês são 1800 bps ao ano.
requestedInstallments vai de 1 a 600.
previewScheduleSnapshotId é um UUID que você gera para identificar a cotação que você mostrou ao tomador. O Lender o guarda na proposta. Calcule o cronograma que você mostra com POST /api/v1/loan-applications/preview-schedule. Essa chamada não persiste nada nem devolve um identificador. Gere o identificador do seu lado e guarde-o com o seu próprio registro de cotação.
Não existe campo assignedOfficerId. O Lender o define a partir do subject do token.

A proposta volta em pending_approval, e carrega 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": "dentro da política"
}

approvedAmount se torna o teto de tudo que você desembolsa. Sob XX, só o oficial que criou a proposta pode aprová-la. A proposta passa para approved e carrega o registro de decisão.

6. Desembolse

POST /api/v1/loan-applications/{id}/disburse Envie o header X-Idempotency. O Lender o exige. Uma retentativa 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 precisa ser igual a grossRequestedAmount. O posting do desembolso fecha como líquido igual a bruto menos retenções, e o perfil genérico não calcula retenções. Qualquer líquido menor deixa o posting sem fechar e o Lender recusa o desembolso.

loanAccountId é um UUID que você envia — o Lender não o gera. Ele identifica a conta de empréstimo sob a qual este contrato recebe servicing, e é imutável nas parcelas de liberação posteriores da mesma proposta. O Lender também verifica que:

netDeliveredAmount não excede grossRequestedAmount.
grossRequestedAmount, e o total acumulado entre liberações, não excede approvedAmount.
disbursedAt não é anterior à decisão de aprovação.
A jurisdição e a versão de perfil continuam coincidindo 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 o trata 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 seu evento de desembolso. Depois leia a conta de empréstimo:

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

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 1. Guarde esse valor com o seu próprio registro de produto. Se você configurou o Midaz, o posting do desembolso chega ao ledger quando o despachante do outbox repassa a intenção. Isso acontece pouco depois da chamada, não dentro dela.

Próximos passos

Fazer servicing 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 seu próprio calendário. Dispare uma rotina de apropriação, ou ative 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. Vincule um perfil contábil

4. Crie a proposta

5. Aprove

6. Desembolse

Confirme que o empréstimo existe

Próximos passos

Fazer servicing de um empréstimo

Como funciona a apropriação

​As seis chamadas

​1. Crie o produto

​2. Crie uma versão

​3. Vincule um perfil contábil

​4. Crie a proposta

​5. Aprove

​6. Desembolse

​Confirme que o empréstimo existe

​Próximos passos

Fazer servicing de um empréstimo

Como funciona a apropriação

As seis chamadas

1. Crie o produto

2. Crie uma versão

3. Vincule um perfil contábil

4. Crie a proposta

5. Aprove

6. Desembolse

Confirme que o empréstimo existe

Próximos passos