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

实战手册

本实战手册面向需要将贷款投资组合接入 Waafir 监控 API 的金融科技工程师。每个方案都使用全部三种参考客户端——cURL、TypeScript、Python——完整演示一项任务,读者无需在脑海中进行语言之间的转换。这些方案侧重于真实集成会遇到的失败和边界情况路径,而不仅仅是顺利路径。

适用对象

您已经从 Waafir 组织管理员处获得一个个人访问令牌(PAT),并且正在编写代码,将每日贷款明细表数据——借款人、贷款、计划还款、实际还款、抵押品和抵押品估值——提交到 Waafir。每次提交都会按发送时的原样记录,然后存储为行;之后,这些数据会为与该投资组合关联的任何数据室中的投资者监控标签页提供支持。

如何使用这些方案

每个方案的结构都相同:一段简短的文字说明、三个按固定顺序排列的围栏代码块,以及一段简短的验证说明。这些代码块分别是:

  1. cURL——可直接复制粘贴到 shell 中运行。最不受特定约定限制;适用于一次性探测和 CI 检查。
  2. TypeScript——基于 fetch,直接调用公开的 JSON 契约。无需安装 SDK。
  3. Python——基于 requests,调用同样的 JSON 契约。标准库即可满足需求;无需安装任何 Waafir 专用包。

身份验证

所有端点都要求在 Authorization 标头中提供 PAT:

Authorization: Bearer <YOUR_PAT>

PAT 的作用域限定于单个 Waafir 组织,并在每个请求中携带该组织的身份。请将其视为机密;如有泄露,请通过仪表板轮换。这些方案中使用的 API 基础 URL 均为 https://app.waafir.io——如果您先针对沙盒租户进行集成,请将其替换为您的预发布环境 URL。

方案中使用的约定

  • cURL 示例中的所有 shell 变量都写作 ${UPPER_CASE_NAME},这样您可以一次性 export 它们,并在各个方案中重复使用。
  • TypeScript 和 Python 示例假定从环境变量中读取 BASE_URL 和 PAT。请根据您的配置加载方式进行调整。
  • Idempotency-Key 标头是平台范围内用于安全重试的约定;具体语义请参阅重试方案。
  • 所有写入端点都接受您自己的 external_id 值——在摄取、对账和贷款明细表下载的全过程中,调用方提供的标识符始终是权威的引用依据。您永远不需要了解 Waafir 的内部 UUID。

本手册不涵盖的内容

本实战手册以任务为导向。如需完整的端点定义、请求和响应模式以及错误代码参考,请参阅 API 参考部分(它将与本手册一同发布)。关于产品概念,例如什么是投资组合以及它与数据室的关系,请参阅数据室和基础概念部分。

方案列表

  1. 通过异步 NDJSON 批量导入贷款明细表——基础摄取流程:直接上传、提交、轮询直至完成。
  2. 在提交数据前用试运行验证加载——相同的流程,但加上 ?dryRun=true;在写入任何行之前了解文件包含的内容。
  3. 使用幂等键安全重试——在不创建重复导入的情况下应对短暂的网络故障。
  4. 导入后排查部分失败错误——当导入以 partial 结束时,分页浏览逐行错误。
  5. 取消正在进行的导入——在下一个批次边界停止长时间运行的导入,不会留下部分写入的行。
  6. 按外部 ID 核对数据——用您自己的标识符确认某一行已落库,并核验每日计数。