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

Receitas

Este livro de receitas é para engenheiros de fintechs que estão conectando o seu portfólio de empréstimos à API de monitoramento do Waafir. Cada receita percorre uma tarefa de ponta a ponta com os três clientes de referência — cURL, TypeScript, Python —, para que o leitor não precise traduzir mentalmente de uma linguagem para outra. As receitas privilegiam os caminhos de falha e de casos-limite que uma integração real encontra, e não apenas o caminho feliz.

Para quem é

Você recebeu um token de acesso pessoal (PAT) do administrador da sua organização no Waafir e está escrevendo o código que envia os dados diários da sua fita de empréstimos — tomadores, empréstimos, parcelas programadas, pagamentos efetivos, garantias e avaliações de garantias — para o Waafir. Cada envio é registrado tal como foi enviado e, em seguida, armazenado como linhas; a partir daí, alimenta a guia de monitoramento para investidores de qualquer sala de dados vinculada ao portfólio.

Como usar estas receitas

Todas as receitas têm o mesmo formato: um breve texto introdutório, três blocos de código em ordem fixa e um parágrafo curto de verificação. Os blocos de código são:

  1. cURL — copie e cole no seu shell. O menos opinativo; útil para sondagens pontuais e verificações de CI.
  2. TypeScript — baseado em fetch, sobre os contratos JSON públicos. Nenhuma instalação de SDK necessária.
  3. Python — baseado em requests, sobre os mesmos contratos JSON. A biblioteca padrão basta; nenhum pacote específico do Waafir é necessário.

Autenticação

Todos os endpoints exigem um PAT no cabeçalho Authorization:

Authorization: Bearer <YOUR_PAT>

Um PAT tem como escopo uma única organização do Waafir e carrega a identidade dessa organização em cada requisição. Trate-o como um segredo; faça a rotação pelo painel caso ele vaze. A URL base da API em todas estas receitas é https://app.waafir.io — substitua-a pela sua URL de staging se estiver integrando primeiro com o tenant de sandbox.

Convenções usadas nas receitas

  • Todas as variáveis de shell nos exemplos de cURL são escritas como ${UPPER_CASE_NAME}, para que você possa fazer export delas uma vez e reutilizá-las entre as receitas.
  • Os exemplos em TypeScript e Python presumem que BASE_URL e PAT são lidos do ambiente. Adapte ao seu carregador de configuração.
  • O cabeçalho Idempotency-Key é a convenção de toda a plataforma para novas tentativas seguras; consulte a receita de novas tentativas para a semântica exata.
  • Todos os endpoints de escrita aceitam os seus próprios valores de external_id — os identificadores fornecidos pelo chamador continuam sendo a referência oficial durante a ingestão, a conciliação e os downloads da fita. Você nunca precisa conhecer os UUIDs internos do Waafir.

O que o livro de receitas não cobre

O livro de receitas é orientado a tarefas. Para definições completas dos endpoints, esquemas de requisição e resposta e referências de códigos de erro, consulte a seção de referência da API quando ela for publicada junto com o livro de receitas. Para conceitos do produto, como o que é um portfólio e como ele se relaciona com uma sala de dados, consulte Salas de dados e a seção de conceitos fundamentais.

As receitas

  1. Importar uma fita de empréstimos em massa via NDJSON assíncrono — o fluxo de ingestão fundamental: upload direto, commit, consulta periódica até a conclusão.
  2. Validar uma carga com execução de teste antes de gravar dados — o mesmo fluxo com ?dryRun=true; descubra o que o seu arquivo contém antes que qualquer linha seja gravada.
  3. Repetir com segurança usando uma chave de idempotência — sobreviva a falhas de rede transitórias sem criar importações duplicadas.
  4. Inspecionar erros de falha parcial após uma importação — percorra, página a página, os erros por linha quando uma importação termina como partial.
  5. Cancelar uma importação em andamento — interrompa uma importação demorada no próximo limite de lote, sem linhas gravadas pela metade.
  6. Conciliar os seus dados por ID externo — confirme que uma linha foi gravada, pelo seu próprio identificador, e verifique as contagens diárias.