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

# Faça a gestão de um empréstimo

> Opere uma conta de empréstimo ativa: leia o cronograma e as transações dela, registre e veja a prévia de pagamentos, antecipe, reprograme e corrija com estornos.

Depois do desembolso, um empréstimo vira uma **conta de empréstimo**, a visão de gestão do contrato vivo. A gestão da carteira cobre toda a vida da conta. O dinheiro entra, o cronograma muda, e você corrige erros sem reescrever o histórico.

## Leia a conta

***

| Operação | Objetivo |
| - | - |
| `GET /api/v1/loan-accounts/{id}` | Lê a conta de empréstimo ativa. |
| `GET /api/v1/loan-accounts/{id}/schedule` | Lê o cronograma de parcelas atual. |
| `GET /api/v1/loan-accounts/{id}/transactions` | Lista as transações lançadas contra a conta. |
| `GET /api/v1/loan-accounts/{id}/charges` | Lista os encargos ativos na conta. |
| `GET /api/v1/loan-accounts/{id}/audit-events` | Lê a trilha de auditoria (Um registro cronológico e imutável de cada ação e transação no sistema, essencial para conformidade regulatória e resolução de disputas.) imutável dos eventos de ciclo de vida. |

## Registre dinheiro

***

**1. Veja a prévia da alocação**

`POST /api/v1/loan-accounts/{id}/preview-repayment` mostra como o Lender alocaria um pagamento entre as parcelas em aberto **sem registrar o pagamento**. O Lender paga primeiro a parcela vencida mais antiga. Dentro de cada parcela, ele paga multas, depois tarifas, depois juros, depois principal.

**2. Registre o pagamento**

`POST /api/v1/loan-accounts/{id}/repayments` registra o dinheiro recebido e o aloca no cronograma. Envie a sua chave em `X-Idempotency`. O Lender nunca lê `X-Request-ID`, e uma chamada sem chave utilizável responde `422` (LENDER-0301). A mesma chave com a mesma conta de empréstimo, o mesmo valor e a mesma data efetiva devolve o pagamento já registrado. A mesma chave com fatos diferentes responde `409`. Um pagamento datado em um dia civil de São Paulo posterior a hoje responde `422` (LENDER-0395), e um datado antes do primeiro desembolso do contrato responde `422` (LENDER-0985). Veja [Idempotência](https://docs.lerian.studio/pt/products/lender/lender-rest-api.md#idempotency).

**3. Antecipe**

`POST /api/v1/loan-accounts/{id}/prepayments` liquida o empréstimo antes do prazo, no todo ou em parte. Uma conta de empréstimo brasileira precisa antes de uma [cotação de pagamento antecipado](https://docs.lerian.studio/pt/products/lender/brazil-regulatory-pack.md). Um pagamento antecipado parcial pode ser estornado uma vez pela rota de estorno.

Um job diário, ligado por padrão, quita as parcelas vencidas com o dinheiro que um contrato mantém não aplicado. Com o job desligado (`JOBS_UNAPPLIED_CASH_SETTLEMENT_ENABLED`), uma parcela que o dinheiro retido cobre entra em atraso. A lista de transações aceita o filtro `requestId`, que a restringe às linhas registradas sob uma chave.

Quando sobra dinheiro retido depois que um contrato é liquidado, `POST /api/v1/br/loan-accounts/{id}/payoff-refunds` registra o reembolso que o cliente devolveu ao tomador, e `GET /api/v1/br/payoff-refunds-due` lista os contratos liquidados que ainda devem dinheiro. Um contrato de crédito direto que não pode ser recuperado recebe baixa com `POST /api/v1/br/loan-accounts/{id}/write-offs` (Res. CMN 4.966 art. 49). A baixa é irreversível. O dinheiro que o tomador paga depois é lançado como recuperação de crédito.

## Mude o cronograma

***

`POST /api/v1/loan-accounts/{id}/reschedules` reescreve o cronograma restante, por exemplo para uma renegociação. A mudança é um novo estado do cronograma, não uma edição do antigo. Uma reprogramação pode se classificar como reestruturação, com justificativa, e pode dispensar encargos de atraso. Uma renegociação substancial substitui o contrato por uma nova conta de empréstimo.

## Corrija sem destruir

***

As correções preservam uma linha do tempo consistente e auditável. Para desfazer uma transação registrada, estorne essa transação:

`POST /api/v1/loan-accounts/{id}/transactions/{transactionId}/reverse`

Um estorno acrescenta uma transação compensatória em vez de apagar qualquer coisa, então a conta mantém uma trilha de auditoria completa.

Um estorno recebe a chave em `X-Idempotency`, como um pagamento. A mesma chave reproduz o estorno já registrado apenas quando todos os fatos do estorno também coincidem. Os fatos do estorno são a transação que você estorna, a conta de empréstimo, a data efetiva do estorno, o motivo, a versão do perfil e o código da jurisdição. Qualquer diferença nesses fatos responde `409`.

> [!WARNING]
>
> A gestão da carteira nunca edita o passado. Pagamentos, reprogramações e estornos acrescentam fatos novos. O Lender rederiva o estado atual desse histórico, então a conta continua explicável a partir do registro próprio.

## Um pagamento final devolvido vira um recebível

***

Estornar o pagamento que quitou um empréstimo **consignado** nem sempre devolve a dívida ao contrato. A ordem de exclusão manda a entidade pagadora parar de descontar da folha. Depois que a ordem foi emitida ao trilho e o trilho não a rejeitou, o mandato de folha acabou. Nada no Lender o averba de novo. Um contrato revivido ali seria dívida sem instrumento por trás. Essa dívida seria cobrada por atraso, provisionada e oferecida de volta ao oficial como algo cujo desconto ele poderia cancelar uma segunda vez.

O Lender ainda aceita o estorno, porque o banco devolveu o dinheiro e o ledger tem de concordar com o banco. O destino muda. O Lender abre um **recebível de pagamento devolvido** contra o tomador, fora da operação de crédito, sem mandato de folha e cobrado por outros meios. O estorno responde qual dos dois aconteceu, e com o id do recebível quando um foi aberto.

O contrato mantém o estado de quitado. Nada reabre. O Lender não reprocessa nenhum cronograma e não desfaz nenhuma alocação.

> [!NOTE]
>
> Uma exclusão ainda em voo conta como emitida. Um estorno não pode esperar a resposta do trilho. Se uma revivência acontece antes de o trilho responder, nada a desfaz quando a resposta volta confirmada. Onde o trilho **rejeitou** a exclusão, o mandato nunca morreu, e o estorno revive o contrato exatamente como sempre reviveu.

### Trabalhar o recebível

| Operação | Finalidade |
| - | - |
| `GET /api/v1/returned-payment-receivables` | Listar recebíveis, delimitados por conta de empréstimo, tomador ou status. |
| `GET /api/v1/returned-payment-receivables/{id}` | Ler um recebível. |
| `POST /api/v1/returned-payment-receivables/{id}/collections` | Registrar que o tomador o pagou. |

Uma cobrança quita a dívida inteira, então ela não carrega valor: o Lender lê o número do recebível. Ela recebe a chave em `X-Idempotency`, como um pagamento. Reenviar a mesma cobrança sob essa mesma chave responde `200` com a cobrança que já está de pé. Uma segunda cobrança, diferente, contra uma dívida já cobrada responde `409` com `LENDER-0325`. O Lender recusa uma cobrança com `422` e `LENDER-0326` quando o instante de cobrança dela não é RFC 3339, ou quando ela não tem chave utilizável. A mesma recusa cobre um nome de cobrador mais longo do que o campo comporta, ou uma chave já gasta cobrando outra dívida.

O recebível nomeia o contrato de onde veio, então você encontra os recebíveis de um contrato delimitando a lista àquela conta de empréstimo. Ele não faz parte da visão de servicing do próprio contrato, porque já não é dívida do contrato.

> [!WARNING]
>
> O Lender recusa um pagamento devolvido que carregava dinheiro que a instituição segurava sem alocar, com `422` e `LENDER-0323`. Essa recusa é terminal por desenho. O Lender não registra o estorno e deixa o contrato exatamente como estava.

O Lender carrega o recebível a **valor de face**. A varredura diária de PDD o envelhece pela escala do produto de origem e provisiona a perda esperada para a idade dele. No estágio final, a varredura o baixa a prejuízo. Um produto cujo plano de contas pode desviar um pagamento devolvido deve carregar as três regras dessa provisão e dessa baixa. Caso contrário, o Lender recusa o plano com `422` e `LENDER-0406`.

## O que acontece downstream

***

A gestão da carteira emite `repayment.recorded`, `repayment_reversal.recorded`, `loan_schedule.prepayment_applied`, `loan_schedule.rescheduled`, `returned_payment_receivable.opened`, `returned_payment_receivable.collected` e `returned_payment_receivable.written_off`. Um pagamento, um estorno e um pagamento antecipado registram intenções de lançamento duráveis. Quando o relay do ledger está configurado, o Lender as repassa ao ledger. Caso contrário, as intenções permanecem no outbox aguardando entrega. Leia [o caminho de lançamento](https://docs.lerian.studio/pt/products/lender/lender-in-the-platform.md).

## Próximos passos

***

> [card] [Contabilidade e rodadas de apropriação](https://docs.lerian.studio/pt/products/lender/accounting-and-accrual-runs.md)
>
> Reconheça juros ao longo do tempo e leia a referência de diário que cada rodada registra.

> [card] [Pacote regulatório Brasil](https://docs.lerian.studio/pt/products/lender/brazil-regulatory-pack.md)
>
> Leia o estágio de PDD de um empréstimo em atraso e aplique uma transição de estágio.


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