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

批量 NDJSON

批量 NDJSON 接口在单个同步 HTTP 请求中最多接受一万行,按照与单条记录路由相同的 schema 对每行进行校验,并返回行级错误报告。它适用于能轻松放入一个 HTTP 请求的日终批次;历史数据加载或更大的批次请使用异步导入。

传输格式为换行分隔的 JSON:每行一个有效的 JSON 对象,没有尾随逗号,没有外层数组,也没有起止封装。对象之间的空行会被接受并跳过。

路由

每个实体对应一个路由。每行所应用的 schema 与 URL 中的实体一致。

方法路径实体
POST/api/v1/monitoring/loan/bulk/borrowersborrower
POST/api/v1/monitoring/loan/bulk/loansloan
POST/api/v1/monitoring/loan/bulk/scheduled-repaymentsscheduled_repayment
POST/api/v1/monitoring/loan/bulk/actual-paymentsactual_payment
POST/api/v1/monitoring/loan/bulk/collateralcollateral
POST/api/v1/monitoring/loan/bulk/collateral-valuationscollateral_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>

请求头和查询参数:

名称位置必填说明
Authorizationheader是Bearer PAT。
Content-Typeheader否推荐 application/x-ndjson;也接受 application/json。
Idempotency-Keyheader否强烈建议在生产批次中使用。
?dryRun=truequery否执行校验,跳过写入。
?portfolioId=<UUID>query是该批次的租户锚点;缺失或格式错误时返回 400 portfolio_id_required。

批量接口只从查询字符串中读取 portfolioId;在批次封装层,各行请求体中的同名字段会被忽略。请求体中的每一行都必须引用同一个投资组合。

请求体就是 NDJSON 载荷本身——UTF-8 编码,以单个换行符结尾。超过一万行或大于十兆字节的请求体会被拒绝——参见大小上限。

逐行约定

每一行都根据实体 schema 独立校验。每行适用的规则与单条记录写入相同:

  • 每一行都必须带有自己的 id UUID 和 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"
    }
  ]
}
字段类型说明
totalRowsinteger请求体中非空行的数量。
succeededinteger已存储的行数。
failedintegertotalRows - succeeded。
bronzeSubmissionIdUUID整个 NDJSON 请求体对应的那一条提交记录的 id。?dryRun=true 的响应中不包含此字段。
reusedboolean仅当 Idempotency-Key 与先前的批次匹配且响应是重建的时,才出现且为 true;否则不出现。
dryRunboolean仅在 ?dryRun=true 的响应中出现且为 true;否则不出现。
errors[].rowNumberinteger请求体中从 1 开始的行号。
errors[].codeenumvalidation_failed | unique_violation | fk_violation | check_violation | db_error。
errors[].messagestring便于阅读的摘要;对于 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 请求——批量批次通常在几秒内完成,但包含大量数据库外键查找的大批次可能耗时更长。

以下情况请选择异步导入:

  • 您的批次超过任一大小上限。
  • 您要加载还款、计划还款或借款人的历史存档——典型的历史数据加载可达数百万行。
  • 您希望保留取消进行中加载的选项。