Referência da API
Esta seção é o manual de referência da API do domínio de empréstimos do Waafir — a interface HTTP que as fintechs usam para enviar dados de portfólio ao Waafir para o monitoramento por investidores. Ela documenta cada rota em /api/v1/monitoring/loan/, os schemas de requisição e resposta, cada código de status, o contrato compartilhado de experiência do desenvolvedor e os envelopes de erro que você deve esperar.
A referência é exaustiva, mas não narrativa. Se você está integrando pela primeira vez e quer um roteiro guiado de ponta a ponta — com cURL, TypeScript e Python lado a lado —, leia as Receitas junto com esta referência; as duas foram feitas para serem lidas em conjunto.
O que a API cobre
A API do domínio de empréstimos oferece quatro formas de ingestão, além de uma interface de conciliação:
- CRUD de registro único — uma chamada HTTP por linha. Use para gravações operacionais de baixo volume: um único empréstimo novo, um único pagamento, uma transição de status.
- NDJSON em lote — até dez mil linhas em uma única chamada síncrona. Use para lotes de fim de dia que cabem em uma única requisição HTTP.
- Importações assíncronas — um upload direto de arquivo seguido de processamento assíncrono. Use para cargas históricas ou qualquer lote acima de dez mil linhas.
- Conciliação — leitura de volta das linhas enviadas pelos seus próprios IDs do chamador e contagens de linhas por entidade. Use para verificar se o envio de ontem chegou corretamente antes de fazer o envio de hoje.
Cada forma é tratada em uma página própria. A ordem das páginas segue a ordem em que a maioria dos integradores as percorre: leia a visão geral, depois o modo de ingestão que você pretende usar primeiro, depois a conciliação e, por fim, a referência de erros.
As seis entidades do domínio de empréstimos
Toda rota opera sobre uma ou mais das entidades a seguir. Os schemas completos estão documentados em cada rota — esta lista é o catálogo:
borrower— a pessoa física ou jurídica que toma o empréstimo, com campos opcionais de dados pessoais (PII) que são mascarados na leitura.loan— o próprio contrato de empréstimo: principal, moeda, APR, prazo, frequência de pagamento, status.scheduled_repayment— o cronograma contratual de pagamentos, uma linha por data de vencimento.actual_payment— os pagamentos efetivamente recebidos, incluindo baixas e pagamentos parciais.collateral— garantia vinculada a um empréstimo.collateral_valuation— avaliações pontuais de uma linha de garantia, com suporte a vários métodos.
Toda entidade pertence a um portfólio da sua organização. O portfólio é informado em cada gravação; a organização vem do seu token de acesso pessoal e nunca aparece no corpo de uma requisição.
Autenticação em uma linha
Toda requisição leva Authorization: Bearer <PAT>, em que <PAT> é um token de acesso pessoal emitido pelo plano de controle do Waafir. Os tokens têm escopo de organização — um token emitido para a organização A não pode ler nem gravar dados da organização B, e leituras entre organizações retornam 404 Not Found em vez de 403 Forbidden para não revelar a existência de recursos de outro tenant.
O modelo completo de autenticação e autorização é tratado na visão geral.
Como usar esta referência
Leia as páginas em ordem ou vá direto à interface de que você precisa:
- Visão geral — o contrato compartilhado que toda rota do domínio de empréstimos respeita: autenticação, as garantias de integração (IDs fornecidos pelo chamador, idempotência, simulações), envelopes de erro, convenções de valores monetários e datas, semântica de cancelamento e como cada envio é registrado.
- CRUD de registro único — cada rota de POST, GET, PATCH e cancelamento de linha única.
- NDJSON em lote — ingestão síncrona em lote com relatório de erros por linha.
- Importações assíncronas — o ciclo de vida de upload em duas fases, consulta de status e paginação de erros.
- Conciliação — leitura de volta por ID do chamador e contagens de linhas por entidade.
- Erros e códigos de status — o catálogo consolidado de todos os códigos de status, envelopes de erro e códigos de erro nomeados emitidos pela interface do domínio de empréstimos.
Para guias orientados a tarefas — integrar um portfólio de ponta a ponta, executar uma conciliação diária, recuperar-se de uma importação que falhou parcialmente — consulte as Receitas (publicadas junto com esta referência). As Receitas percorrem cada tarefa em três linguagens; esta referência é a fonte de verdade sobre o que cada rota aceita e retorna.
O que não está nesta referência
- Onboarding e tokens — como registrar uma organização, criar um portfólio e emitir um token de acesso pessoal. Esses fluxos são tratados na documentação de administração da plataforma e na receita de primeiros passos das Receitas.
- Análises voltadas a investidores — pacotes de gráficos, a exportação do tape e a interface de download do loan tape. Eles são disponibilizados por rotas separadas e não são tratados aqui.
- Webhooks e entrega agendada do tape — não tratados aqui.