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

异步导入

异步导入接口适用于历史数据加载,以及任何超过批量 NDJSON一万行或十兆字节上限的批次。该流程分为两个阶段:您先描述要上传的内容,获得一个有时效的上传 URL,将文件直接 PUT 到该 URL,然后请求平台提交(commit)该文件。之后,一个 worker 逐行流式处理文件,记录逐行错误,并通过状态端点报告进度。

此处列出的路由是进入导入流程的贷款领域入口。

生命周期

生命周期包含七种状态。大多数生产加载会经历 pending_upload → queued → processing → succeeded;其他状态用于体现各种失败情形。

状态含义
pending_upload导入记录已存在;有时效的上传 URL 有效;平台尚未看到文件。
queued提交成功;worker 尚未领取该文件。
processingworker 正在逐行流式处理文件。
succeeded每一行都已存储。
partial文件已全部处理,但至少有一行失败。
failed致命错误导致处理在完成前中止(例如 gzip 格式错误、上传的文件缺失、worker 内部错误)。
cancelled调用方取消了导入;worker 在下一个分块边界处停止。

一直停留在 pending_upload 的记录表示已签发但从未提交的上传 URL;这些记录会在 URL 的 TTL 过期后被定期回收。

路由一览

方法路径用途
POST/api/v1/monitoring/loan/imports发起新的导入;获取有时效的上传 URL。
POST/api/v1/monitoring/loan/imports/{id}/commit完成上传,将 worker 任务加入队列。
GET/api/v1/monitoring/loan/imports/{id}读取状态、计数和错误摘要。
GET/api/v1/monitoring/loan/imports/{id}?errors=true分页浏览逐行错误。
GET/api/v1/monitoring/loan/imports列出调用方的贷款导入。
DELETE/api/v1/monitoring/loan/imports/{id}取消进行中的导入。

POST /api/v1/monitoring/loan/imports

发起新的导入。返回导入 id、有时效的上传 URL,以及客户端 PUT 文件时必须原样附带的上传请求头。

请求体

字段类型必填约束
kindenum是六种类型之一。
filenamestring是1-255 个字符;仅用于显示。
sizeBytesinteger是正整数;与您打算上传的文件大小一致。
portfolioIdUUID string | null否可选的覆盖值;请求体中的各行仍携带各自的值。
idempotencyKeystring | null否优先使用请求头;请求体字段作为备用。
dryRunboolean否true 时执行校验但不加入队列。
metadataobject | null否原样透传。
rowCountDeclaredinteger | null否仅供参考——可改善进度报告。

两者同时提供时,Idempotency-Key HTTP 请求头优先于请求体字段。

响应——202 Accepted

{
  "importId": "1234abcd-5678-90ef-1234-567890abcdef",
  "uploadUrl": "https://<upload-host>/...?<signature>",
  "headers": { "<header-name>": "<header-value>" },
  "s3Key": "imports/abc.../...",
  "reused": false,
  "statusUrl": "/api/v1/monitoring/loan/imports/1234abcd-5678-90ef-1234-567890abcdef",
  "commitUrl": "/api/v1/monitoring/loan/imports/1234abcd-5678-90ef-1234-567890abcdef/commit"
}
字段说明
importId您在后续每次调用中引用的平台标识符。
uploadUrl用于 PUT 上传的有时效 URL。
headers您的 PUT 必须包含的 HTTP 请求头映射。
s3Key文件存放的存储键。
reused如果该响应是先前 Idempotency-Key 的去重结果,则为 true。
statusUrl / commitUrl为后续生命周期提供的便捷 URL。

状态码

状态响应封装触发条件
202 Accepted如上已创建导入记录。
400 Bad Requesterrors[](path/message)请求体校验失败。
400 Bad Request{ error, code: "UNKNOWN_KIND", allowed: [...] }kind 不是六种贷款类型之一。
409 Conflict{ error, code: "IDEMPOTENCY_KEY_REUSED", importId, mismatchedFields }该 Idempotency-Key 已用于参数不同的导入。

上传文件

拿到 uploadUrl 后,将文件直接 PUT 到该 URL。请原样附带响应中 headers 映射的每一个请求头;URL 上的签名覆盖了这些请求头,否则上传会被拒绝。

curl -X PUT "$UPLOAD_URL" \
  -H "<header-name>: <header-value>" \
  --data-binary @your-file.ndjson

上传直接进入存储,不经过 API。文件格式与批量 NDJSON 页面中记录的 NDJSON 传输格式相同,但没有行数上限。

POST /api/v1/monitoring/loan/imports/{id}/commit

PUT 完成后,调用 commit 告知平台上传已完成。平台会确认文件存在,将导入记录从 pending_upload 切换为 queued,并将 worker 任务加入队列。

请求

无请求体。Idempotency-Key 是隐式的——对非 pending_upload 状态的记录再次提交不会产生任何操作,只返回当前状态。

响应

200 OK:

{ "importId": "1234abcd-...", "status": "queued" }
状态响应封装触发条件
200 OK{ importId, status }提交成功,或该记录已越过 pending_upload(幂等)。
404 Not Found标准导入不存在或属于其他组织。
409 Conflict{ error, code: "COMMIT_FAILED" }平台找不到上传的文件——通常是上传从未发生或尚未完成。请在上传完成后重试提交。

GET /api/v1/monitoring/loan/imports/{id}

读取导入的当前状态、计数和错误摘要。这是客户端为监控进度而调用的轮询端点。

请求

参数位置必填说明
idpath是导入的平台 UUID。
errorsquery否true 时切换到错误分页模式(见下文)。

响应——默认模式

{
  "importId": "1234abcd-...",
  "kind": "actual_payment",
  "domain": "loan",
  "status": "succeeded",
  "filename": "payments-2025-full-year.ndjson",
  "sizeBytes": 524288000,
  "portfolioId": "ddf63d12-...",
  "rowCountDeclared": 1500000,
  "rowCountProcessed": 1500000,
  "rowCountSucceeded": 1499987,
  "rowCountFailed": 13,
  "createdAt": "2026-05-20T10:00:00Z",
  "startedAt": "2026-05-20T10:00:15Z",
  "completedAt": "2026-05-20T10:18:42Z",
  "dryRun": false,
  "errorSummary": {
    "totals": { "validation_error": 9, "fk_violation": 4 },
    "samples": [
      { "rowNumber": 12, "errorCode": "validation_error", "errorMessage": "..." },
      { "rowNumber": 1041, "errorCode": "fk_violation", "errorMessage": "..." }
    ]
  }
}

errorSummary 是一个小型内嵌摘要——按错误代码统计的总数,以及最多十个示例行。如需完整的逐行列表,请切换到错误分页模式。

响应——?errors=true&limit=&offset=

{
  "items": [
    {
      "rowNumber": 12,
      "errorCode": "validation_error",
      "errorMessage": "interestRateApr must be >= 0",
      "rawRow": "{\"id\":\"...\",\"interestRateApr\":\"-0.05\",...}",
      "createdAt": "2026-05-20T10:01:14Z"
    }
  ],
  "limit": 20,
  "offset": 0
}
字段说明
rowNumber上传的 NDJSON 中从 1 开始的行号。
errorCode常见值包括 parse_error(该行不是有效 JSON)、validation_error(schema 拒绝了该行)、portfolio_mismatch(该行的 portfolioId 与导入的锚点不一致)以及 processor_error(处理程序意外失败)。完整列表请参见错误与状态码。
errorMessage便于阅读的失败摘要。
rawRow原始 NDJSON 行,原样保留以便调试。

limit 默认为 20,最大为 100。offset 默认为 0。分页按 rowNumber 顺序遍历已保存的错误列表,因此稳定的游标是 offset += limit。

状态码

状态触发条件
200 OK该记录存在于您的组织中。
400 Bad Request在 ?errors=true 时 limit 或 offset 格式错误。
404 Not Found未找到记录或跨组织。

GET /api/v1/monitoring/loan/imports

列出调用方的贷款导入,最新的排在最前。

请求

参数位置必填约束
statusquery否七种生命周期状态之一。
kindquery否六种贷款类型之一。
limitquery否1-100;默认 20。
offsetquery否非负数;默认 0。

响应

{
  "items": [
    {
      "importId": "...",
      "kind": "actual_payment",
      "status": "succeeded",
      "filename": "...",
      "createdAt": "...",
      "completedAt": "...",
      "rowCountSucceeded": 1499987,
      "rowCountFailed": 13
    }
  ],
  "limit": 20,
  "offset": 0
}

DELETE /api/v1/monitoring/loan/imports/{id}

取消进行中的导入。worker 会在下一个分块边界处停止;已存储的行会保留。取消已处于终态的记录(succeeded、partial、failed 或 cancelled)不会产生任何操作,只返回现有状态。

响应

200 OK:

{ "importId": "1234abcd-...", "status": "cancelled" }
状态触发条件
200 OK已应用取消,或记录已处于终态。
404 Not Found未找到记录或跨组织。

类型

发起请求中的 kind 字段决定了每一行依据哪个 schema 进行校验,以及由哪个实体接收这些行。六种类型与实体一一对应:

类型实体Schema
borrowerborrowers与 POST /borrowers 相同。
loanloans与 POST /loans 相同。
scheduled_repaymentscheduled_repayments计划还款 schema。
actual_paymentactual_payments与 POST /payments 相同。
collateralcollateral抵押品 schema。
collateral_valuationcollateral_valuations抵押品估值 schema。

不在此列表中的 kind 会返回 400 UNKNOWN_KIND,响应中会列出允许的值,因此拼写错误无需反复试错即可纠正。

何时使用此接口

以下情况请使用异步导入:

  • 您要加载历史存档——典型的历史数据加载可达数百万行。
  • 您的批次超过批量 NDJSON 的任一上限(10 000 行或 10 MB)。
  • 您希望能在加载中途取消——批量 NDJSON 没有取消接口,因为请求本身就是加载过程。
  • 您的客户端可以接受轮询——导入完成时不会推送通知。

对于能放入单个同步请求的小型业务批次,批量 NDJSON 是更简单的方式。