> ## 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 do Lender e integração embarcada
> Integre o Lender a partir do seu próprio software: a superfície REST que carrega toda operação, o que o seu cliente precisa tratar em dinheiro, erros, retentativas e paginação, e o padrão para rodar o Lender atrás de um produto que seus usuários já usam.
**A API REST do Lender é toda a superfície de cliente.** Produtos, propostas, contas de empréstimo, rotinas de apropriação e os registros regulatórios brasileiros são todos chamadas HTTP sob `/api/v1`. Nada existe apenas dentro de uma biblioteca cliente.
Chame o Lender com o cliente HTTP que sua stack já tem. Não há uma biblioteca 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 precisa tratar e o que vale guardar do seu lado. Depois cobre como colocar o Lender atrás de um produto com o qual seus usuários já falam. Leia [API REST do Lender](/pt/lender/lender-rest-api) para as operações em si.
Os documentos OpenAPI deste portal são fontes de renderização para as páginas de referência. Eles não são contratos de cliente, e não são base para gerar um cliente nem um SDK.
## O que o seu cliente precisa tratar
***
Quatro regras cobrem a maior parte do código que você escreve contra o Lender.
### Dinheiro viaja como string decimal
Todo campo de dinheiro e de taxa viaja como string JSON, nunca como número JSON. Dinheiro carrega duas casas decimais, e uma taxa carrega oito:
```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.
### Erros respondem problem+json
Toda falha responde `application/problem+json`. Ramifique pelo `status`. Para um `422`, leia o array `errors`: cada entrada nomeia o campo que falhou em `location`, com uma `message` e o `value` que o Lender recebeu. Mapeie esses locais nos seus próprios campos de formulário e o usuário vê qual dado corrigir.
Trate `detail` como texto para uma pessoa, não como uma chave contra a qual seu código compara. Uma falha do lado do servidor responde com um detalhe 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.
### Reenvie as escritas de dinheiro com a sua própria chave
Desembolso, encargos de produto, pré-pagamento, reprogramação, pagamento e reversão aceitam cada um uma chave de idempotência que você gera. Derive-a do seu próprio identificador de request, e uma retentativa não custa nada.
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 voo. O pagamento e a reversão se apoiam em `X-Request-ID`, e recorrem a `X-Idempotency` quando ele falta: uma retentativa com os mesmos dados repete, e o mesmo id com dados diferentes responde `409`. Então ramifique sobre o corpo da resposta, nunca sobre a presença do header de repetição.
[API REST do Lender](/pt/lender/lender-rest-api#idempotência) 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 só `limit`. Um valor fora da faixa declarada 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 suas escritas devolvem
***
As operações de originação são comandos: criar, aprovar, rejeitar, retirar e desembolsar. Cada uma responde com o corpo completo da proposta, e esse corpo carrega o `loanApplicationId` e, uma vez desembolsada a proposta, o `loanAccountId`.
Guarde os dois do seu lado conforme avança. Seu próprio registro então liga o seu tomador à conta de empréstimo. Toda leitura de servicing parte de um identificador que você já tem, porque o cronograma, as transações, os encargos e o histórico de auditoria são indexados pela conta de empréstimo.
## Integrar o Lender atrás do seu próprio produto
***
O Lender é um serviço que você implanta, não uma biblioteca que você linka. Para colocá-lo atrás de uma aplicação que 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 app móvel**. Seu serviço autentica o seu usuário e decide se aquele usuário pode agir. Depois ele chama o Lender com um token próprio.
**Emita o token para a pessoa que age**. O Lender lê o oficial designado a partir do subject do token, não de algum campo do request. Esse subject é o que a trilha de auditoria registra, então um único token de serviço compartilhado faz todo empréstimo parecer do mesmo oficial. O Lender também autoriza cada transição contra o oficial a quem a proposta está designada. O mesmo subject portanto carrega uma proposta da criação até o desembolso.
**Mantenha uma credencial por tenant**. O tenant vem da identidade validada, nunca de um header, um parâmetro de query ou um campo do corpo. Em modo multi-tenant cada token carrega uma claim `tenantId`, então seu serviço guarda uma credencial para cada tenant que atende. Leia [Multi-tenancy](/pt/multi-tenancy).
**Saiba das mudanças de estado pelos eventos**. O Lender publica um evento de negócio sempre que um produto, uma proposta ou uma conta de empréstimo muda de estado. Assine e seu serviço reage conforme cada mudança acontece, sem um laço de polling contra as leituras de servicing. Leia [Eventos do Lender](/pt/lender/lender-events).
Um desembolso registra sua intenção de lançamento na mesma transação de banco de dados que move a proposta para `disbursed`, e o lançamento no ledger chega depois. Não trate um `200` no desembolso como prova de que o ledger já carrega o lançamento. Leia [Contabilidade e rotinas de apropriação](/pt/lender/accounting-and-accrual-runs).
## Próximos passos
***
O caminho base, a autenticação, a idempotência e as operações por trabalho.
O contrato do wire e os eventos que você pode assinar.
Seis chamadas de um banco de dados vazio até um empréstimo desembolsado.
Os serviços, as migrações e a configuração que uma primeira chamada precisa.