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

对账

对账接口让您使用自己的调用方 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 读取单笔贷款。不包括已取消(软删除)的行。

请求

参数位置必填约束
externalIdpath是1-255 个字符;对任何 URL 不安全字符进行百分号编码。
portfolioIdquery是拥有该贷款的投资组合的 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 RequestportfolioId 缺失或格式错误,或 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

读取各实体的行数,可按投资组合、日期筛选,或只查看单个实体。已软删除的行不计入。

请求

参数位置必填约束
portfolioIdquery否UUID;限定为单个投资组合。省略则返回整个组织的汇总。
datequery否YYYY-MM-DD;提供后,响应会为每个实体包含一个 onDate 计数。
entityquery否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 RequestportfolioId、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"

典型的每日对账

完成当天的提交后,标准的对账流程是:

  1. 调用 GET /counts?date=<today>,并指定您的投资组合。将每个实体的 onDate 计数与您今天提交的数量进行比较。如果计数与您提交的一致,说明您的批次已完整落库。
  2. 对于任何不一致之处,查找具体的行,使用 GET /loans/{externalId}。这些查找开销很小——每次只需一次索引扫描——并会返回规范的行状态,包括平台分配的 UUID,您可以借此进一步排查。
  3. 如需行级排查,可使用单条记录 GET 端点和异步导入的错误分页端点,它们会提供逐行的失败详情。

对账接口有意设计为只读且低开销——它是集成的心跳,而不是承载负载的接口。每个投资组合每天调用一两次即可;它没有专门的速率限制,但请不要在紧密循环中轮询它。