/api/v1. Nada existe apenas dentro de uma biblioteca de cliente.
Chame o Lender com o cliente HTTP que a sua stack já tem. Não existe biblioteca de cliente do Lender para instalar, então a API é o contrato contra o qual você escreve. Esta página cobre o que o seu cliente deve tratar e o que guardar do seu lado. Depois ela cobre como colocar o Lender atrás de um produto com que os seus usuários já falam. Leia API REST do Lender para as operações em si.
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 cliente ou de SDK.
O que o seu cliente deve tratar
Quatro regras cobrem a maior parte do código que você escreve contra o Lender.
O dinheiro viaja como string decimal
Os valores de dinheiro são strings decimais JSON, normalmente com duas casas decimais. As taxas decimais comorequestedInterestRate são strings com oito casas decimais. Os campos fixedAnnualRateBps, floatingSpreadBps e annualRateBps são pontos-base inteiros:
Os erros respondem problem+json
A maioria dos erros de operação e de fallback respondeapplication/problem+json. Não suponha isso para as respostas 401 e 403. Ramifique por status e por content type. Um 422 de validação de schema pode incluir um array errors com detalhes de campo, enquanto a validação de handler ou de domínio pode retornar apenas o detail de topo.
Trate detail como texto para uma pessoa, não como uma chave que o seu código casa. Uma falha do lado do servidor responde com um detail genérico de propósito, então nenhuma causa interna chega a um cliente. Registre o status e o seu próprio identificador de correlação, e deixe os traces do Lender carregarem o resto.
Repita as suas escritas com a sua própria chave
As escritas de dinheiro e de ciclo de vida recebem uma chave de idempotência que você gera. Elas incluem as cinco escritas de proposta de empréstimo, encargos de produto, pagamento antecipado, reprogramação, pagamento e estorno. Derive a chave do seu próprio identificador de requisição, para que uma nova tentativa repita a primeira resposta em vez de escrever uma segunda vez. As operações que exigemX-Idempotency repetem uma chamada concluída com X-Idempotency-Replayed: true na resposta. Elas respondem 409 enquanto a primeira chamada ainda está em andamento. Pagamento, estorno e cobrança de pagamento devolvido se baseiam em X-Request-ID, e recorrem a X-Idempotency quando ele está ausente. Uma nova tentativa com os mesmos fatos repete. O mesmo id com fatos diferentes responde 409. Então ramifique pelo corpo da resposta, nunca pela presença do header de repetição.
O middleware falha fechado durante uma indisponibilidade do armazenamento de idempotência: ele recusa com 503 em vez de deixar passar uma escrita desprotegida. Trate essa recusa como “não executou, tente de novo”, e concilie antes de partir para uma chave nova.
API REST do Lender lista qual header cada uma dessas operações aceita, e quanto tempo uma chave vive.
Pagine com filtros, não com offsets profundos
A paginação é por operação. As leituras de lista de produtos aceitamlimit e offset. O histórico de auditoria aceita apenas limit. Um valor fora do intervalo declarado responde 422 em vez de uma página reduzida em silêncio. Leia a página de referência da operação que você chama, e restrinja a consulta em vez de percorrer um offset longo.
Guarde os identificadores que as suas escritas retornam
As operações de originação são comandos: criar, aprovar, rejeitar, retirar e desembolsar. Cada uma responde com o corpo completo da proposta. O
id dela identifica a proposta de empréstimo. Depois do desembolso, disbursementEvent.loanAccountId identifica a conta de empréstimo.
Guarde os dois do seu lado conforme avança. O seu próprio registro então liga o seu tomador à conta de empréstimo. Cada leitura de gestão da carteira parte de um identificador que você já tem. O cronograma, as transações, os encargos e o histórico de auditoria se baseiam todos na conta de empréstimo.
Incorporar o Lender atrás do seu próprio produto
O Lender é um serviço do qual você faz o deploy, não uma biblioteca que você vincula. Para colocá-lo atrás de uma aplicação que os seus clientes já usam, guarde as credenciais do seu lado e chame o Lender de servidor para servidor. Quatro regras mantêm essa fronteira limpa. Nunca entregue um token do Lender a um navegador ou a um aplicativo móvel. O seu serviço autentica o seu usuário e decide se esse usuário pode agir. Depois ele chama o Lender com um token próprio. Gere o token para a pessoa que age. O Lender deriva o ator HTTP do subject do token, nunca de um campo da requisição. O analista responsável aprova e rejeita. Tanto o tomador quanto o analista responsável podem retirar. A política de ator da jurisdição fixada governa a aprovação e o desembolso, então não suponha que um único subject humano faz cada transição. Mantenha uma credencial por tenant. Um Lender self-hosted usa
DEFAULT_TENANT_ID. Na Lerian Cloud, o tenant vem da identidade validada, nunca de um header, de um parâmetro de query ou de um campo de corpo, então o seu serviço mantém uma credencial para cada tenant que atende.
Saiba das mudanças de estado pelos eventos. O Lender publica eventos de negócio pelo outbox dele e não inicia sem o backbone de eventos. Leia Eventos do Lender.
Um desembolso registra a intenção de lançamento dele na mesma transação de banco de dados que move a proposta para
disbursed. O Lender repassa essa intenção ao Midaz apenas quando o relay do ledger está configurado. Caso contrário, a intenção fica no outbox. Não trate um 200 no desembolso como prova de que o ledger já carrega o lançamento. Leia Contabilidade e rodadas de apropriação.Próximos passos
API REST do Lender
O caminho base, a autenticação, a idempotência e as operações por tarefa.
Eventos do Lender
O contrato de transmissão e os eventos em que você pode se inscrever.
Início rápido
Sete chamadas de um banco de dados vazio até um empréstimo desembolsado.
Pré-requisitos
Os serviços, as migrations e a configuração de que uma primeira chamada precisa.