对账
对账接口让您使用自己的调用方 ID(而不是平台分配的 UUID)核验哪些数据已进入 Waafir。它有意保持精简——只有两个路由——却是稳健集成的运营支柱:每一次健康的每日数据接入都以一次对账调用收尾。
为什么要按调用方 ID 对账
当您提交一笔 externalId: "L-001" 的贷款时,您的系统已经用这个名称来识别该行。向平台询问“你们有 L-001 吗?”是自然的后续步骤——而且无需先转换为平台 UUID,您的对账逻辑就能直接使用与账务系统相同的标识符。
平台保证 externalId 在投资组合内的有效行之间唯一,因此按 externalId 查找只需读取单行。
路由
| 方法 | 路径 | 用途 |
|---|---|---|
GET | /api/v1/monitoring/loan/loans/{externalId}?portfolioId=<UUID> | 按调用方 ID 读取单笔贷款。 |
GET | /api/v1/monitoring/loan/counts | 读取各实体的行数合计,可按投资组合、日期或实体筛选。 |
GET /api/v1/monitoring/loan/loans/{externalId}
按您提交的 externalId 读取单笔贷款。不包括已取消(软删除)的行。
请求
| 参数 | 位置 | 必填 | 约束 |
|---|---|---|---|
externalId | path | 是 | 1-255 个字符;对任何 URL 不安全字符进行百分号编码。 |
portfolioId | query | 是 | 拥有该贷款的投资组合的 UUID。 |
之所以必须提供 portfolioId,是因为 externalId 在不同投资组合之间并不唯一——它只在单个投资组合内唯一。
响应——200 OK
{
"loan": {
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"borrowerId": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "L-001",
"predecessorLoanId": null,
"principalAmount": "10000.0000",
"currencyCode": "USD",
"interestRateApr": "0.180000",
"disbursementDate": "2026-01-15",
"termMonths": 12,
"repaymentFrequency": "monthly",
"productType": "Term loan",
"status": "active",
"metadata": {},
"createdAt": "2026-01-15T08:00:00Z",
"updatedAt": "2026-01-15T08:00:00Z"
},
"borrower": {
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "B-001",
"name": "J***",
"email": "j***@example.com",
"phone": "***-***-1234",
"nationalIdLast4": "1234",
"countryCode": "KE",
"dob": "1985-03-20",
"gender": "female",
"incomeBand": null,
"employmentStatus": null
}
}响应中内嵌了该贷款的借款人,且 PII 已掩码处理。这是投资者范围的视图——与借款人 GET 端点采用相同的掩码。掩码让您可以确认“这笔贷款关联到了正确的借款人”,而不会向调用系统暴露 PII。需要原始 PII 的管理员应通过按 UUID 读取借款人的接口,使用 ?unmask=true 并留下审计日志记录。
金额字段以完整的存储精度返回(金额为四位小数;interestRateApr 为六位);您的客户端应将其视为不透明的十进制字符串,而不要解析为浮点数。
状态码
| 状态 | 触发条件 |
|---|---|
200 OK | 在您的组织中找到了该贷款。 |
400 Bad Request | portfolioId 缺失或格式错误,或 externalId 包含格式错误的百分号编码。 |
404 Not Found | 该贷款在所提供的投资组合中不作为有效行存在,或该投资组合属于其他组织。 |
cURL
curl https://app.waafir.io/api/v1/monitoring/loan/loans/L-001?portfolioId=ddf63d12-1234-5678-9abc-def012345678 \
-H "Authorization: Bearer $WAAFIR_PAT"GET /api/v1/monitoring/loan/counts
读取各实体的行数,可按投资组合、日期筛选,或只查看单个实体。已软删除的行不计入。
请求
| 参数 | 位置 | 必填 | 约束 |
|---|---|---|---|
portfolioId | query | 否 | UUID;限定为单个投资组合。省略则返回整个组织的汇总。 |
date | query | 否 | YYYY-MM-DD;提供后,响应会为每个实体包含一个 onDate 计数。 |
entity | query | 否 | borrowers、loans、scheduled_repayments、actual_payments、collateral、collateral_valuations 之一(不区分大小写)。提供后,只返回该实体。 |
响应——200 OK
默认汇总,包含全部六个实体:
{
"counts": {
"borrowers": { "total": 1200 },
"loans": { "total": 3450 },
"scheduled_repayments": { "total": 41400 },
"actual_payments": { "total": 32118 },
"collateral": { "total": 600 },
"collateral_valuations": { "total": 1840 }
},
"date": null,
"portfolioId": null
}使用 ?date=2026-05-22 时,每个实体会增加一个 onDate 计数,表示在所提供日期创建的行数:
{
"counts": {
"borrowers": { "total": 1200, "onDate": 0 },
"loans": { "total": 3450, "onDate": 12 },
"scheduled_repayments": { "total": 41400, "onDate": 144 },
"actual_payments": { "total": 32118, "onDate": 1207 },
"collateral": { "total": 600, "onDate": 0 },
"collateral_valuations": { "total": 1840, "onDate": 0 }
},
"date": "2026-05-22",
"portfolioId": null
}使用 ?entity=loans 时,只会出现 loans 条目。
状态码
| 状态 | 触发条件 |
|---|---|
200 OK | 查询已解析;返回计数。 |
400 Bad Request | portfolioId、date 或 entity 格式错误。 |
不存在或属于其他组织的 portfolioId 不会返回 404;而是返回 200,且所有计数均为零。这是有意为之——计数接口读取的是您自己的数据,而未知的投资组合在功能上与没有任何行的投资组合无法区分。
cURL
# Full daily reconciliation for one portfolio:
curl "https://app.waafir.io/api/v1/monitoring/loan/counts?portfolioId=ddf63d12-1234-5678-9abc-def012345678&date=2026-05-22" \
-H "Authorization: Bearer $WAAFIR_PAT"典型的每日对账
完成当天的提交后,标准的对账流程是:
- 调用
GET /counts?date=<today>,并指定您的投资组合。将每个实体的onDate计数与您今天提交的数量进行比较。如果计数与您提交的一致,说明您的批次已完整落库。 - 对于任何不一致之处,查找具体的行,使用
GET /loans/{externalId}。这些查找开销很小——每次只需一次索引扫描——并会返回规范的行状态,包括平台分配的 UUID,您可以借此进一步排查。 - 如需行级排查,可使用单条记录 GET 端点和异步导入的错误分页端点,它们会提供逐行的失败详情。
对账接口有意设计为只读且低开销——它是集成的心跳,而不是承载负载的接口。每个投资组合每天调用一两次即可;它没有专门的速率限制,但请不要在紧密循环中轮询它。