单条记录 CRUD
单条记录 CRUD 接口是低频路径:每行数据一次 HTTP 调用。它适用于业务写入——一笔新贷款、一笔未赶上每日批次的还款、一次状态变更——以及按平台 UUID 回读。日终批次请使用批量 NDJSON;历史数据加载请使用异步导入。
本页的每个路由都遵守概述中记录的约定:Bearer 令牌身份验证、集成保证、fieldErrors 响应封装、取消语义,以及每次提交如何被记录。下文的逐路由说明只列出各路由特有的结构;跨路由的通用行为请回看概述。
路由一览
| 方法 | 路径 | 用途 |
|---|---|---|
POST | /api/v1/monitoring/loan/borrowers | 创建借款人 |
GET | /api/v1/monitoring/loan/borrowers/{id} | 按 UUID 读取借款人(含 PII 掩码) |
POST | /api/v1/monitoring/loan/loans | 创建贷款 |
POST | /api/v1/monitoring/loan/payments | 创建实际还款 |
GET | /api/v1/monitoring/loan/payments/{id} | 按 UUID 读取实际还款 |
PATCH | /api/v1/monitoring/loan/loans/{loanRef}/status | 将贷款变更为新状态 |
POST | /api/v1/monitoring/loan/payments/{id}/cancel | 软删除一笔还款 |
所有变更类路由都接受 Idempotency-Key 请求头和 ?dryRun=true 查询参数,并在校验失败时返回结构化的 fieldErrors 响应封装。
POST /api/v1/monitoring/loan/borrowers
在由 portfolioId 标识的投资组合中创建一个借款人。
请求
POST /api/v1/monitoring/loan/borrowers HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json
Idempotency-Key: <opaque-key>请求体:
| 字段 | 类型 | 必填 | 约束 |
|---|---|---|---|
id | UUID 字符串 | 是 | 调用方提供的平台标识符。 |
portfolioId | UUID 字符串 | 是 | 所属投资组合;必须存在于您的组织中。 |
externalId | 字符串 | 是 | 1-255 个字符;对于有效行,在 (portfolio, externalId) 范围内唯一。 |
name | string | null | 否 | 借款人全名。原样保存;面向投资者的读取会进行掩码处理。 |
email | string | null | 否 | RFC 5322 电子邮件地址;原样保存;面向投资者的读取会进行掩码处理。 |
phone | string | null | 否 | 自由格式电话号码;原样保存;面向投资者的读取会进行掩码处理。 |
nationalIdLast4 | string | null | 否 | 恰好四位数字;从不返回前面的数字。 |
countryCode | string | null | 否 | ISO-3166 两字母代码(大写)。 |
dob | date string | null | 否 | YYYY-MM-DD。 |
gender | enum | null | 否 | male | female | non_binary | other | undisclosed(不区分大小写)。 |
incomeBand | string | null | 否 | 自由格式。 |
employmentStatus | string | null | 否 | 自由格式。 |
metadata | object | null | 否 | 原样透传。 |
响应
首次写入返回 201 Created,幂等重放返回 200 OK:
{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "BORROWER-001",
"bronzeSubmissionId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789",
"reused": false
}| 状态 | 响应封装 | 触发条件 |
|---|---|---|
200 OK | { id, externalId, bronzeSubmissionId, reused: true } | Idempotency-Key 与之前的请求匹配;不会发生新的写入。 |
201 Created | { id, externalId, bronzeSubmissionId, reused: false } | 插入了新行。 |
400 Bad Request | fieldErrors | 任一请求体字段校验失败。 |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | portfolioId 不存在或属于其他组织。 |
409 Conflict | { error, code: "ID_CONFLICT", fieldErrors: [...] } | 已存在具有相同 id 的有效借款人。 |
cURL
curl -X POST https://app.waafir.io/api/v1/monitoring/loan/borrowers \
-H "Authorization: Bearer $WAAFIR_PAT" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e" \
-d '{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"externalId": "BORROWER-001",
"gender": "female",
"countryCode": "KE"
}'GET /api/v1/monitoring/loan/borrowers/{id}
按平台 UUID 读取借款人。PII 字段默认会被掩码处理;管理员可以通过 ?unmask=true 请求原始 PII,此操作会写入一条审计日志。
请求
| 参数 | 位置 | 必填 | 约束 |
|---|---|---|---|
id | path | 是 | 借款人的平台 UUID。 |
unmask | query | 否 | true 返回原始 PII;仅限管理员。默认进行掩码处理。 |
响应
200 OK,返回经掩码处理的借款人记录:
{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"externalId": "BORROWER-001",
"name": "J***",
"email": "j***@example.com",
"phone": "***-***-1234",
"nationalIdLast4": "1234",
"countryCode": "KE",
"dob": "1985-03-20",
"gender": "female",
"incomeBand": null,
"employmentStatus": null,
"metadata": {}
}| 状态 | 触发条件 |
|---|---|
200 OK | 该行存在于您的组织中。如果调用方是管理员且传入 ?unmask=true,PII 为原始值;否则 PII 会被掩码处理。 |
400 Bad Request | id 不是格式正确的 UUID。 |
404 Not Found | 该行不存在、已取消,或属于其他组织。 |
PII 掩码适用于 name、email、phone 和 nationalIdLast4。nationalIdLast4 字段在写入时就只保存后四位;读取时的掩码仍会对非管理员读取隐藏这四位。
非管理员调用方传入 ?unmask=true 不会收到 403——响应仍为 200,返回掩码后的结构,并写入一条记录该次被拒绝的去掩码尝试的审计日志。平台不将角色检查作为错误返回,因为掩码后的结构是安全的默认值;正是审计轨迹让安全团队能看到这次尝试。
管理员调用方传入 ?unmask=true 时会收到原始 PII,且该请求会另外写入一条记录此次去掩码操作的审计日志。响应带有 Cache-Control: private, no-store,以防中间节点缓存包含原始 PII 的载荷。
POST /api/v1/monitoring/loan/loans
针对同一投资组合中已存在的借款人创建一笔贷款。
请求
| 字段 | 类型 | 必填 | 约束 |
|---|---|---|---|
id | UUID 字符串 | 是 | 调用方提供的平台标识符。 |
portfolioId | UUID 字符串 | 是 | 所属投资组合。 |
borrowerId | UUID 字符串 | 是 | 同一投资组合中的一个有效借款人。 |
externalId | 字符串 | 是 | 1-255 个字符;对于有效行,在投资组合内唯一。 |
predecessorLoanId | UUID string | null | 否 | 在重组时设置;指向被替换的贷款。 |
principalAmount | 十进制字符串 | 是 | 最多四位小数。 |
currencyCode | 字符串 | 是 | ISO-4217 三字母代码;不区分大小写。 |
interestRateApr | 十进制字符串 | 是 | 最多六位小数;必须 >= 0。 |
disbursementDate | 日期字符串 | 是 | YYYY-MM-DD。 |
termMonths | 整数 | 是 | 必须 > 0。 |
repaymentFrequency | enum | 是 | monthly | weekly | biweekly | quarterly | bullet(不区分大小写)。 |
productType | string | null | 否 | 自由格式,例如 "Term loan"、"Overdraft"。 |
status | enum | 是 | pending | active | paid_off | restructured | written_off | defaulted(不区分大小写)。 |
metadata | object | null | 否 | 原样透传。 |
响应
201 Created(幂等重放时为 200 OK),返回 { id, externalId, bronzeSubmissionId, reused }。
| 状态 | 响应封装 | 触发条件 |
|---|---|---|
200 OK | { ..., reused: true } | 幂等重放。 |
201 Created | { ..., reused: false } | 插入了新贷款。 |
400 Bad Request | fieldErrors | 校验失败(例如 interestRateApr 为负数、currencyCode 格式错误)。 |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | 投资组合不存在或跨组织。 |
409 Conflict | { error, code: "ID_CONFLICT" } | 已存在具有相同 id 的有效贷款。 |
422 Unprocessable Entity | { error, code: "REFERENCED_ENTITY_NOT_FOUND", fieldErrors: [{ path: "borrowerId", ... }] } | borrowerId 未能解析为同一投资组合中的有效借款人。 |
cURL
curl -X POST https://app.waafir.io/api/v1/monitoring/loan/loans \
-H "Authorization: Bearer $WAAFIR_PAT" \
-H "Content-Type: application/json" \
-d '{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"borrowerId": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "LOAN-001",
"principalAmount": "10000.00",
"currencyCode": "USD",
"interestRateApr": "0.18",
"disbursementDate": "2026-01-15",
"termMonths": 12,
"repaymentFrequency": "monthly",
"status": "active"
}'POST /api/v1/monitoring/loan/payments
针对已存在的贷款记录一笔实际还款。用于已收还款、部分还款和核销。重组应建模为设置了 predecessorLoanId 的新贷款,而不是一笔还款。
请求
| 字段 | 类型 | 必填 | 约束 |
|---|---|---|---|
id | UUID 字符串 | 是 | 调用方提供的平台标识符。 |
portfolioId | UUID 字符串 | 是 | 所属投资组合。 |
loanId | UUID 字符串 | 是 | 同一投资组合中的一笔有效贷款。 |
externalId | 字符串 | 是 | 1-255 个字符;对于有效行,在投资组合内唯一。 |
paymentDate | 日期字符串 | 是 | YYYY-MM-DD。 |
amount | 十进制字符串 | 是 | 收到的还款总额。 |
currencyCode | 字符串 | 是 | ISO-4217。 |
principalPaid | 十进制字符串 | 否 | 默认为 "0"。 |
interestPaid | 十进制字符串 | 否 | 默认为 "0"。 |
feesPaid | 十进制字符串 | 否 | 默认为 "0"。 |
writeOffAmount | 十进制字符串 | 否 | 默认为 "0"。参见下文的豁免规则。 |
paymentNotes | string | null | 否 | 当 writeOffAmount > 0 时必须为 "Forgiven"(不区分大小写)。 |
paymentMethod | enum | null | 否 | cash | bank_transfer | card | mobile_money | check | other。 |
metadata | object | null | 否 | 原样透传。 |
豁免规则。 如果 writeOffAmount > 0,则 paymentNotes 必须等于 "Forgiven"(不区分大小写)。平台在 API 边界处就会使请求失败,因此错误的还款会在记录任何内容之前被拒绝。
响应
201 Created(幂等重放时为 200 OK),返回 { id, externalId, bronzeSubmissionId, reused }。
| 状态 | 响应封装 | 触发条件 |
|---|---|---|
200 OK | { ..., reused: true } | 幂等重放。 |
201 Created | { ..., reused: false } | 插入了新还款。 |
400 Bad Request | fieldErrors | 校验失败(金额格式错误、枚举未匹配、缺少必填字段)。 |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | 投资组合不存在或跨组织。 |
409 Conflict | { error, code: "ID_CONFLICT" } | 已存在具有相同 id 的有效还款。 |
422 Unprocessable Entity | { error, code: "REFERENCED_ENTITY_NOT_FOUND", fieldErrors: [{ path: "loanId", ... }] } | loanId 未能解析为同一投资组合中的有效贷款。 |
400 Bad Request | { error, code: "CHECK_VIOLATION", fieldErrors: [...] } | 存储还款时豁免规则被拒绝(罕见;校验会先拒绝相同的结构)。 |
GET /api/v1/monitoring/loan/payments/{id}
按平台 UUID 读取一笔实际还款,包括已取消(软删除)的行。可用于核验写入或查看已取消的记录。
请求
| 参数 | 位置 | 必填 | 约束 |
|---|---|---|---|
id | path | 是 | 还款的平台 UUID。 |
响应
200 OK,返回完整的还款记录。已取消的行会填充 deletedAt;有效行的 deletedAt: null。跨组织或未知 UUID 返回 404 Not Found。如果 id 不是格式正确的 UUID,返回 400 Bad Request。
PATCH /api/v1/monitoring/loan/loans/{loanRef}/status
将贷款变更为新状态。{loanRef} 路径段既接受贷款的平台 UUID,也接受其 externalId。传入 externalId 时,还必须提供 ?portfolioId=<UUID>,因为外部 ID 在不同投资组合之间并不唯一。
请求
PATCH /api/v1/monitoring/loan/loans/LOAN-001/status?portfolioId=ddf63d12-1234-5678-9abc-def012345678 HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json
Idempotency-Key: <opaque-key>请求体:
| 字段 | 类型 | 必填 | 约束 |
|---|---|---|---|
status | enum | 是 | active | paid_off | defaulted | written_off | restructured 之一(不区分大小写)。 |
effectiveDate | 日期字符串 | 是 | YYYY-MM-DD。 |
reason | string | null | 否 | 1-500 个字符;记录在审计日志中。 |
状态变更矩阵
平台强制执行状态变更矩阵;无效的变更会返回 422 INVALID_STATUS_TRANSITION,其 fieldErrors 会指明变更前后的状态。
| 原状态 | 允许的目标状态 |
|---|---|
pending | active |
active | paid_off, defaulted, written_off, restructured |
paid_off | (终态) |
defaulted | written_off, restructured |
written_off | (终态) |
restructured | (终态) |
将贷款变更为 restructured 后,自然的后续步骤是为替换贷款执行一次 POST /loans,并设置 predecessorLoanId。这两次写入有意设计为非原子操作——如果替换贷款的 POST 失败,原贷款将保持 restructured 状态,下次查询时对账接口会暴露这一偏差。
响应
成功时返回 200 OK:
{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"externalId": "LOAN-001",
"status": "restructured",
"bronzeSubmissionId": "9d8c7b6a-5432-1098-7654-321098765432",
"reused": false
}| 状态 | 响应封装 | 触发条件 |
|---|---|---|
200 OK | { id, externalId, status, bronzeSubmissionId, reused } | 已应用变更(或幂等重放,此时 reused: true)。 |
400 Bad Request | fieldErrors | 请求体校验失败、按 externalId 查找时缺少 portfolioId、枚举格式错误。 |
404 Not Found | { error, code: "NOT_FOUND" } | 按 UUID 未找到贷款,或 (portfolioId, externalId) 无法解析。 |
422 Unprocessable Entity | { error, code: "INVALID_STATUS_TRANSITION", fieldErrors: [...] } | 变更前后的状态组合不在变更矩阵中;fieldErrors[].message 会列出允许的目标状态。 |
409 Conflict | { error, code: "IDEMPOTENCY_CONFLICT" } | 该 Idempotency-Key 已用于另一次状态变更。先前的写入保持有效;请使用新密钥发送新的状态变更。 |
您提供的 effectiveDate 会随提交一起记录,并写入审计日志;它不会出现在响应体中。此路由有意不接受 metadata——状态变更本身就是审计事件,而可选的 reason 字段承载便于阅读的上下文说明。
POST /api/v1/monitoring/loan/payments/{id}/cancel
软删除一笔先前记录的还款。取消端点是贷款领域唯一的冲销接口——没有 PATCH /loans/{id}/adjust,今后也不会有。
请求
POST /api/v1/monitoring/loan/payments/7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f/cancel HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json请求体(可选):
| 字段 | 类型 | 必填 | 约束 |
|---|---|---|---|
reason | string | null | 否 | 1-500 个字符;记录在取消审计事件中。 |
接受空请求体;您也可以完全省略 Content-Type 请求头。
响应
成功时返回 200 OK:
{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"deletedAt": "2026-03-15T11:02:33Z",
"bronzeSubmissionId": "9d8c7b6a-5432-1098-7654-321098765432",
"reused": false,
"alreadyCancelled": false
}对同一笔还款第二次调用时,响应结构完全相同,只是 alreadyCancelled: true,且 deletedAt 为最初的取消时间戳。reused 标志反映幂等状态,而 alreadyCancelled 反映该行是否被本次调用修改。
| 状态 | 响应封装 | 触发条件 |
|---|---|---|
200 OK | { id, deletedAt, bronzeSubmissionId, reused, alreadyCancelled } | 首次或后续取消。 |
400 Bad Request | fieldErrors | id 不是格式正确的 UUID,或 reason 超过 500 个字符。 |
404 Not Found | { error, code: "NOT_FOUND" } | 还款不存在或属于其他组织。 |
每次取消(包括第二次)都会写入一条提交记录,以保证审计完整性。该行只会在第一次调用时被修改。
软删除与 externalId 复用
已取消的还款会让其 externalId 可在今后的写入中复用,因为唯一性约束只适用于有效行。要更正错误的提交,标准做法是:
- 对原始行调用
POST /api/v1/monitoring/loan/payments/{id}/cancel。 - 调用
POST /api/v1/monitoring/loan/payments,以更正后的字段创建新行。您可以复用相同的externalId;但必须提供不同的id。
这是有意为之:取消是非破坏性的(原始行会保留以供审计),而复用 externalId 能让业务侧的调用方 ID 空间保持连续,便于对账。