Skip to main content
O Lender serve uma única API HTTP. Cada operação fica sob o caminho base /api/v1, e nada é versionado no host. Uma listagem de produtos é GET /api/v1/loan-products. Esta página é o mapa, não o território. Ela cobre o que as operações compartilham e depois as agrupa pelo trabalho que fazem. Cada operação tem sua própria página sob o anchor Lender na Referência de API, com os formatos completos de request e response.
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 nem base para gerar um SDK.

​
Autenticação

O Lender aceita um token bearer JWT. Um único esquema de segurança se aplica a todo o documento:
Duas leituras são públicas e não pedem token: listar jurisdições e obter uma jurisdição. O registro é metadado da implantação, então um cliente pode lê-lo antes de ter identidade. As sondas ficam fora da autenticação para que um orquestrador as alcance sem token: /health, /readyz e /version.

​
Autorização

O Lender autoriza cada request 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 única escrita: Conceda ao papel do oficial apenas as ações de que o trabalho dele precisa. make generate-casdoor escreve os papéis e permissões do Lender num arquivo semente que você carrega no seu provedor de identidade — Pré-requisitos mostra o conjunto mínimo para originar.

​
Identidade de tenant e de oficial

O tenant nunca é um header, um parâmetro de query nem um campo do body. O Lender o resolve a partir da identidade validada do request. Veja Multi-tenancy. O oficial designado vem do subject do token da mesma forma. Nenhum body de solicitação de empréstimo carrega um campo de oficial, e nenhum valor enviado pelo cliente sobrescreve o subject.

​
Requests e responses

Toda operação que carrega body envia e devolve application/json. Envie todo campo de dinheiro e de taxa como string decimal, nunca como número JSON — "50000.00", "0.01500000". O Lender os devolve do mesmo jeito. Os timestamps são RFC 3339 em UTC.

​
Idempotência

As escritas de dinheiro e de cronograma aceitam o header de request X-Idempotency. Envie a sua própria chave. As cinco operações que exigem X-Idempotency compartilham um comportamento:
  • Uma retentativa de uma chamada concluída repete a primeira resposta e coloca nela X-Idempotency-Replayed: true. Nada é registrado uma segunda vez.
  • Uma retentativa enquanto a primeira chamada ainda está em voo responde 409.
  • A chave tem escopo de tenant e expira depois da janela que IDEMPOTENCY_RETRY_WINDOW_SEC define, com default de 300 segundos.
O pagamento e a reversão funcionam de outro jeito. Os dois leem X-Request-ID primeiro e recorrem a X-Idempotency quando ele falta. Envie um dos dois: uma chamada que não carrega nenhum responde 422. O Lender guarda o id do request no banco de dados junto com os dados da chamada. Uma retentativa que carrega o mesmo id e os mesmos dados repete a primeira resposta pela rota normal de resposta, sem header de repetição. O mesmo id de request com dados diferentes responde 409 em vez de repetir, então um id nunca consegue registrar dois valores diferentes. Esse registro não expira. Os dados 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 só os parâmetros que ela declara. Um valor fora da faixa é rejeitado em vez de ajustado ao limite. Cada outra leitura declara os próprios parâmetros, então restrinja-a com os identificadores e filtros da página de referência dela.

​
Erros

Todo erro responde application/problem+json e segue a RFC 9457. Ramifique pelo status e, num 422, pelos valores de location em errors. Um 422 nomeia cada campo que falhou. 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 trabalho

​
Catalogar um produto

Oito operações são donas do catálogo. Criar um produto e acrescentar uma versão constroem os termos aos quais uma solicitação se vincula. A versão é imutável. Vincular um perfil contábil mapeia cada evento contábil para contas do livro-razão, e o Lender precisa dele no desembolso. Aplicar um encargo e ler taxas flutuantes completam a superfície, junto com listar, obter e ativar. Leia Definir um produto de empréstimo.

​
Originar

Seis operações levam uma solicitação de enviada a desembolsada: criar, depois uma de aprovar, rejeitar ou retirar, e então desembolsar. Pré-visualizar um cronograma calcula as parcelas para uma cotação e não persiste nada. As respostas de criação e de decisão são as únicas leituras de uma solicitação, então guarde o body que cada chamada devolve. 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.

​
Fazer servicing de um empréstimo vivo

Cinco leituras descrevem a conta: a conta, o cronograma, as transações, os encargos e o histórico de auditoria. Cinco escritas movem dinheiro ou o cronograma: pré-visualizar um pagamento antes de registrá-lo, pré-pagar, repactuar e reverter uma transação. Nada reescreve o histórico. Uma reversão registra uma nova transação que compensa a original. Leia Fazer servicing de um empréstimo.

​
Contabilizar e lançar

Iniciar uma rotina de apropriação reconhece juros de um período de competência. Liste as referências de lançamento por id de correlação e leia uma para encontrar o registro contábil que uma rotina escreveu. Leia Contabilidade e rotinas de apropriação.

​
Descobrir jurisdições

As duas leituras públicas informam quais códigos de jurisdição esta implantação carrega e o que cada perfil decide. Leia Jurisdições.

​
Brasil

O pacote Brasil acrescenta 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 suas transições, uma cotação de pré-pagamento com o respectivo extrato de liquidação, pré-visualização de tributos e consentimento de capitalização. O pacote também carrega seus próprios caminhos de produto, que se comportam como os genéricos sob regras brasileiras. Leia Pacote regulatório do Brasil. A jornada com desconto em folha é uma conversa por eventos com o rail 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 vazio a um empréstimo desembolsado.

Eventos

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

Referência de API

Cada operação, com os formatos completos de request e response.

Pré-requisitos

Os serviços, as migrações e a configuração que uma primeira chamada precisa.