Waafir
本页面为机器翻译,尚待人工审核,可能存在错误。

API 参考

本节是 Waafir 贷款领域 API 的参考手册。金融科技公司通过这一 HTTP 接口将投资组合数据持续推送到 Waafir,供投资者进行投后监控。本节记录了 /api/v1/monitoring/loan/ 下的每个路由、请求与响应的 schema、每个状态码、统一的开发者体验约定,以及您应预期的错误响应封装。

本参考力求详尽,但并非叙述性教程。如果您是首次集成,并希望获得一份端到端的分步指南(并排提供 cURL、TypeScript 和 Python 示例),请将“实战手册”与本参考配合阅读;两者本就是为配套使用而设计的。

API 涵盖的范围

贷款领域 API 提供四种接入方式以及一个对账接口:

  • 单条记录 CRUD——每行数据一次 HTTP 调用。适用于低频的业务写入:一笔新贷款、一笔还款、一次状态变更。
  • 批量 NDJSON——一次同步调用最多一万行。适用于可放入单个 HTTP 请求的日终批次。
  • 异步导入——先直接上传文件,再进行异步处理。适用于历史数据加载或任何超过一万行的批次。
  • 对账——按您自己的调用方 ID 回读已提交的行,并获取各实体的行数。用于在提交今天的数据之前,确认昨天的提交已完整落库。

每种方式都有单独的页面介绍。页面顺序与大多数集成方的阅读顺序一致:先读概述,再读您计划首先使用的接入方式,然后是对账,最后是错误参考。

六个贷款领域实体

每个路由都作用于以下一个或多个实体。它们的完整 schema 在各路由中分别说明,此处仅列出目录:

  • borrower——借款的自然人或法人,带有可选的 PII 字段,读取时会被掩码处理。
  • loan——贷款协议本身:本金、币种、APR、期限、还款频率、状态。
  • scheduled_repayment——合同约定的还款计划,每个到期日一行。
  • actual_payment——实际收到的还款,包括核销和部分还款。
  • collateral——为贷款提供的抵押品。
  • collateral_valuation——某条抵押品记录在某一时点的估值,支持多种估值方法。

每个实体都隶属于您组织中的某个投资组合。每次写入都需提供投资组合;组织则由您的个人访问令牌确定,从不出现在请求体中。

一句话说明身份验证

每个请求都携带 Authorization: Bearer <PAT>,其中 <PAT> 是由 Waafir 控制平面签发的个人访问令牌。令牌的作用域限定在组织内:签发给组织 A 的令牌无法读写组织 B 的数据,跨组织读取会返回 404 Not Found 而非 403 Forbidden,以免泄露其他租户资源的存在。

完整的身份验证与授权模型请参见概述。

如何使用本参考

可按顺序阅读各页,也可直接跳转到所需的接口:

  • 概述——每个贷款领域路由都遵守的统一约定:身份验证、集成保证(调用方提供的 ID、幂等性、试运行)、错误响应封装、金额与日期约定、取消语义,以及每次提交如何被记录。
  • 单条记录 CRUD——所有单行的 POST、GET、PATCH 和取消路由。
  • 批量 NDJSON——带逐行错误报告的同步批量接入。
  • 异步导入——两阶段上传、状态轮询和错误分页的完整生命周期。
  • 对账——按调用方 ID 回读以及各实体的行数统计。
  • 错误与状态码——贷款领域接口返回的所有状态码、错误响应封装和命名错误码的汇总目录。

如需面向任务的指南(端到端接入一个投资组合、执行每日对账、从部分失败的导入中恢复),请参阅与本参考同步发布的“实战手册”。“实战手册”以三种语言演示每项任务;而本参考是各路由接受什么、返回什么的权威依据。

本参考不包含的内容

  • 入驻与令牌——如何注册组织、创建投资组合以及签发个人访问令牌。这些流程在平台管理文档和“实战手册”的入门示例中介绍。
  • 面向投资者的分析——图表包、贷款数据带(tape)导出以及贷款数据带下载接口。它们通过单独的路由提供,此处不作介绍。
  • Webhook 与定时数据带推送——此处不作介绍。