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 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.
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
1. Crie o produto
POST /api/v1/loan-products
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
currencynã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.admittedBorrowerKindsnomeia 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, omitafloatingRateTableId,floatingSpreadBpserequiresFloatingRate. 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.
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.
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:
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 para a superfície mais ampla do produto.
4. Ative o produto
POST /api/v1/loan-products/{productId}/activate
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.
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 tomadorpessoaFisica, um CNPJ o tornapessoaJuridica, 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. OborrowerIdda resposta é esse titular, e a proposta guarda apenas esse id.requestedInterestRateé a taxa mensal como string decimal na escala 8. Ela deve ser maior que0e não maior que1. 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ão1800bps ao ano, dentro da faixa do passo 2.requestedInstallmentsfica entre 1 e 600.previewScheduleSnapshotIdé opcional. Para citar a cotação que você mostrou ao tomador, envie oscheduleOfferSnapshotIdquePOST /api/v1/loan-applications/preview-scheduleretornou.- Uma proposta informa exatamente um entre
requestedPrincipalAmount,requestedNetAmounterequestedInstallmentAmount. Não existe campoassignedOfficerId: o Lender define o analista a partir do subject do token. firstDueDateegracePeriodDayssão opcionais. Omita os dois, e a proposta registra a primeira data de vencimento que o gerador de cronograma define paraexpectedDisbursementDate. Todo cronograma e a liberação dependem dessa data.
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 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 é 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:
netDeliveredAmountnão excedegrossRequestedAmount.grossRequestedAmounté igual aapprovedAmount, porque este é o único desembolso da proposta. Uma liberação em tranches declaratrancheNumber, e o total corrente dela não excedeapprovedAmount.decisionAtedisbursedAt, quando você os envia, não são anteriores à criação da proposta, edisbursedAtnã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:
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
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.