> ## 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](/pt/products/lender/lender-rest-api) para as operações em si.
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/403 da lib-auth. 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 escritas de dinheiro com a sua própria chave
Desembolso, encargos de produto, pagamento antecipado, pagamento antecipado do pacote Brasil, reprogramação, pagamento e estorno aceitam, cada um, uma chave de idempotência que você gera. Derive essa chave do seu próprio identificador de requisição, e uma nova tentativa não custa nada enquanto o armazenamento de idempotência estiver disponível.
As cinco operações que exigem `X-Idempotency` repetem uma chamada concluída com `X-Idempotency-Replayed: true` na resposta. Elas respondem `409` enquanto a primeira chamada ainda está em andamento. Pagamento e estorno se baseiam em `X-Request-ID`, e recorrem a `X-Idempotency` quando ele está ausente. Uma nova tentativa com os mesmos fatos repete. O mesmo id com fatos diferentes responde `409`. Então ramifique pelo corpo da resposta, nunca pela presença do header de repetição.
O middleware falha aberto durante uma indisponibilidade do armazenamento de idempotência. Uma falha ambígua pode já ter executado a operação. Confirme o resultado antes de repetir uma escrita de dinheiro nessa janela.
[API REST do Lender](/pt/products/lender/lender-rest-api#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.
**Gere o token para a pessoa que age**. O Lender deriva o ator HTTP do subject do token, nunca de um campo da requisição. No fluxo humano genérico, o analista responsável aprova e rejeita. Tanto o tomador quanto o analista responsável podem retirar. A política de ator da jurisdição fixada governa a aprovação e o desembolso, então não suponha que um único subject humano faz cada transição.
**Mantenha uma credencial por tenant**. No modo single-tenant o Lender usa `DEFAULT_TENANT_ID`. No modo multi-tenant o tenant vem da identidade validada, nunca de um header, de um parâmetro de query ou de um campo de corpo. Cada token carrega uma claim `tenantId`, então o seu serviço mantém uma credencial para cada tenant que atende. Leia [Multi-tenancy](/pt/platform/multi-tenancy).
**Saiba das mudanças de estado pelos eventos**. Quando o streaming está habilitado e um broker está configurado, o Lender publica eventos de negócio pelo outbox dele. Quando o streaming está desabilitado, ele usa um emissor no-op. Quando o streaming está habilitado sem broker configurado, o Lender recusa subir em vez de recorrer ao emissor no-op. Habilite e configure o streaming antes de tratar a entrega de eventos como contrato de integração. Leia [Eventos do Lender](/pt/products/lender/lender-events).
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 apenas quando o relay do ledger está configurado. Caso contrário, a intenção fica no outbox. 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](/pt/products/lender/accounting-and-accrual-runs).
## Próximos passos
***
O caminho base, a autenticação, a idempotência e as operações por tarefa.
O contrato de transmissão e os eventos que você pode assinar.
Seis chamadas de um banco de dados vazio até um empréstimo desembolsado.
Os serviços, as migrations e a configuração de que uma primeira chamada precisa.