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

# SDK e incorporação do Lender

> Integre o Lender a partir do seu próprio software: a superfície REST que carrega cada operação, o que o seu cliente deve tratar em dinheiro, erros, novas tentativas e paginação, e o padrão para rodar o Lender atrás de um produto que os seus usuários já usam.

**A API REST do Lender é toda a superfície de cliente.** Produtos, propostas, contas de empréstimo, rodadas de apropriação e os registros regulatórios brasileiros são todos chamadas HTTP sob `/api/v1`. Nada existe apenas dentro de uma biblioteca de cliente.

Chame o Lender com o cliente HTTP que a sua stack já tem. Não existe biblioteca de cliente do Lender para instalar, então a API é o contrato contra o qual você escreve. Esta página cobre o que o seu cliente deve tratar e o que guardar do seu lado. Depois ela cobre como colocar o Lender atrás de um produto com que os seus usuários já falam. Leia [API REST do Lender](https://docs.lerian.studio/pt/products/lender/lender-rest-api.md) para as operações em si.

> [!NOTE]
>
> Os documentos OpenAPI neste portal são fontes de renderização das páginas de referência. Eles não são contratos de cliente, e não são base para geração de cliente ou de SDK.

## O que o seu cliente deve tratar

***

Quatro regras cobrem a maior parte do código que você escreve contra o Lender.

### O dinheiro viaja como string decimal

Os valores de dinheiro são strings decimais JSON, normalmente com duas casas decimais. As taxas decimais como `requestedInterestRate` são strings com oito casas decimais. Os campos `fixedAnnualRateBps`, `floatingSpreadBps` e `annualRateBps` são pontos-base inteiros:

```json theme={null}
{
  "requestedPrincipalAmount": "50000.00",
  "requestedInterestRate": "0.01500000"
}
```

Envie a string, e faça o parse da string com o tipo decimal da sua linguagem. Um float binário perde centavos, e um número JSON convida a isso. Os timestamps são RFC 3339 em UTC.

### Os erros respondem problem+json

A maioria dos erros de operação e de fallback responde `application/problem+json`. Não suponha isso para as respostas 401 e 403. Ramifique por `status` e por content type. Um `422` de validação de schema pode incluir um array `errors` com detalhes de campo, enquanto a validação de handler ou de domínio pode retornar apenas o `detail` de topo.

Trate `detail` como texto para uma pessoa, não como uma chave que o seu código casa. Uma falha do lado do servidor responde com um detail genérico de propósito, então nenhuma causa interna chega a um cliente. Registre o status e o seu próprio identificador de correlação, e deixe os traces do Lender carregarem o resto.

### Repita as suas escritas com a sua própria chave

As escritas de dinheiro e de ciclo de vida recebem uma chave de idempotência que você gera. Elas incluem as cinco escritas de proposta de empréstimo, os encargos do produto, o pagamento antecipado, a reprogramação, o pagamento, o estorno e as escritas de baixa e de reembolso. Derive a chave do seu próprio identificador de requisição, para que uma nova tentativa reproduza a primeira resposta em vez de gravar uma segunda vez.

As operações que impõem `X-Idempotency` na borda reproduzem uma chamada concluída com `X-Idempotency-Replayed: true` na resposta. Elas respondem `409` enquanto a primeira chamada ainda está em andamento. Pagamento, estorno, cobrança de pagamento devolvido e as escritas de baixa e de reembolso também usam `X-Idempotency` como chave, e nunca leem `X-Request-ID`. Uma chamada que envia apenas `X-Request-ID` é recusada. Uma nova tentativa com os mesmos fatos reproduz. A mesma chave com fatos diferentes responde `409`. Portanto, decida pelo corpo da resposta, nunca pela presença do cabeçalho de reprodução.

O middleware falha **fechado** durante uma indisponibilidade do armazenamento de idempotência: ele recusa com `503` em vez de deixar passar uma escrita desprotegida. Trate essa recusa como "não executou, tente de novo", e concilie antes de partir para uma chave nova.

[API REST do Lender](https://docs.lerian.studio/pt/products/lender/lender-rest-api.md#idempotency) lista qual header cada uma dessas operações aceita, e quanto tempo uma chave vive.

### Pagine com filtros, não com offsets profundos

A paginação é por operação. As leituras de lista de produtos aceitam `limit` e `offset`. O histórico de auditoria aceita apenas `limit`. Um valor fora do intervalo declarado responde `422` em vez de uma página reduzida em silêncio. Leia a página de referência da operação que você chama, e restrinja a consulta em vez de percorrer um offset longo.

## Guarde os identificadores que as suas escritas retornam

***

As operações de originação são comandos: criar, aprovar, rejeitar, retirar e desembolsar. Cada uma responde com o corpo completo da proposta. O `id` dela identifica a proposta de empréstimo. Depois do desembolso, `disbursementEvent.loanAccountId` identifica a conta de empréstimo.

Guarde os dois do seu lado conforme avança. O seu próprio registro então liga o seu tomador à conta de empréstimo. Cada leitura de gestão da carteira parte de um identificador que você já tem. O cronograma, as transações, os encargos e o histórico de auditoria se baseiam todos na conta de empréstimo.

## Incorporar o Lender atrás do seu próprio produto

***

O Lender é um serviço do qual você faz o deploy, não uma biblioteca que você vincula. Para colocá-lo atrás de uma aplicação que os seus clientes já usam, guarde as credenciais do seu lado e chame o Lender de servidor para servidor. Quatro regras mantêm essa fronteira limpa.

**Nunca entregue um token do Lender a um navegador ou a um aplicativo móvel**. O seu serviço autentica o seu usuário e decide se esse usuário pode agir. Depois ele chama o Lender com um token próprio.

**Emita o token para a pessoa que age**. O Lender deriva o ator HTTP do subject do token, nunca de um campo da requisição. O Lender registra quem criou como analista responsável, e nenhuma decisão o confere: qualquer operador ou admin que tenha a permissão da rota pode aprovar, rejeitar, retirar ou desembolsar uma proposta direta. Um contrato que a rail de folha CLT registrou é aprovado e liberado apenas por essa rail.

**Mantenha uma credencial por tenant**. Um Lender self-hosted usa `DEFAULT_TENANT_ID`. Na Lerian Cloud, o tenant vem da identidade validada, nunca de um header, de um parâmetro de query ou de um campo de corpo, então o seu serviço mantém uma credencial para cada tenant que atende.

**Saiba das mudanças de estado pelos eventos**. O Lender publica eventos de negócio pelo outbox dele e não inicia sem o backbone de eventos. Leia [Eventos do Lender](https://docs.lerian.studio/pt/products/lender/lender-events.md).

> [!NOTE]
>
> Um desembolso registra a intenção de lançamento dele na mesma transação de banco de dados que move a proposta para `disbursed`. O Lender repassa essa intenção ao Midaz logo depois. Não trate um `200` no desembolso como prova de que o ledger já carrega o lançamento. Leia [Contabilidade e rodadas de apropriação](https://docs.lerian.studio/pt/products/lender/accounting-and-accrual-runs.md).

## Próximos passos

***

> [card] [API REST do Lender](https://docs.lerian.studio/pt/products/lender/lender-rest-api.md)
>
> O caminho base, a autenticação, a idempotência e as operações por tarefa.

> [card] [Eventos do Lender](https://docs.lerian.studio/pt/products/lender/lender-events.md)
>
> O contrato de transmissão e os eventos em que você pode se inscrever.

> [card] [Início rápido](https://docs.lerian.studio/pt/products/lender/lender-quick-start.md)
>
> Sete chamadas de um banco de dados vazio até um empréstimo desembolsado.

> [card] [Pré-requisitos](https://docs.lerian.studio/pt/products/lender/lender-prerequisites.md)
>
> Os serviços, as migrations e a configuração de que uma primeira chamada precisa.


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