概述
每个贷款领域端点都共享本页所述的约定。请先阅读本页;各接口页面会引用这里的内容,而不再重复说明。
基础 URL 与版本
所有贷款领域路由都挂载在 /api/v1/monitoring/loan/ 下。v 后面的整数是主版本号:主版本升级属于破坏性变更,只会在明确发出弃用通知后进行。同一主版本内的小幅演进只做增量——新增可选字段、新端点、新枚举值——绝不会破坏忽略未知字段的集成。
生产环境主机为 https://app.waafir.io。要得到完整 URL,请在本参考站点上的任意路径前加上该主机,例如 https://app.waafir.io/api/v1/monitoring/loan/borrowers。
身份验证
每个请求都携带一个包含 Bearer 令牌的 Authorization 请求头:
Authorization: Bearer <PAT><PAT> 是由 Waafir 控制平面针对单个组织签发的个人访问令牌。令牌所属的组织决定了每次读写的租户范围——任何 URL 或请求体中都没有组织参数,因为令牌已经将其固定。
跨组织请求返回 404 Not Found,而不是 403 Forbidden。 返回 403 会按 id 泄露其他租户资源的存在;采用 404 策略后,未知 id 和其他租户的 id 会被同等对待。
缺少 Authorization 请求头、令牌未知或令牌已吊销的请求会返回 401 Unauthorized。
集成保证
每个变更类路由都遵守以下保证。每一条都是您的客户端代码可以依赖的;在这里读一遍,就能一次性实现稳健的集成。
调用方提供的 ID
每个实体的请求体中都有一个 id 字段,由您以 UUID 形式提供。平台从不替您生成 ID。这是本列表中其他所有约定的基础:幂等性、对账和重放都依赖于您能够通过自己选定的标识符定位某一行。
如果您用相同的 id 再次 POST 一行,将收到 409 ID_CONFLICT,以及一条指向 id 的 fieldErrors 条目。请谨慎选择 ID——推荐使用生成的 UUIDv4,但任何格式正确的 UUID 都可以。
除 id 外,每个实体还带有一个 externalId——最长 255 个字符的自由格式字符串,供您从自己的系统定位该行。对于有效行,externalId 在投资组合内唯一,这正是按调用方 ID 对账得以实现的原因。
Idempotency-Key 请求头
每个变更类路由都会读取可选的 Idempotency-Key HTTP 请求头。若提供该请求头,平台会对照内部存档进行去重:使用相同键的第二次请求将返回与第一次相同的响应,即使请求体略有不同。客户端正是借此应对网络抖动——此时它们无法确定请求是否已送达。
该请求头在传输时不区分大小写(Idempotency-Key、idempotency-key、IDEMPOTENCY-KEY 都有效)。其值被视为不透明字符串——请为每个逻辑操作选择一个稳定的值,通常是 UUIDv4 加上路由区分标识。
?dryRun=true
每个变更类路由都接受 ?dryRun=true 查询参数。试运行请求会执行校验和租户检查并返回校验后的输入,但不会记录任何内容,也不会存储任何行。可在正式写入前用它确认请求体能被正确解析。
试运行成功时的响应结构为 { "dryRun": true, "validatedInput": <body> },状态码为 200 OK。试运行期间的校验失败会返回与真实写入相同的 400 结构;区别仅在于副作用。
fieldErrors 校验响应封装
校验失败时返回 400 Bad Request,并附带结构化的响应封装:
{
"error": "Validation failed",
"fieldErrors": [
{ "path": "interestRateApr", "message": "interestRateApr must be >= 0" },
{ "path": "termMonths", "message": "termMonths must be > 0" }
]
}path 是指向出错字段的点分路径;message 是便于阅读的说明。该响应封装在所有路由中保持一致,因此只需一个客户端处理器即可统一呈现所有校验失败。
不区分大小写的枚举与“您是不是想输入”提示
领域枚举(贷款状态、还款方式、还款频率、币种代码等)在传输时接受任意大小写。平台在持久化之前会将其规范化为标准的小写形式。
未匹配时返回 400,其 fieldErrors 条目会指出出错的值,并建议最接近的可接受值:
{
"error": "Validation failed",
"fieldErrors": [
{
"path": "status",
"message": "got 'restruktured', did you mean 'restructured'?"
}
]
}建议值通过一个小型编辑距离算法计算,因此能可靠地识别字母颠倒和单字符拼写错误。
metadata JSONB 透传
每个实体都接受一个可选的、类型为对象的 metadata 字段。平台会原样持久化该对象——不删除任何键,也不强制转换任何值。可用它附加平台本身无需理解的客户端上下文:您的内部 ID、来源系统、抽取时间戳、营销活动代码。
有两个接口不接受 metadata:贷款状态变更路由和还款取消路由。其原因在这两个路由的说明中给出。
按调用方 ID 对账
每个实体都可以通过您提交的 externalId 在某个投资组合范围内定位。对账接口——GET /loans/{externalId} 和 GET /counts——借此让您无需平台分配的 UUID 即可核验写入结果。具体结构请参见对账页面。
金额表示
金额在传输时为十进制数字字符串,最多四位小数。JavaScript 的 number 会被拒绝,因为 IEEE-754 二进制浮点数无法精确表示十进制的分:
{ "amount": "100.50", "currencyCode": "USD" }小数位超过四位,或包含数字、前导负号和单个小数点以外字符的值,会返回 400 及一条 fieldErrors 条目。空字符串会被拒绝。
币种代码为 ISO-4217 三字母代码。平台显式识别常用代码集;对于符合三个大写字母格式的未知代码,平台会接受并原样保存,因此不会阻碍小众市场的币种代码。
日期格式
日期在传输时为 YYYY-MM-DD 形式的 ISO-8601 日历日期字符串:
{ "disbursementDate": "2026-01-15" }日期不含时区部分。日期是按投资组合自身口径理解的日历日期;平台不做转换。
取消语义
API 调用从不擦除任何行。取消或其他冲销操作会将该行标记为已取消。由此带来的影响:
- 取消不会释放
externalId。externalId只在投资组合内的有效行之间唯一。已取消的行不再有效,因此您可以在更正后重新提交时复用其externalId。 - 对账读取默认不返回已取消的行。
GET /loans/{externalId}和GET /counts接口的默认响应会排除已软删除的行。 - 提交记录无论如何都会保留。 即使某行被取消,创建它的那次提交的记录仍完整保留,以供审计。
每次提交都会被记录
每次成功的变更都会在写入行之前记录原始请求体。这对您的集成意味着:
200/201表示您的提交已被持久记录,即使下游处理稍后将其标记出问题。您的审计轨迹从平台确认请求的那一刻开始。409 ID_CONFLICT也会存档。 提交记录同时保存冲突信息和所尝试的提交内容,因此您日后排查时,对于究竟发送了什么不会有任何疑义。- 异步导入在提交(commit)时记录。 上传的 NDJSON 文件和导入本身就是记录;异步导入没有单独的逐行记录。
提交记录不可更改。您无法通过公共 API 直接读取它,但正因为有它,对账接口才具有权威性——那里可见的每一行背后都有对应的存档条目。
本参考其余部分的组织方式
本参考站点后续的每一页分别介绍一种接入方式或对账接口。每个路由页面都采用相同的结构:一句话说明用途、请求结构(请求头、查询参数、请求体)、各状态码对应的响应结构,以及一个最简 cURL 调用示例。逐字段的约束列在便于浏览的表格中;深入示例和三种语言的代码示例则放在“实战手册”中。
错误与状态码页面汇总了本站点所有路由使用的响应封装。请在集成前通读一遍;每当遇到意料之外的非 200 状态时,再回来查阅。