> ## 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. # API REST do Lender > Oriente-se na API do Lender: o caminho base /api/v1, autenticação bearer, autorização por recurso e ação, dinheiro em string decimal, idempotência delimitada, paginação, o formato de erro problem+json e as operações agrupadas por tarefa. O Lender serve uma API HTTP. Cada operação fica sob o caminho base `/api/v1`, e nada é versionado no host. Uma lista de produtos é `GET /api/v1/loan-products`. Esta página cobre o que as operações compartilham e depois as agrupa pela tarefa que fazem. Cada operação tem uma página própria sob a âncora **Lender** na [Referência da API](https://docs.lerian.studio/pt/reference/introduction.md), com os formatos completos de requisição e de resposta. > [!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 SDK. ## Autenticação *** A autenticação é configurada por deploy. `PLUGIN_AUTH_ENABLED` tem `true` como padrão. Quando habilitada, as rotas protegidas exigem um token bearer JWT: ```http theme={null} Authorization: Bearer ``` Na Lerian Cloud, o Lender resolve o tenant a partir da claim `tenantId` da identidade validada. Duas leituras são públicas e não pedem token: [listar jurisdições](https://docs.lerian.studio/pt/reference/products/lender/list-jurisdictions.md) e [ler uma jurisdição](https://docs.lerian.studio/pt/reference/products/lender/get-jurisdiction.md). O registro é metadado de deploy, então um cliente consegue lê-lo antes de ter uma identidade. As probes ficam fora da autenticação para que um orquestrador as alcance sem token: `/health`, `/readyz` e `/version`. ### Autorização *** O Lender autoriza cada requisição contra a aplicação `lender`, um recurso e uma ação. O recurso acompanha a superfície, e as ações são granulares em vez de uma escrita única: | Recurso | Ações | | - | - | | `loan_product` | `read`, `write` | | `loan_applications` | `read`, `preview:schedule`, `create`, `approve`, `reject`, `withdraw`, `disburse`, `capitalization-consent:ingest`, `preview:tax`, `b3-registration:record` | | `loan_accounts` | `read`, `write`, `audit:read`, `book:read`, `charge:apply`, `repayment:preview`, `repayment:record`, `repayment:reverse`, `returned_payment:collect`, `prepayment:record`, `reschedule`, `cet:read`, `pdd:transition`, `payoff-refund:record`, `write-off:record`, `credit-loss-recovery:record`, `credit-loss-recovery:reverse`, `write-off-collection:end` | | `accounting` | `read`, `write`, `retry`, `supersede` | | `streaming_manifest` | `read` | Conceda ao papel de analista apenas as ações que o trabalho dele exige. O Lender define seus papéis e permissões em um arquivo seed que você carrega no seu provedor de identidade. Os papéis do cliente são `viewer`, `operator`, `editor`, `admin` e `collection-agent`, e `editor` tem exatamente o que `operator` tem. Os [Pré-requisitos](https://docs.lerian.studio/pt/products/lender/lender-prerequisites.md) mostram o conjunto mínimo para originar. ### Identidade do tenant e do analista *** **O tenant nunca é um header, um parâmetro de query nem um campo de corpo.** Um Lender self-hosted usa `DEFAULT_TENANT_ID`. Na Lerian Cloud, o Lender resolve o tenant a partir da identidade validada. O analista responsável vem do subject do token da mesma forma. Nenhum corpo de proposta de empréstimo carrega um campo de analista, e nenhum valor fornecido pelo cliente substitui o subject. O Lender registra o analista, e nenhuma decisão o confere. ## Requisições e respostas *** Envie valores de dinheiro e taxas decimais como `requestedInterestRate` na forma de strings decimais: `"50000.00"`, `"0.01500000"`. Os valores de versão de produto e de taxa flutuante `fixedAnnualRateBps`, `floatingSpreadBps` e `annualRateBps` são pontos-base inteiros. Os timestamps são RFC 3339 em UTC. ## Idempotência *** O Lender submete 35 operações a um contrato de no máximo uma vez, em duas classes. A classe decide onde a garantia vive. As duas classes leem a chave apenas de `X-Idempotency`, nunca de `X-Request-ID`. | Classe | Cabeçalho | Onde a garantia vive | Operações | | - | - | - | - | | Imposta na borda | `X-Idempotency`, exigido pelo schema | Um middleware na frente do handler, apoiado pelo armazenamento de idempotência | 27 escritas: as cinco escritas de proposta de empréstimo (criar, aprovar, rejeitar, retirar, desembolsar), o pagamento antecipado e seu alias do Brasil, a cotação de pagamento antecipado do Brasil, a avaliação de ativo problemático do Brasil, a reprogramação, os encargos do produto, as execuções de apropriação e sua nova tentativa, a varredura de substituição de plano de contas, os fatos do lote de cessão, a quitação de funding da cessão, a liquidação de cobrança do consignado e as dez ações de operador do consignado | | Gravada com o dinheiro | `X-Idempotency`, exigido pelo handler | Um marcador gravado na mesma transação de banco de dados que o dinheiro | 8 escritas: registrar um pagamento, estornar uma transação, cobrar um recebível de pagamento devolvido, registrar um reembolso de quitação, dar baixa em um contrato, registrar uma recuperação de crédito e o estorno dela, e declarar o fim da cobrança de uma baixa | As quatro escritas de produto (criar um produto e acrescentar uma versão, cada uma na forma genérica e na do Brasil) aceitam `X-Idempotency` como cabeçalho opcional. Com ele, um reenvio com a mesma chave e o mesmo corpo reproduz a primeira resposta em vez de criar um segundo produto. Sem ele, nada é deduplicado. Envie a sua própria chave. Nas 27 operações impostas na borda: * Uma nova tentativa de uma chamada **concluída** repete a primeira resposta e carimba `X-Idempotency-Replayed: true` nela. O Lender não registra nada uma segunda vez. * Uma nova tentativa enquanto a primeira chamada ainda está **em andamento** responde `409`. Aguarde e leia o recurso. Não envie o comando de novo. * Uma requisição que **não carrega chave** responde `400` com o código `IDEMPOTENCY_KEY_REQUIRED`. A chave é um header obrigatório no schema da operação, então a recusa acontece antes de qualquer lógica de handler rodar. * Uma chave enviada com uma grafia que o Lender não lê (`Idempotency-Key` ou `X-Idempotency-Key`) responde `400` com o código `IDEMPOTENCY_KEY_HEADER_UNKNOWN`, em vez de executar o comando desprotegido. Enviar uma dessas junto com o header do contrato não é problema. A recusa só dispara quando `X-Idempotency` está ausente. * O Lender delimita a chave ao seu tenant, e a chave expira depois da janela que `IDEMPOTENCY_RETRY_WINDOW_SEC` define, cujo padrão é 86400 segundos (24 horas). **O contrato falha fechado, nas duas direções.** Um deploy sem armazenamento de idempotência acessível não inicia. Se o armazenamento ficar inacessível enquanto ele roda, uma operação protegida responde `503` com o código `IDEMPOTENCY_UNAVAILABLE` em vez de executar desprotegida. Toda recusa carrega um código legível por máquina, e o cliente decide com base nele entre reenviar e conciliar. Os códigos `IDEMPOTENCY_OUTCOME_UNKNOWN` e `IDEMPOTENCY_OUTCOME_UNKNOWN_UNFENCED` dizem que a requisição alcançou o handler e que o resultado não pode ser estabelecido. Leia o recurso antes de decidir. Os códigos de recusa formam um contrato publicado. Renomear um código quebra esse contrato. As oito operações transacionais funcionam de outro modo. Todas leem `X-Idempotency` e nada mais: uma chamada sem chave utilizável é recusada (LENDER-0301 para um pagamento, LENDER-0317 para um estorno, LENDER-0326 para uma cobrança, LENDER-0965 para uma baixa ou o fim de uma cobrança, LENDER-0917 para um reembolso de quitação, LENDER-0976 para uma recuperação e seu estorno). Cada recusa responde `422`. Elas não usam middleware e não têm expiração de 24 horas. Uma repetição de um pagamento, um estorno, uma baixa, uma recuperação ou um reembolso traz `X-Idempotency-Replayed: true`. Uma cobrança repetida não traz. O Lender guarda o id da requisição no banco de dados junto com os fatos da chamada. Uma nova tentativa que carrega o mesmo id e os mesmos fatos repete a primeira resposta pelo caminho normal de resposta. O mesmo id de requisição com fatos **diferentes** responde `409` em vez de repetir, então um id nunca pode registrar dois valores diferentes. Esse registro não expira. Os fatos que o Lender compara mudam conforme a operação: | Operação | Fatos comparados com o id de requisição guardado | | - | - | | Registrar um pagamento | A conta de empréstimo, o valor e a data efetiva (`transactionDate` quando `effectiveDate` está ausente). | | Estornar uma transação | A transação que está sendo estornada, a conta de empréstimo, a data efetiva do estorno, o motivo, a versão do perfil e o código de jurisdição. O valor vem da transação original, então não é comparado. | | Cobrar um recebível de pagamento devolvido | O recebível e a própria cobrança. Reentregar a mesma cobrança sob a mesma identidade de requisição responde `200` com o recebível que já vale; uma segunda cobrança, diferente, contra um recebível já cobrado responde `409`. | As cinco escritas de dinheiro da família de perda de crédito e reembolso comparam a chave com o que registraram primeiro. A mesma chave com outro valor, motivo ou corpo responde `409`, e o fim da cobrança de uma baixa é declarado uma vez: outra chave é recusada. ## Paginação *** A paginação é por operação, não global. Leia a página de referência da operação que você chama, e envie apenas os parâmetros que ela declara. | Leitura | Parâmetros | | - | - | | [Listar produtos de empréstimo](https://docs.lerian.studio/pt/reference/products/lender/list-loan-products.md) e [listar produtos de empréstimo brasileiros](https://docs.lerian.studio/pt/reference/products/lender/list-loan-products-br.md) | `limit` (padrão 25, teto 100) e `offset` (padrão 0, teto 10.000) | | [Eventos de auditoria](https://docs.lerian.studio/pt/reference/products/lender/list-loan-account-audit-events-huma.md) | apenas `limit` (padrão 50, teto 100) | O Lender rejeita um valor fora do intervalo em vez de ajustá-lo. Cada outra leitura declara os parâmetros próprios, então restrinja a leitura com os identificadores e filtros da página de referência dela. ## Erros *** Erros do Huma e do handler global respondem `application/problem+json` e seguem a [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457). Os middlewares de autorização e de idempotência podem usar formatos de resposta próprios. | Campo | O que ele carrega | | - | - | | `status` | O código de status HTTP. | | `title` | O nome do status. | | `detail` | O que deu errado nesta ocorrência. | | `errors` | Detalhes opcionais de validação de schema. Cada entrada carrega um `location`, uma `message` e o `value` que o Lender recebeu. | Ramifique por status e por content type. Para um `422`, use `errors` quando presente. A validação de handler ou de domínio pode retornar apenas o `detail` de topo. Uma falha do lado do servidor responde com um detail genérico, então uma causa crua nunca chega a um cliente. ## As operações por tarefa *** ### Catalogue um produto Oito operações cuidam do catálogo. [Criar um produto](https://docs.lerian.studio/pt/reference/products/lender/create-loan-product.md) e [acrescentar uma versão](https://docs.lerian.studio/pt/reference/products/lender/create-loan-product-version.md) montam os termos a que uma proposta se prende. A versão é imutável. [Prender um perfil contábil](https://docs.lerian.studio/pt/reference/products/lender/create-loan-product-accounting-profile.md) mapeia cada evento contábil em contas contábeis, e a ativação exige esse perfil. [Aplicar um encargo](https://docs.lerian.studio/pt/reference/products/lender/create-loan-product-charges.md) e [ler taxas flutuantes](https://docs.lerian.studio/pt/reference/products/lender/list-loan-product-floating-rates.md) completam a superfície, ao lado de [listar](https://docs.lerian.studio/pt/reference/products/lender/list-loan-products.md), [ler](https://docs.lerian.studio/pt/reference/products/lender/get-loan-product.md) e [ativar](https://docs.lerian.studio/pt/reference/products/lender/activate-loan-product.md). Leia [Defina um produto de empréstimo](https://docs.lerian.studio/pt/products/lender/define-a-loan-product.md). ### Origine Seis operações levam uma proposta de enviada até desembolsada: [criar](https://docs.lerian.studio/pt/reference/products/lender/create-loan-application.md), depois uma entre [aprovar](https://docs.lerian.studio/pt/reference/products/lender/approve-loan-application.md), [rejeitar](https://docs.lerian.studio/pt/reference/products/lender/reject-loan-application.md) ou [retirar](https://docs.lerian.studio/pt/reference/products/lender/withdraw-loan-application.md), e então [desembolsar](https://docs.lerian.studio/pt/reference/products/lender/disburse-loan-application.md). [Ver a prévia de um cronograma](https://docs.lerian.studio/pt/reference/products/lender/preview-loan-schedule.md) calcula as parcelas de uma cotação e pode registrá-la como oferta. [Listar](https://docs.lerian.studio/pt/reference/products/lender/list-loan-applications.md) e [ler](https://docs.lerian.studio/pt/reference/products/lender/get-loan-application.md) consultam propostas. Leia [Como funciona a originação](https://docs.lerian.studio/pt/products/lender/how-origination-works.md) para a máquina de estados e [Início rápido](https://docs.lerian.studio/pt/products/lender/lender-quick-start.md) para as sete chamadas de ponta a ponta. ### Faça a gestão de um empréstimo vivo Cinco leituras descrevem a conta: [a conta](https://docs.lerian.studio/pt/reference/products/lender/get-active-loan-account.md), [o cronograma dela](https://docs.lerian.studio/pt/reference/products/lender/get-active-loan-schedule.md), [as transações dela](https://docs.lerian.studio/pt/reference/products/lender/list-active-loan-transactions.md), [os encargos dela](https://docs.lerian.studio/pt/reference/products/lender/list-active-loan-charges.md) e [o histórico de auditoria dela](https://docs.lerian.studio/pt/reference/products/lender/list-loan-account-audit-events-huma.md). Cinco escritas movem dinheiro ou o cronograma: [ver a prévia de um pagamento](https://docs.lerian.studio/pt/reference/products/lender/preview-repayment.md) antes de [registrá-lo](https://docs.lerian.studio/pt/reference/products/lender/record-repayment.md), [antecipar](https://docs.lerian.studio/pt/reference/products/lender/prepay-loan-account.md), [reprogramar](https://docs.lerian.studio/pt/reference/products/lender/reschedule-loan-account.md) e [estornar uma transação](https://docs.lerian.studio/pt/reference/products/lender/reverse-loan-account-transaction.md). Nada reescreve o histórico. Um estorno lança uma transação nova que compensa a original. Leia [Faça a gestão de um empréstimo](https://docs.lerian.studio/pt/products/lender/service-a-loan.md). ### Contabilize e lance [Começar uma rodada de apropriação](https://docs.lerian.studio/pt/reference/products/lender/create-accrual-run.md) reconhece juros de um período de competência. [Listar referências de diário](https://docs.lerian.studio/pt/reference/products/lender/get-journal-reference.md) por id de correlação e [ler uma](https://docs.lerian.studio/pt/reference/products/lender/get-journal-reference-by-id.md) para achar o registro contábil que uma rodada gravou. Leia [Contabilidade e rodadas de apropriação](https://docs.lerian.studio/pt/products/lender/accounting-and-accrual-runs.md). ### Descubra jurisdições As duas leituras públicas informam quais códigos de jurisdição este deploy carrega e o que cada perfil decide. Leia [Jurisdições](https://docs.lerian.studio/pt/products/lender/jurisdictions.md). ### Brasil O pacote Brasil adiciona leituras e escritas reguladas sob `/api/v1/br`. Elas são [divulgação do CET](https://docs.lerian.studio/pt/reference/products/lender/get-loan-account-cet-disclosure.md), [o descritor da operação de crédito](https://docs.lerian.studio/pt/reference/products/lender/get-loan-account-credit-operation-descriptor.md), [estágio de PDD](https://docs.lerian.studio/pt/reference/products/lender/get-loan-account-pdd-stage.md) e [as transições dele](https://docs.lerian.studio/pt/reference/products/lender/apply-loan-account-pdd-stage-transition.md), [uma cotação de pagamento antecipado](https://docs.lerian.studio/pt/reference/products/lender/create-prepayment-quote.md) com [o demonstrativo de quitação dela](https://docs.lerian.studio/pt/reference/products/lender/get-payoff-statement.md), [prévia de tributos](https://docs.lerian.studio/pt/reference/products/lender/preview-tax.md) e [consentimento de capitalização](https://docs.lerian.studio/pt/reference/products/lender/ingest-capitalization-clause-consent.md). O pacote também carrega caminhos de produto próprios, que se comportam como os genéricos sob as regras brasileiras. Leia [Pacote regulatório Brasil](https://docs.lerian.studio/pt/products/lender/brazil-regulatory-pack.md). A jornada com desconto em folha é uma conversa por eventos com o trilho de folha de pagamento, não um conjunto de chamadas REST. Leia [Consignado privado](https://docs.lerian.studio/pt/products/lender/consignado-privado.md). ### Mais superfícies Cada uma destas famílias tem suas próprias operações na referência. * **Ceder recebíveis a um fundo.** `/api/v1/assignment/...` registra fundos, monta e pontua lotes de recebíveis contra a regra de elegibilidade de um fundo, e os aprova ou descarta. Também gera o arquivo de oferta e o termo de endosso, e ingere o arquivo de retorno do administrador. Registra fatos observados externamente e trabalha a fila de exceções. * **Cobre um pagamento devolvido.** `/api/v1/returned-payment-receivables` lista e lê as dívidas separadas do tomador que um pagamento final estornado abre quando o contrato que ele encerrou já não pode receber o dinheiro de volta. Ele também registra uma cobrança contra uma delas. * **Promova uma versão de produto.** `POST /api/v1/loan-products/{id}/promote` reaponta um produto ativo para outra de suas versões. Como resultado, novas propostas passam a originar nela, enquanto contratos já escritos ficam na versão em que nasceram. O apelido Brasil da operação é `/api/v1/br/loan-products/{id}/promote`. * **Leia e revise versões de produto.** `/api/v1/loan-product-versions` lista e lê os retratos de versão, e declara uma revisão do modelo de encargos em um deles. Pelo pacote Brasil, ele também declara a classificação normativa de uma versão. * **Modele os documentos.** `/api/v1/loan-products/{productId}/document-templates` e a superfície equivalente sob um fundo de cessão rascunham, leem e publicam as versões de modelo a partir das quais o Lender renderiza um documento gerado. * **Tabelar as taxas flutuantes.** `/api/v1/rate-tables` cria tabelas de taxas flutuantes, adiciona períodos e lista e corrige taxas diárias de índice. * **Emitir um instrumento de crédito.** `/api/v1/loan-applications/{applicationId}/credit-instruments` emite o instrumento que evidencia uma proposta, lista os instrumentos emitidos e baixa um. Em uma versão cujo instrumento é emitido pelo cliente, `/api/v1/loan-applications/{applicationId}/signed-credit-instrument` registra o instrumento assinado e o baixa. * **Dar baixa em uma perda de crédito.** `/api/v1/br/loan-accounts/{id}/write-offs` dá baixa em um contrato de crédito direto conforme a Res. CMN 4.966 art. 49. A mesma família registra e estorna as recuperações de crédito que um tomador baixado paga depois, e declara o fim da cobrança da baixa. * **Reembolsar um contrato liquidado.** `/api/v1/br/loan-accounts/{id}/payoff-refunds` registra o dinheiro que o cliente devolveu a um tomador, e `GET /api/v1/br/payoff-refunds-due` lista os contratos liquidados que ainda devem dinheiro ao tomador. * **Registrar na B3.** `/api/v1/br/loan-applications/{id}/b3-registration` registra o código do instrumento que a B3 atribuiu a um contrato de crédito direto. O Lender o guarda e não comanda nada na B3. * **Precificar o IOF por tenant.** `/api/v1/br/tax/iof-rates` lê as alíquotas do tenant, e `PUT` precifica um tipo de tomador. * **Abrir as portas de parceiros.** `GET /api/v1/partner/loan-products/{loanProductId}` e `POST /api/v1/br/partner/loan-products/{loanProductId}/tax/preview` atendem uma credencial de parceiro vinculada a esse produto de empréstimo. * **Avançar uma data de negócio.** `GET /api/v1/business-date` lê a data de negócio do tenant. `POST /api/v1/business-date/advance` funciona apenas onde `BUSINESS_DATE_ENABLED` está ligada, o que o Lender permite apenas em sandbox ou em homologação. * **Acompanhe uma execução de accrual.** `/api/v1/accrual-runs` lista execuções, lê uma delas e suas decisões item a item, e reenvia ao razão os reconhecimentos que ele não confirmou, por `POST /api/v1/accrual-runs/{id}/retry`. A superfície `/api/v1/accounting-profiles` lista os perfis configurados. O par de sucessão substitui o plano de contas de um produto e liquida a mudança nos saldos de cada contrato vivo. * **Observe a carteira.** `/api/v1/dashboard/portfolio` e as duas leituras de inadimplência respondem a partir do retrato diário da carteira. A varredura diária de promoção de PDD constrói esse retrato para a data-base dela antes de varrer, e vem habilitada, então um deploy padrão tem um. O job separado `core-daily-portfolio-snapshot` aciona o mesmo produtor no próprio agendamento para deploys que queiram construí-lo independentemente da varredura. * **Escalone os estágios de provisão.** `/api/v1/br/pdd-stage-ladders` publica uma versão de escada de estágios de PDD e lê a que está em vigor. * **Trabalhe a cobrança extraordinária.** `/api/v1/br/consignado/collection-instructions` e o par de liquidação listam as instruções abertas e ingerem o Arquivo de Baixa Extraordinária do agente de cobrança. Eles também listam as linhas que ele recusou. A superfície de operação sob `/api/v1/internal/br/consignado/...` nomeia o canal do agente, trabalha linhas e itens de inbox em quarentena e dá destino a restituições de desconto a maior devidas aos trabalhadores. * **Inspecione a identidade e o fluxo.** `GET /api/v1/me` informa a sessão para a qual o token resolve, e `GET /api/v1/internal/streaming/discards` lista os registros de entrada colocados em quarentena pelos consumidores. ## Próximos passos *** > [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] [Eventos](https://docs.lerian.studio/pt/products/lender/lender-events.md) > > Assine a jornada de crédito em vez de fazer polling. > [card] [Referência da API](https://docs.lerian.studio/pt/reference/introduction.md) > > Cada operação, com os formatos completos de requisição e de resposta. > [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.