Skip to main content
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, com os formatos completos de requisição e de resposta.
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:
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 e ler uma jurisdição. 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: 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 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. 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: 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. 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. Os middlewares de autorização e de idempotência podem usar formatos de resposta próprios. 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 e acrescentar uma versão montam os termos a que uma proposta se prende. A versão é imutável. Prender um perfil contábil mapeia cada evento contábil em contas contábeis, e a ativação exige esse perfil. Aplicar um encargo e ler taxas flutuantes completam a superfície, ao lado de listar, ler e ativar. Leia Defina um produto de empréstimo.

​
Origine

Seis operações levam uma proposta de enviada até desembolsada: criar, depois uma entre aprovar, rejeitar ou retirar, e então desembolsar. Ver a prévia de um cronograma calcula as parcelas de uma cotação e pode registrá-la como oferta. Listar e ler consultam propostas. Leia Como funciona a originação para a máquina de estados e Início rápido 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, o cronograma dela, as transações dela, os encargos dela e o histórico de auditoria dela. Cinco escritas movem dinheiro ou o cronograma: ver a prévia de um pagamento antes de registrá-lo, antecipar, reprogramar e estornar uma transação. 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.

​
Contabilize e lance

Começar uma rodada de apropriação reconhece juros de um período de competência. Listar referências de diário por id de correlação e ler uma para achar o registro contábil que uma rodada gravou. Leia Contabilidade e rodadas de apropriação.

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

​
Brasil

O pacote Brasil adiciona leituras e escritas reguladas sob /api/v1/br. Elas são divulgação do CET, o descritor da operação de crédito, estágio de PDD e as transições dele, uma cotação de pagamento antecipado com o demonstrativo de quitação dela, prévia de tributos e consentimento de capitalização. 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. 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.

​
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

Início rápido

Sete chamadas de um banco de dados vazio até um empréstimo desembolsado.

Eventos

Assine a jornada de crédito em vez de fazer polling.

Referência da API

Cada operação, com os formatos completos de requisição e de resposta.

Pré-requisitos

Os serviços, as migrations e a configuração de que uma primeira chamada precisa.