Waafir
Esta página é uma tradução automática pendente de revisão humana. Pode conter erros.

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.