批量 NDJSON
批量 NDJSON 接口在单个同步 HTTP 请求中最多接受一万行,按照与单条记录路由相同的 schema 对每行进行校验,并返回行级错误报告。它适用于能轻松放入一个 HTTP 请求的日终批次;历史数据加载或更大的批次请使用异步导入。
传输格式为换行分隔的 JSON:每行一个有效的 JSON 对象,没有尾随逗号,没有外层数组,也没有起止封装。对象之间的空行会被接受并跳过。
路由
每个实体对应一个路由。每行所应用的 schema 与 URL 中的实体一致。
| 方法 | 路径 | 实体 |
|---|---|---|
POST | /api/v1/monitoring/loan/bulk/borrowers | borrower |
POST | /api/v1/monitoring/loan/bulk/loans | loan |
POST | /api/v1/monitoring/loan/bulk/scheduled-repayments | scheduled_repayment |
POST | /api/v1/monitoring/loan/bulk/actual-payments | actual_payment |
POST | /api/v1/monitoring/loan/bulk/collateral | collateral |
POST | /api/v1/monitoring/loan/bulk/collateral-valuations | collateral_valuation |
请求体中的每一行都必须是有效的 JSON 对象,并满足单条记录页面中记录的该实体 schema。两者的 schema 完全相同;只是传输封装不同。
请求
POST /api/v1/monitoring/loan/bulk/loans HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/x-ndjson
Idempotency-Key: <opaque-key>请求头和查询参数:
| 名称 | 位置 | 必填 | 说明 |
|---|---|---|---|
Authorization | header | 是 | Bearer PAT。 |
Content-Type | header | 否 | 推荐 application/x-ndjson;也接受 application/json。 |
Idempotency-Key | header | 否 | 强烈建议在生产批次中使用。 |
?dryRun=true | query | 否 | 执行校验,跳过写入。 |
?portfolioId=<UUID> | query | 是 | 该批次的租户锚点;缺失或格式错误时返回 400 portfolio_id_required。 |
批量接口只从查询字符串中读取 portfolioId;在批次封装层,各行请求体中的同名字段会被忽略。请求体中的每一行都必须引用同一个投资组合。
请求体就是 NDJSON 载荷本身——UTF-8 编码,以单个换行符结尾。超过一万行或大于十兆字节的请求体会被拒绝——参见大小上限。
逐行约定
每一行都根据实体 schema 独立校验。每行适用的规则与单条记录写入相同:
- 每一行都必须带有自己的
idUUID 和portfolioId。 调用方提供的 ID 是逐行去重的键。 - 整个批次共用请求级的
Idempotency-Key。 参见下文的幂等性。 metadata按行提供。 每行可以携带自己的透传元数据;平台会原样持久化。- 币种、日期、枚举和金额规则与单条记录相同。校验失败的行会作为逐行错误报告中的一个条目出现,其
code: "validation_failed"。
校验失败的行不会中止整个批次——失败会作为 errors[] 中的一个条目出现,其余行继续处理。
响应
只要请求本身能被解析,无论有多少行成功或失败,每个批次都会返回 200 OK。响应体中包含完整的逐行报告:
{
"totalRows": 4,
"succeeded": 3,
"failed": 1,
"bronzeSubmissionId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789",
"reused": false,
"errors": [
{
"rowNumber": 2,
"code": "fk_violation",
"message": "borrowerId references a borrower that does not exist in this portfolio"
}
]
}| 字段 | 类型 | 说明 |
|---|---|---|
totalRows | integer | 请求体中非空行的数量。 |
succeeded | integer | 已存储的行数。 |
failed | integer | totalRows - succeeded。 |
bronzeSubmissionId | UUID | 整个 NDJSON 请求体对应的那一条提交记录的 id。?dryRun=true 的响应中不包含此字段。 |
reused | boolean | 仅当 Idempotency-Key 与先前的批次匹配且响应是重建的时,才出现且为 true;否则不出现。 |
dryRun | boolean | 仅在 ?dryRun=true 的响应中出现且为 true;否则不出现。 |
errors[].rowNumber | integer | 请求体中从 1 开始的行号。 |
errors[].code | enum | validation_failed | unique_violation | fk_violation | check_violation | db_error。 |
errors[].message | string | 便于阅读的摘要;对于 validation_failed,校验错误会合并为一句话。 |
逐行错误结构只包含 rowNumber、code 和 message。没有逐行的 fieldErrors 数组,也没有逐行的 rawRow——原始 NDJSON 原样保存在提交记录中,而不会在响应中回显。
succeeded 为 0 并不是错误响应——批次已被解析,平台处理了每一行;报告告诉您没有任何数据落库。真正失败的批次(整个请求体的 NDJSON 格式错误、请求体过大、投资组合未知)会按下表返回 4xx。
状态码
此接口的顶层错误响应封装使用小写的 code 值,与单条记录路由使用的大写代码不同。两套代码空间有意保持独立。
| 状态 | 响应封装 | 触发条件 |
|---|---|---|
200 OK | 逐行报告 | 批次已处理;逐行结果见 errors[]。 |
400 Bad Request | { error, code: "invalid_body", errors: [...] } | 无法将请求体读取为文本。 |
400 Bad Request | { error, code: "portfolio_id_required", fieldErrors: [...] } | ?portfolioId=<UUID> 缺失或不是有效的 UUID。 |
400 Bad Request | { error, code: "invalid_json" } | 以逐行方式嵌入逐行报告中——不是有效 JSON 的行会在 errors[] 中得到一个 code: "invalid_json" 条目。整个批次仍返回 200。 |
404 Not Found | { error, code: "portfolio_not_found", fieldErrors: [...] } | ?portfolioId= 在您的组织中不作为有效投资组合存在。 |
413 Payload Too Large | { error, code: "batch_too_large", fieldErrors: [...] } | 参见大小上限。 |
大小上限
批量接口对载荷的上限取以下两者中较小者:
- 一万个非空行。 超出部分的行会在处理开始之前被拒绝。
- 十兆字节的请求体。
超过任一上限的请求会收到 413 Payload Too Large:
{
"error": "batch payload exceeds 10485760 bytes; use the async import endpoint at /api/v1/monitoring/loan/imports",
"code": "batch_too_large",
"fieldErrors": [{ "path": "(body)", "message": "max 10485760 bytes" }]
}字节上限和行数上限的响应封装都使用 code: "batch_too_large";通过 error 和 fieldErrors[].message 区分触发原因。标准的恢复方式是将同一载荷改走异步导入流程,该流程直接上传文件并异步处理,没有行数上限。
幂等性
批量接口在批次封装层面按 Idempotency-Key 去重。具体机制如下:
- 首次使用键
K调用。 请求体作为一条提交记录保存,每一行都被处理,逐行报告随该提交一并保存。 - 第二次使用键
K调用,请求体相同。 不会产生第二条记录,也不会重复插入。平台返回原始报告,并带有reused: true。 - 第二次使用键
K调用,请求体不同。 平台仍返回原始报告——原始提交才是权威依据。用更正后的请求体重新 POST 时必须使用不同的键。
这意味着客户端在网络抖动后重试是安全的,即使第二次请求的请求体在传输中被截断或修改——平台会返回第一次成功处理时的行级结果。
提交记录
每个批量请求都记录为一条包含整个 NDJSON 请求体的提交,而不是每行一条。重试的行永远不会被存储两次,因为 externalId 在投资组合内的有效行之间唯一。
响应中的 bronzeSubmissionId 是提交记录的 id;请将其与您本地的提交记录一起保存,以便审计和对账。
cURL 示例
cat <<'EOF' > batch.ndjson
{"id":"a1...","portfolioId":"ddf63d12-1234-5678-9abc-def012345678","borrowerId":"b1...","externalId":"L-001","principalAmount":"5000","currencyCode":"USD","interestRateApr":"0.18","disbursementDate":"2026-01-15","termMonths":12,"repaymentFrequency":"monthly","status":"active"}
{"id":"a2...","portfolioId":"ddf63d12-1234-5678-9abc-def012345678","borrowerId":"b2...","externalId":"L-002","principalAmount":"3000","currencyCode":"USD","interestRateApr":"0.20","disbursementDate":"2026-01-15","termMonths":24,"repaymentFrequency":"monthly","status":"active"}
{"id":"a3...","portfolioId":"ddf63d12-1234-5678-9abc-def012345678","borrowerId":"b3...","externalId":"L-003","principalAmount":"7500","currencyCode":"USD","interestRateApr":"0.22","disbursementDate":"2026-01-15","termMonths":18,"repaymentFrequency":"monthly","status":"active"}
EOF
curl -X POST "https://app.waafir.io/api/v1/monitoring/loan/bulk/loans?portfolioId=ddf63d12-1234-5678-9abc-def012345678" \
-H "Authorization: Bearer $WAAFIR_PAT" \
-H "Content-Type: application/x-ndjson" \
-H "Idempotency-Key: nightly-2026-01-15-loans" \
--data-binary @batch.ndjson如何在批量 NDJSON 与异步导入之间选择
以下情况请选择批量 NDJSON:
- 您的批次不超过一万行和十兆字节。
- 您希望在 HTTP 响应中立即获得逐行报告。
- 您可以接受耗时较长的 HTTP 请求——批量批次通常在几秒内完成,但包含大量数据库外键查找的大批次可能耗时更长。
以下情况请选择异步导入:
- 您的批次超过任一大小上限。
- 您要加载还款、计划还款或借款人的历史存档——典型的历史数据加载可达数百万行。
- 您希望保留取消进行中加载的选项。