> ## 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.

# Como funciona a apropriação

> O que uma rodada de apropriação faz: o mês contábil que ela reconhece, o valor que ela calcula, o que a rodada produz e para onde vai o lançamento resultante.

O Lender não reconhece juros de forma contínua. Ele reconhece juros em uma **rodada de apropriação**. Uma rodada cobre uma data de referência e, para cada empréstimo que seleciona, reconhece exatamente um mês contábil.

## Um mês civil fechado, o mesmo para todos os empréstimos

***

O mês contábil de um empréstimo é a **competência** dele, e quem ancora a competência é o calendário, não a data de desembolso. Uma rodada reconhece o último mês civil que já tinha terminado por inteiro antes da **data de referência** dela. Ela reconhece esse mesmo mês para cada empréstimo que seleciona. Uma rodada em qualquer dia de abril fecha março.

O mapeamento é total. Toda data de referência nomeia exatamente uma competência, e essa competência é sempre um mês que acabou. Nenhuma rodada consegue reconhecer um mês ainda em curso. O serviço define o mês que uma rodada fecha, seja qual for o dia em que você começa a rodada.

Um empréstimo desembolsado no meio do mês não fica de fora do primeiro mês dele. Os juros se espalham pelos dias de cada intervalo do cronograma, e a competência recolhe o que cai dentro dela. Um empréstimo desembolsado no dia 12, portanto, reconhece esse primeiro pedaço de mês dentro do mês em que foi contratado.

## O que uma rodada faz

***

`POST /api/v1/accrual-runs` recebe a data de referência e o **modo** da rodada e, opcionalmente, até 100 ids de produto de empréstimo que delimitam a rodada. Tanto `businessDate` quanto `mode` são obrigatórios. O `mode` rotula a rodada para os seus próprios relatórios, com uma reserva. O modo `heartbeat` pertence ao driver agendado, e o Lender recusa uma chamada que o envia.

**1. O Lender seleciona os empréstimos**

Você não envia uma lista. O Lender lê a própria carteira e pega cada conta de empréstimo em uma proposta desembolsada ou ativa, dentro dos produtos que você delimitou. Uma rodada cobre a carteira inteira. Ela percorre os candidatos página a página até acabarem, então nenhum contrato perde uma competência porque a carteira cresceu.

**2. O Lender reconhece os juros**

Para cada empréstimo, o Lender resolve a taxa efetiva de juros do cronograma contratual e pega a linha daquela competência. O reconhecimento trabalha sobre os fluxos de caixa contratuais.

**3. O Lender grava o reconhecimento e a intenção de lançamento**

Uma transação de banco de dados guarda a rodada, um item por reconhecimento e a intenção de lançamento balanceada por trás de cada item. Ou tudo fica durável, ou nada fica.

**4. O relay entrega o lançamento**

Depois que a rodada faz commit, o relay do outbox lança a transação balanceada no Midaz, e o Midaz a contabiliza.

## O valor que o Lender reconhece

***

O reconhecimento segue o método da taxa efetiva de juros. O custo amortizado começa no principal que o cronograma amortiza, menos a tarifa de originação. Os tributos retidos ficam fora dele: no Brasil, o IOF é um repasse e nunca entra no custo amortizado.

O Lender resolve a taxa a partir do próprio cronograma, então os juros reconhecidos reproduzem o contrato em vez de uma taxa separada que você mantém.

Quando a jurisdição tributa a receita de juros, a rodada reconhece esse tributo também. O tributo é um segundo valor no mesmo empréstimo e na mesma competência, com lançamento balanceado próprio. Juros e tributo nunca dividem uma transação.

## Uma vez por empréstimo, por mês, por valor

***

Um reconhecimento é único em três coisas: a conta de empréstimo, a competência e o tipo de valor. Uma segunda rodada para a mesma data de referência não reconhece nada novo para um empréstimo já reconhecido. Ela não dobra os juros e não enfileira um segundo lançamento.

Essa unicidade é a garantia do caminho do dinheiro. Ela também torna uma rodada segura para repetir depois de uma interrupção.

## O que uma rodada produz

***

Uma rodada responde com:

* O identificador da rodada e o status da rodada.
* Uma **referência de diário**: o identificador contábil da rodada.
* O **id de correlação** que o Lender deriva do modo, da data de referência e dos produtos no escopo.

Por trás dessa resposta, a rodada guarda um item para cada reconhecimento: a conta de empréstimo, a competência, o tipo de valor e o valor. Esses itens são a base a partir da qual o Lender monta os lançamentos.

Use o id da referência de diário para amarrar a rodada aos seus próprios registros contábeis: ele identifica exatamente uma rodada. O registro da referência também guarda o id de correlação. O Lender deriva esse id do modo, da data de referência e dos produtos no escopo. Uma leitura por id de correlação, portanto, retorna a rodada mais recente que compartilha esse id. [Contabilidade e rodadas de apropriação](https://docs.lerian.studio/pt/products/lender/accounting-and-accrual-runs.md) cobre as duas operações que fazem essa leitura.

## A rodada não grava o lançamento no ledger

***

Uma rodada reconhece juros e enfileira uma intenção de lançamento. Ela não chama o Midaz e não espera uma contabilização. O relay lança depois, e o ledger contabiliza a transação. Uma rodada bem-sucedida significa que o reconhecimento e a intenção dele estão duráveis, não que o ledger já mostra o lançamento.

Um lançamento que nunca chegou ao ledger não é trabalho perdido. Repita a rodada. [Contabilidade e rodadas de apropriação](https://docs.lerian.studio/pt/products/lender/accounting-and-accrual-runs.md) cobre o que uma repetição responde de volta.

Configure duas coisas antes que um lançamento possa ser contabilizado:

* Dê ao perfil contábil da versão do produto uma regra para o evento `accrual`, com pernas balanceadas. Quando a jurisdição tributa a receita de juros, adicione também a regra opcional `accrual_tax`, para que o tributo tenha pernas próprias.
* O Lender sempre inicializa o outbox. Configure a conexão com o ledger para que o relay consiga entregar a intenção durável. Veja [Configuração e deploy](https://docs.lerian.studio/pt/products/lender/configuration-and-deploy.md).

Configure o perfil antes da primeira rodada. Sem uma regra de apropriação, o Lender não tem pernas para montar um lançamento, e a rodada deixa esse empréstimo de fora.

## Empréstimos que uma rodada deixa de fora

***

Um empréstimo selecionado ainda pode não reconhecer nada como receita:

* A apropriação está suspensa. No Brasil, os dois estágios mais profundos da escala de provisionamento suspendem a apropriação (veja o [Pacote regulatório Brasil](https://docs.lerian.studio/pt/products/lender/brazil-regulatory-pack.md)). Um contrato suspenso ainda lança a tarifa de originação retida. O mês dele é lançado como `accrual_withholding`, que debita os juros a receber e credita rendas a apropriar, e o valor passa para receita no recebimento.
* Uma rodada anterior já decidiu aquela competência para ele.
* Os juros dele para aquela competência são zero.

Nenhum desses casos faz a rodada falhar. Uma rodada reconhece o que consegue e informa o que reconheceu.

## Rodar a apropriação de forma agendada

***

A rodada também tem um driver agendado dentro do serviço, e ele vem ligado. Ele dispara todo dia às 06:00 UTC até você dar outra expressão cron a ele.

Diário não quer dizer uma competência por dia. Todo disparo fecha o mesmo mês, o primeiro que dá certo decide o mês, e todo disparo posterior naquele mês encontra o trabalho já feito. A cadência diária é uma repetição. Um serviço fora do ar no dia 1 fecha o mês no dia 2. Uma expressão mensal teria perdido aquela competência de vez.

## Próximos passos

***

> [card] [Contabilidade e rodadas de apropriação](https://docs.lerian.studio/pt/products/lender/accounting-and-accrual-runs.md)
>
> Perfis contábeis, regras de lançamento e as operações de referência de diário.

> [card] [Arquitetura do Lender](https://docs.lerian.studio/pt/products/lender/lender-architecture.md)
>
> Os domínios, o encaixe da jurisdição e o outbox que leva o dinheiro para fora.

> [card] [Defina um produto de empréstimo](https://docs.lerian.studio/pt/products/lender/define-a-loan-product.md)
>
> Produtos, versões e o perfil contábil de que uma rodada depende.

> [card] [Pacote regulatório Brasil](https://docs.lerian.studio/pt/products/lender/brazil-regulatory-pack.md)
>
> Estágios de provisionamento, tributos e as divulgações que o perfil brasileiro adiciona.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.