Skip to main content
A API REST do Lender é toda a superfície de cliente. Produtos, propostas, contas de empréstimo, rodadas de apropriação e os registros regulatórios brasileiros são todos chamadas HTTP sob /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 como requestedInterestRate são strings com oito casas decimais. Os campos fixedAnnualRateBps, floatingSpreadBps e annualRateBps são pontos-base inteiros:
Envie a string, e faça o parse da string com o tipo decimal da sua linguagem. Um float binário perde centavos, e um número JSON convida a isso. Os timestamps são RFC 3339 em UTC.

​
Os erros respondem problem+json

A maioria dos erros de operação e de fallback responde application/problem+json. Não suponha isso para as respostas 401/403 da lib-auth. 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 escritas de dinheiro com a sua própria chave

Desembolso, encargos de produto, pagamento antecipado, pagamento antecipado do pacote Brasil, reprogramação, pagamento e estorno aceitam, cada um, uma chave de idempotência que você gera. Derive essa chave do seu próprio identificador de requisição, e uma nova tentativa não custa nada enquanto o armazenamento de idempotência estiver disponível. As cinco operações que exigem X-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 e estorno 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 aberto durante uma indisponibilidade do armazenamento de idempotência. Uma falha ambígua pode já ter executado a operação. Confirme o resultado antes de repetir uma escrita de dinheiro nessa janela. 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 aceitam limit 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. No fluxo humano genérico, 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. No modo single-tenant o Lender usa DEFAULT_TENANT_ID. No modo multi-tenant o tenant vem da identidade validada, nunca de um header, de um parâmetro de query ou de um campo de corpo. Cada token carrega uma claim tenantId, então o seu serviço mantém uma credencial para cada tenant que atende. Leia Multi-tenancy. Saiba das mudanças de estado pelos eventos. Quando o streaming está habilitado e um broker está configurado, o Lender publica eventos de negócio pelo outbox dele. Quando o streaming está desabilitado, ele usa um emissor no-op. Quando o streaming está habilitado sem broker configurado, o Lender recusa subir em vez de recorrer ao emissor no-op. Habilite e configure o streaming antes de tratar a entrega de eventos como contrato de integração. 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 que você pode assinar.

Início rápido

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