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 false como padrão. Quando habilitada, as rotas protegidas exigem um token bearer JWT:
O padrão serve apenas a deploys single-tenant: a inicialização rejeita MULTI_TENANT_ENABLED=true com PLUGIN_AUTH_ENABLED=false, porque 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. No modo single-tenant o Lender usa DEFAULT_TENANT_ID. No modo multi-tenant ele resolve o tenant a partir da identidade validada. Veja Multi-tenancy. 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

Cada operação que carrega um corpo envia e retorna application/json. 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

As escritas de dinheiro e de cronograma aceitam um header de requisição X-Idempotency. Envie a sua própria chave. Com um armazenamento de idempotência acessível, as cinco operações que exigem X-Idempotency compartilham um comportamento:
  • Uma nova tentativa de uma chamada concluída repete a primeira resposta e carimba X-Idempotency-Replayed: true nela. Nada é registrado uma segunda vez.
  • Uma nova tentativa enquanto a primeira chamada ainda está em andamento responde 409.
  • A chave é delimitada ao seu tenant e expira depois da janela que IDEMPOTENCY_RETRY_WINDOW_SEC define, cujo padrão é 300 segundos.
O middleware compartilhado falha aberto em erros transitórios do armazenamento de idempotência. Durante uma indisponibilidade, não conte com a repetição nem com a proteção de no máximo uma vez no nível do middleware. Pagamento e estorno funcionam de outro jeito. Os dois 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. Um valor fora do intervalo é rejeitado em vez de ajustado. 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 o Lender precisa desse perfil no desembolso. 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 não persiste nada. As respostas de criação e de decisão são as únicas leituras de uma proposta, então guarde o corpo que cada chamada retorna. Leia Como funciona a originação para a máquina de estados e Início rápido para as seis 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: 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.

​
Próximos passos

Início rápido

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