> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Início rápido > Sete chamadas de um banco de dados vazio até um empréstimo desembolsado: um produto, uma versão, um perfil contábil, uma ativação, uma proposta, uma aprovação e um desembolso. 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](https://docs.lerian.studio/pt/products/lender/lender-prerequisites.md). Envie o mesmo token bearer nas sete chamadas. O Lender registra o subject do token como o analista responsável da proposta. Nenhuma decisão confere esse dado: qualquer operador ou admin que tenha a permissão da rota pode aprovar, rejeitar, retirar ou desembolsar uma proposta direta. > [!NOTE] > > 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](https://docs.lerian.studio/pt/products/lender/brazil-regulatory-pack.md) para um produto que retém IOF. Um contrato com desconto em folha pertence ao contexto delimitado do consignado privado. Leia [Consignado privado](https://docs.lerian.studio/pt/products/lender/consignado-privado.md) para o vocabulário e os tópicos de ciclo de vida dele. ## As sete chamadas *** ``` 1. POST /api/v1/loan-products → productId 2. POST /api/v1/loan-products/{productId}/versions → versionId 3. POST /api/v1/loan-products/{productId}/accounting-profiles 4. POST /api/v1/loan-products/{productId}/activate → active 5. POST /api/v1/loan-applications → pending_approval 6. POST /api/v1/loan-applications/{id}/approve → approved 7. POST /api/v1/loan-applications/{id}/disburse → disbursed ``` ## 1. Crie o produto *** `POST /api/v1/loan-products` ```json theme={null} { "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` ```json theme={null} { "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 para contas do ledger. A ativação recusa um produto sem perfil, então vincule-o agora. ```json theme={null} { "loanProductVersionId": "", "accountingMode": "accrual", "postingRules": [ { "eventType": "disbursement", "legs": [ { "account": "principal", "role": "principal", "side": "debit", "nature": "debit", "perOperation": true }, { "account": "1000-10-001", "role": "cash", "side": "credit", "nature": "debit" } ] }, { "eventType": "repayment", "legs": [ { "account": "1000-10-001", "role": "cash", "side": "debit", "nature": "debit" }, { "account": "principal", "role": "principal", "side": "credit", "nature": "debit", "perOperation": true }, { "account": "interest", "role": "interest", "side": "credit", "nature": "debit", "perOperation": true } ] }, { "eventType": "prepayment", "legs": [ { "account": "1000-10-001", "role": "cash", "side": "debit", "nature": "debit" }, { "account": "4200-10-001", "component": "charge_rebate", "side": "debit", "nature": "debit", "optional": true }, { "account": "4300-10-001", "component": "iof_refund", "side": "debit", "nature": "debit", "optional": true }, { "account": "principal", "role": "principal", "side": "credit", "nature": "debit", "perOperation": true }, { "account": "2400-10-001", "component": "iof_due", "side": "credit", "nature": "credit", "optional": true } ] }, { "eventType": "accrual", "legs": [ { "account": "interest", "role": "interest", "side": "debit", "nature": "debit", "perOperation": true }, { "account": "4100-10-001", "role": "interest", "side": "credit", "nature": "credit" } ] }, { "eventType": "accrual_withholding", "legs": [ { "account": "interest", "role": "interest", "side": "debit", "nature": "debit", "perOperation": true }, { "account": "2900-10-001", "role": "interest", "side": "credit", "nature": "credit" } ] }, { "eventType": "renegotiation_gain", "legs": [ { "account": "reneg_adj", "component": "renegotiation_adjustment", "side": "debit", "nature": "credit", "perOperation": true }, { "account": "4400-10-001", "component": "renegotiation_gain", "side": "credit", "nature": "credit" } ] }, { "eventType": "renegotiation_loss", "legs": [ { "account": "5100-10-001", "component": "renegotiation_loss", "side": "debit", "nature": "debit" }, { "account": "reneg_adj", "component": "renegotiation_adjustment", "side": "credit", "nature": "credit", "perOperation": true } ] }, { "eventType": "collection_unapplied", "legs": [ { "account": "1000-10-001", "role": "cash", "side": "debit", "nature": "debit" }, { "account": "unapplied", "role": "unapplied_cash", "side": "credit", "nature": "credit", "perOperation": true } ] }, { "eventType": "collection_reapply", "legs": [ { "account": "unapplied", "role": "unapplied_cash", "side": "debit", "nature": "credit", "perOperation": true }, { "account": "principal", "role": "principal", "side": "credit", "nature": "debit", "perOperation": true } ] }, { "eventType": "collection_refund", "legs": [ { "account": "unapplied", "role": "unapplied_cash", "side": "debit", "nature": "credit", "perOperation": true }, { "account": "1000-10-001", "role": "cash", "side": "credit", "nature": "debit" } ] } ] } ``` Envie uma regra por evento contábil. Dez eventos exigem regra: `disbursement`, `repayment`, `prepayment`, `accrual`, `accrual_withholding`, `renegotiation_gain`, `renegotiation_loss`, `collection_unapplied`, `collection_reapply` e `collection_refund`. O array aceita de 10 a 33 regras, e o Lender rejeita menos de dez antes de o handler rodar. Os demais tipos de evento são opcionais. 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 não é lançada no ledger. A ativação não confere essas regras. Cada perna declara exatamente um entre `role` e `component`, um `side` e uma `nature`. `nature` é a natureza própria da conta, não o lado da perna: `debit` para um ativo ou uma despesa, `credit` para um passivo, um patrimônio ou uma receita. O Midaz define a direção do saldo da conta a partir dela. Uma perna que lança uma posição do tomador (`principal`, `interest`, `unapplied_cash` e semelhantes) define `perOperation: true`. O `account` dela vira então um prefixo de até 17 letras, dígitos, `_` ou `-`, e o Lender abre uma conta por conta de empréstimo sob esse prefixo. Qualquer outro `account` é um alias de até 50 letras, dígitos, `:`, `_` ou `-`, então um ponto é recusado (LENDER-0429). Uma posição do tomador lançada em conta compartilhada é recusada (LENDER-0408). As pernas de receita e o crédito de `accrual_withholding` continuam compartilhados. Nenhuma conta aparece nos dois lados da mesma regra. Os eventos a seguir também têm um formato fixo de pernas: | Evento | Pernas | | - | - | | `accrual` | Exatamente um débito e um crédito. | | `accrual_withholding` | Exatamente duas pernas `interest`: um débito na conta que `accrual` debita e um crédito em uma conta compartilhada que não é a receita de `accrual`. | | `renegotiation_gain` | Exatamente duas: um débito do componente `renegotiation_adjustment`, por operação, e um crédito do componente `renegotiation_gain`. | | `renegotiation_loss` | Exatamente duas: um débito do componente `renegotiation_loss` e um crédito do componente `renegotiation_adjustment`, por operação. | | `prepayment` | Exatamente cinco, nesta ordem: débito `cash`, débito opcional `charge_rebate`, débito opcional `iof_refund`, crédito `principal`, crédito opcional `iof_due`. | | `collection_unapplied` | Exatamente duas: débito `cash`, crédito `unapplied_cash`. | | `collection_refund` | Exatamente duas: débito `unapplied_cash`, crédito `cash`. | `collection_reapply` aceita `unapplied_cash` como único débito. Cada crédito que ela traz também deve aparecer como crédito em `repayment` ou `prepayment`, com a mesma conta e o mesmo papel. `disbursement` e `repayment` precisam de pelo menos um débito e um crédito cada, e `repayment` deve creditar uma perna `interest` na conta que `accrual` debita (LENDER-0440). Leia [Defina um produto de empréstimo](https://docs.lerian.studio/pt/products/lender/define-a-loan-product.md) para a superfície mais ampla do produto. ## 4. Ative o produto *** `POST /api/v1/loan-products/{productId}/activate` ```json theme={null} { "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. ```json theme={null} { "loanProductVersionId": "", "borrowerDocument": "111.444.777-35", "borrowerName": "Maria Souza", "requestedPrincipalAmount": "50000.00", "requestedInterestRate": "0.01500000", "requestedInstallments": 24, "expectedDisbursementDate": "" } ``` * `borrowerDocument` é o CPF ou o CNPJ do tomador, com ou sem máscara. Os dígitos verificadores devem ser válidos. Um CPF torna o tomador `pessoaFisica`, um CNPJ o torna `pessoaJuridica`, e a versão deve admitir esse tipo. `borrowerName` é obrigatório. O Lender busca o tomador como titular no CRM do Midaz da instituição do produto e registra um quando não existe. O `borrowerId` da resposta é esse titular, e a proposta guarda apenas esse id. * `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. * Uma proposta informa exatamente um entre `requestedPrincipalAmount`, `requestedNetAmount` e `requestedInstallmentAmount`. Não existe campo `assignedOfficerId`: o Lender define o analista a partir do subject do token. * `firstDueDate` e `gracePeriodDays` são opcionais. Omita os dois, e a proposta registra a primeira data de vencimento que o gerador de cronograma define para `expectedDisbursementDate`. Todo cronograma e a liberação dependem dessa data. 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` ```json theme={null} { "approvedAmount": "48000.00", "decisionAt": "", "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` ```json theme={null} { "loanAccountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "grossRequestedAmount": "48000.00", "netDeliveredAmount": "48000.00" } ``` > [!WARNING] > > **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. Omita `disbursedAt` e o Lender usa o agora de negócio do tenant. A primeira liberação mantém a primeira data de vencimento que a proposta registrou, então envie `expectedDisbursementDate` no passo 5 como o dia em que você desembolsa. Uma versão sem janela de primeiro vencimento recusa uma liberação em qualquer outro dia (LENDER-0951) e um `firstDueDate` diferente do registrado (LENDER-0950). O Lender calcula o IOF e congela o CET de todo desembolso em dinheiro a partir do regime tributário da versão. `jurisdictionExtensions` é opcional, e o Lender lê dele apenas o consentimento da cláusula de capitalização. 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`, quando você os envia, 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. O lançamento do desembolso chega ao ledger do Midaz quando o despachante do outbox repassa a intenção. Isso acontece logo após a chamada, não dentro dela. ## Próximos passos *** > [card] [Faça a gestão de um empréstimo](https://docs.lerian.studio/pt/products/lender/service-a-loan.md) > > Registre pagamentos, antecipe, reprograme e corrija uma conta de empréstimo viva. > [card] [Como funciona a apropriação](https://docs.lerian.studio/pt/products/lender/how-accrual-works.md) > > O reconhecimento de juros roda no agendamento próprio. Comece uma rodada de apropriação, ou habilite o heartbeat. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.