Início rápido

Esta página leva você de um banco de dados vazio a um empréstimo desembolsado em sete 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 sete chamadas. O Lender pega o analista do subject do token, e apenas esse analista pode aprovar e desembolsar a proposta.

Este passo a passo registra um empréstimo brasileiro com o regime tributário none, que não calcula IOF e mantém simples os valores do passo 7. Leia o Pacote regulatório Brasil para um produto que retém IOF. 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 sete 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-products/{productId}/activate     → active
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",
  "loanType": "personal",
  "jurisdictionCode": "BR"
}

loanType aceita personal, commercial ou card. jurisdictionCode é BR. Qualquer outro código retorna 422. A resposta carrega o novo id. O produto fica em draft.

2. Crie uma versão

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

{
  "jurisdictionCode": "BR",
  "changeReason": "initial version",
  "currency": "BRL",
  "rateMode": "fixed",
  "fixedAnnualRateBps": 1800,
  "rateBand": { "minAnnualRateBps": 1200, "maxAnnualRateBps": 4800 },
  "admittedBorrowerKinds": ["pessoaFisica"],
  "jurisdictionExtensions": {
    "taxRegime": "none",
    "normPortfolioClass": "C5"
  }
}

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.
rateBand é obrigatório. É a faixa de preço que a versão autoriza, em pontos-base anuais. Uma proposta cuja taxa fica fora dela é recusada.
admittedBorrowerKinds nomeia para quem a versão empresta. Uma lista vazia ou omitida não admite nenhum tomador.
normPortfolioClass é a carteira. Uma versão brasileira sem carteira não pode ser ativada no passo 4.
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. A ativação recusa um produto sem perfil, então vincule 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 uma regra por evento contábil. Sete eventos precisam de uma regra: disbursement, repayment, prepayment, accrual, collection_unapplied, collection_reapply e collection_refund. Os outros tipos de evento são opcionais. Menos de sete regras é rejeitado antes de o handler rodar. Um produto sob as regras brasileiras de perda de crédito também precisa de provision_constitution e provision_reversal, ou a provisão medida dele não é lançada no ledger. A ativação não verifica essas regras. 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 regime tributário none não calcula nenhuma, então a regra de duas pernas é a que balanceia neste passo a passo. Leia Defina um produto de empréstimo para a superfície mais ampla do produto.

4. Ative o produto

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

{ "versionId": "<versionId>" }

A ativação fixa a versão em que as novas propostas são originadas. Ela recusa um produto que não tem perfil contábil, e uma versão brasileira que não tem carteira. Uma proposta em um produto que não está ativo é recusada.

5. Crie a proposta

POST /api/v1/loan-applications Envie o header X-Idempotency. O Lender exige esse header nesta chamada e nos passos 6 e 7. Uma nova tentativa com o mesmo valor repete a primeira resposta e não grava nada novo.

{
  "loanProductVersionId": "<versionId>",
  "borrowerId": "3f2b8c1e-7a4d-4e9b-9c2a-5d6e7f8a9b0c",
  "borrowerKind": "pessoaFisica",
  "requestedPrincipalAmount": "50000.00",
  "requestedInterestRate": "0.01500000",
  "requestedInstallments": 24,
  "expectedDisbursementDate": "2026-08-01T12:00:00Z"
}

borrowerId é um UUID. borrowerKind aceita pessoaFisica ou pessoaJuridica, e a versão deve admitir esse tipo.
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 e a compara com a faixa de taxa da versão em pontos-base anuais: "0.01500000" ao mês são 1800 bps ao ano, dentro da faixa do passo 2.
requestedInstallments fica entre 1 e 600.
previewScheduleSnapshotId é opcional. Para citar a cotação que você mostrou ao tomador, envie o scheduleOfferSnapshotId que POST /api/v1/loan-applications/preview-schedule retornou.
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.

6. Aprove

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

{
  "approvedAmount": "48000.00",
  "decisionAt": "<current time, RFC3339>",
  "note": "within policy"
}

approvedAmount vira o teto de tudo o que você desembolsa. A proposta passa para approved e carrega o registro da decisão.

7. Desembolse

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

{
  "loanAccountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "grossRequestedAmount": "48000.00",
  "netDeliveredAmount": "48000.00",
  "disbursedAt": "<current time, RFC3339>",
  "jurisdictionExtensions": {
    "disbursedAt": "<the same instant>",
    "loanProductVersionId": "<versionId>",
    "requestId": "<the X-Idempotency value of this call>"
  }
}

Com o regime tributário none, netDeliveredAmount deve ser igual a grossRequestedAmount. O Lender aceita um desembolso apenas quando o líquido é igual ao bruto menos as retenções, menos a tarifa de originação retida. Esse regime não calcula retenções, e este passo a passo não retém tarifa.

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. jurisdictionExtensions leva o que o pipeline brasileiro lê: o instante do desembolso, a versão do passo 2 e o valor de X-Idempotency desta chamada como requestId. O desembolso falha quando falta um deles. O Lender também confere que:

netDeliveredAmount não excede grossRequestedAmount.
grossRequestedAmount é igual a approvedAmount, porque este é o único desembolso da proposta. Uma liberação em tranches declara trancheNumber, e o total corrente dela não excede approvedAmount.
decisionAt e disbursedAt não são anteriores à criação da proposta, e 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 5.

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. Se você configurou o relay do ledger Midaz, o lançamento de desembolso chega ao ledger quando o dispatcher do outbox repassa a intenção. Isso acontece logo depois da chamada, não dentro dela. Caso contrário, a intenção permanece no outbox.

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 sete chamadas

1. Crie o produto

2. Crie uma versão

3. Prenda um perfil contábil

4. Ative o produto

5. Crie a proposta

6. Aprove

7. 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 sete chamadas

​1. Crie o produto

​2. Crie uma versão

​3. Prenda um perfil contábil

​4. Ative o produto

​5. Crie a proposta

​6. Aprove

​7. 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 sete chamadas

1. Crie o produto

2. Crie uma versão

3. Prenda um perfil contábil

4. Ative o produto

5. Crie a proposta

6. Aprove

7. Desembolse

Confirme que o empréstimo existe

Próximos passos