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

Visão geral

Todos os endpoints do domínio de empréstimos compartilham o contrato descrito nesta página. Leia-a primeiro; as páginas de cada interface fazem referência a ela em vez de repeti-la.

URL base e versionamento

Todas as rotas do domínio de empréstimos ficam em /api/v1/monitoring/loan/. O inteiro depois de v é a versão major: um salto de major é uma mudança incompatível e só acontece com aviso explícito de descontinuação. A evolução dentro de uma versão major é somente aditiva — novos campos opcionais, novos endpoints, novos valores de enum — e nunca quebra uma integração que ignora campos que não entende.

O host de produção é https://app.waafir.io. Para obter uma URL completa, acrescente o host antes de qualquer caminho desta referência, por exemplo https://app.waafir.io/api/v1/monitoring/loan/borrowers.

Autenticação

Toda requisição leva um cabeçalho Authorization com um Bearer token:

Authorization: Bearer <PAT>

<PAT> é um token de acesso pessoal emitido pelo plano de controle do Waafir para uma única organização. A organização do token determina o escopo de tenant de cada leitura e de cada gravação — não há parâmetro de organização em nenhuma URL ou corpo, porque o token já a fixa.

Requisições entre organizações retornam 404 Not Found, não 403 Forbidden. Retornar 403 revelaria, pelo id, a existência de um recurso de outro tenant; a postura de 404 trata ids desconhecidos e ids de outros tenants de forma idêntica.

Uma requisição sem cabeçalho Authorization, com um token desconhecido ou com um token revogado retorna 401 Unauthorized.

Garantias de integração

Toda rota de escrita respeita as garantias abaixo. Seu código cliente pode contar com cada uma delas; lendo-as uma vez aqui, você implementa uma integração robusta em uma única passada.

IDs fornecidos pelo chamador

Toda entidade tem um campo id no corpo da requisição, que você informa como UUID. A plataforma nunca inventa IDs por você. Essa é a base de todos os outros compromissos desta lista: idempotência, conciliação e reprocessamento dependem de você poder endereçar uma linha por um identificador que você escolheu.

Se você reenviar por POST uma linha com o mesmo id, receberá 409 ID_CONFLICT e uma entrada em fieldErrors apontando para id. Escolha seus IDs com cuidado — UUIDv4 gerados são recomendados, mas qualquer UUID bem formado funciona.

Além do id, toda entidade também tem um externalId — uma string livre de até 255 caracteres que você usa para endereçar a linha a partir do seu próprio sistema. Um externalId é único dentro de um portfólio entre as linhas ativas, e é isso que torna possível a conciliação por ID do chamador.

Cabeçalho Idempotency-Key

Toda rota de escrita lê um cabeçalho HTTP opcional Idempotency-Key. Quando presente, a plataforma faz a deduplicação com base em um arquivo interno: uma segunda requisição com a mesma chave retorna a mesma resposta que a primeira, mesmo que o corpo seja ligeiramente diferente. É assim que os clientes sobrevivem a falhas de rede que os deixam sem saber se uma requisição chegou.

O cabeçalho não diferencia maiúsculas de minúsculas na transmissão (Idempotency-Key, idempotency-key, IDEMPOTENCY-KEY funcionam). O valor é tratado como opaco — escolha algo estável por operação lógica, normalmente um UUIDv4 mais um discriminador de rota.

?dryRun=true

Toda rota de escrita aceita o parâmetro de query ?dryRun=true. Uma requisição de simulação executa a validação e as verificações de tenant e retorna a entrada validada, mas não registra nada nem armazena nenhuma linha. Use-a para confirmar que um corpo é interpretado corretamente antes de fazer uma gravação real.

O formato da resposta em uma simulação bem-sucedida é { "dryRun": true, "validatedInput": <body> } com 200 OK. Falhas de validação durante uma simulação retornam o mesmo formato 400 de uma gravação real; só os efeitos colaterais diferem.

Envelope de validação fieldErrors

Falhas de validação retornam 400 Bad Request com um envelope estruturado:

{
  "error": "Validation failed",
  "fieldErrors": [
    { "path": "interestRateApr", "message": "interestRateApr must be >= 0" },
    { "path": "termMonths", "message": "termMonths must be > 0" }
  ]
}

path é o caminho com pontos até o campo com problema; message é uma explicação legível. O envelope é uniforme em todas as rotas, então um único handler no cliente consegue exibir qualquer falha de validação de forma consistente.

Enums sem distinção de maiúsculas e minúsculas, com sugestões de "você quis dizer"

Os enums de domínio (status do empréstimo, forma de pagamento, frequência de pagamento, código de moeda e assim por diante) aceitam qualquer combinação de maiúsculas e minúsculas na transmissão. A plataforma normaliza para a forma canônica em minúsculas antes de persistir.

Um valor não reconhecido retorna 400 com uma entrada em fieldErrors que indica o valor com problema e sugere o valor aceito mais próximo:

{
  "error": "Validation failed",
  "fieldErrors": [
    {
      "path": "status",
      "message": "got 'restruktured', did you mean 'restructured'?"
    }
  ]
}

A sugestão é calculada com uma pequena métrica de distância de edição, de modo que transposições e erros de digitação isolados são detectados com confiabilidade.

Repasse de metadata JSONB

Toda entidade aceita um campo opcional metadata do tipo objeto. A plataforma persiste o objeto literalmente — nenhuma chave é removida, nenhum valor é convertido. Use-o para anexar contexto do cliente que a própria plataforma não precisa entender: seu ID interno, o sistema de origem, um timestamp de extração, um código de campanha.

Duas interfaces não aceitam metadata: a rota de transição de status do empréstimo e as rotas de cancelamento de pagamento. A justificativa está documentada junto a essas rotas.

Conciliação por ID do chamador

Toda entidade pode ser endereçada pelo externalId que você enviou, dentro do escopo de um portfólio. A interface de conciliação — GET /loans/{externalId} e GET /counts — usa isso para que você verifique gravações sem nunca precisar do UUID atribuído pela plataforma. Veja os formatos exatos na página de conciliação.

Representação de valores monetários

Os valores monetários são, no formato de transmissão, strings de dígitos decimais, com até quatro casas decimais. O number do JavaScript é rejeitado porque os floats binários IEEE-754 não conseguem representar centavos decimais com exatidão:

{ "amount": "100.50", "currencyCode": "USD" }

Um decimal com mais de quatro casas decimais, ou um valor com caracteres além de dígitos, um sinal de menos inicial e um único ponto, retorna 400 com uma entrada em fieldErrors. Strings vazias são rejeitadas.

Os códigos de moeda são códigos ISO-4217 de três letras. A plataforma reconhece explicitamente o conjunto mais comum; códigos desconhecidos que seguem o formato de três letras maiúsculas são aceitos e persistidos literalmente, para que códigos de mercados exóticos não sejam bloqueados.

Formato de data

As datas são, no formato de transmissão, strings de calendário ISO-8601 no formato YYYY-MM-DD:

{ "disbursementDate": "2026-01-15" }

Não há componente de fuso horário. As datas são datas de calendário na interpretação do portfólio; a plataforma não faz conversão.

Semântica de cancelamento

Chamadas à API nunca apagam uma linha. Um cancelamento ou outra reversão marca a linha como cancelada. As implicações:

  • O externalId não é liberado por um cancelamento. Um externalId é único dentro de um portfólio apenas entre as linhas ativas. Uma linha cancelada deixa de estar ativa, então você pode reutilizar o externalId dela em um reenvio corrigido.
  • Leituras de conciliação não retornam linhas canceladas por padrão. As interfaces GET /loans/{externalId} e GET /counts excluem linhas com exclusão lógica (soft delete) da resposta padrão.
  • Os registros de envio são mantidos de qualquer forma. Mesmo quando uma linha é cancelada, o registro do envio que a criou permanece intacto para auditoria.

Todo envio é registrado

Toda mutação bem-sucedida registra o corpo bruto da requisição antes de a linha ser gravada. As implicações para a sua integração:

  • Um 200/201 significa que o seu envio foi registrado de forma durável, mesmo que o processamento posterior o sinalize depois. Sua trilha de auditoria começa no momento em que a plataforma confirma a requisição.
  • Um 409 ID_CONFLICT também é arquivado. O registro de envio guarda tanto o conflito quanto o envio tentado, para que você possa investigar depois sem ambiguidade sobre o que foi enviado.
  • Importações assíncronas são registradas no momento do commit. O arquivo NDJSON enviado e a própria importação são o registro; não há um registro separado por linha para uma importação assíncrona.

O registro de envio não pode ser alterado. Você nunca o lê diretamente pela API pública, mas é por causa dele que a interface de conciliação é confiável — toda linha visível ali tem uma entrada de arquivo correspondente por trás.

Como o restante desta referência está organizado

Cada página seguinte desta referência documenta uma forma de ingestão ou a interface de conciliação. Toda página de rota segue a mesma estrutura: uma frase sobre a finalidade, o formato da requisição (cabeçalhos, query, corpo), o formato da resposta por código de status e uma chamada cURL mínima. As restrições campo a campo ficam em tabelas fáceis de consultar; exemplos aprofundados e amostras de código em três linguagens ficam nas Receitas.

A página erros e códigos de status é a referência consolidada dos envelopes de resposta usados por todas as rotas desta referência. Leia-a uma vez antes de integrar; volte a ela sempre que um status diferente de 200 surpreender você.