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:
- cURL — copie e cole no seu shell. O menos opinativo; útil para sondagens pontuais e verificações de CI.
- TypeScript — baseado em
fetch, sobre os contratos JSON públicos. Nenhuma instalação de SDK necessária. - 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 fazerexportdelas uma vez e reutilizá-las entre as receitas. - Os exemplos em TypeScript e Python presumem que
BASE_URLePATsã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
- 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.
- 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. - Repetir com segurança usando uma chave de idempotência — sobreviva a falhas de rede transitórias sem criar importações duplicadas.
- 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. - Cancelar uma importação em andamento — interrompa uma importação demorada no próximo limite de lote, sem linhas gravadas pela metade.
- Conciliar os seus dados por ID externo — confirme que uma linha foi gravada, pelo seu próprio identificador, e verifique as contagens diárias.