Pular para o conteúdo principal
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 do analista apenas as ações de que a função dele precisa. O Lender define os papéis e as permissões dele em um arquivo de seed que você carrega no seu provedor de identidade. Pré-requisitos mostra o conjunto mínimo para a originação.

​
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 sobrepõe o subject.

​
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 29 operações a um contrato de no máximo uma vez, em duas classes. A classe decide qual header você envia e onde mora a garantia. Envie a sua própria chave. Nas 26 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 três operações transacionais funcionam de outro jeito. Todas leem X-Request-ID primeiro e recorrem a X-Idempotency quando ele está ausente. Envie um dos dois: uma chamada que não carrega nenhum responde 422. 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, sem header de repetição. 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:

​
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.
  • Ceda 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 aprova ou descarta os lotes. Ele também produz o arquivo de oferta e o termo de endosso, e ingere o arquivo de retorno do administrador. Ele registra fatos observados externamente, registra o instrumento de crédito de um recebível na registradora 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.
  • Tabele as taxas flutuantes. /api/v1/rate-tables cria uma tabela de taxa flutuante e acrescenta os períodos de onde o Lender lê a taxa de um produto flutuante.
  • Emita 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 deles.
  • 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.