异步导入
异步导入接口适用于历史数据加载,以及任何超过批量 NDJSON一万行或十兆字节上限的批次。该流程分为两个阶段:您先描述要上传的内容,获得一个有时效的上传 URL,将文件直接 PUT 到该 URL,然后请求平台提交(commit)该文件。之后,一个 worker 逐行流式处理文件,记录逐行错误,并通过状态端点报告进度。
此处列出的路由是进入导入流程的贷款领域入口。
生命周期
生命周期包含七种状态。大多数生产加载会经历 pending_upload → queued → processing → succeeded;其他状态用于体现各种失败情形。
| 状态 | 含义 |
|---|---|
pending_upload | 导入记录已存在;有时效的上传 URL 有效;平台尚未看到文件。 |
queued | 提交成功;worker 尚未领取该文件。 |
processing | worker 正在逐行流式处理文件。 |
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 文件时必须原样附带的上传请求头。
请求体
| 字段 | 类型 | 必填 | 约束 |
|---|---|---|---|
kind | enum | 是 | 六种类型之一。 |
filename | string | 是 | 1-255 个字符;仅用于显示。 |
sizeBytes | integer | 是 | 正整数;与您打算上传的文件大小一致。 |
portfolioId | UUID string | null | 否 | 可选的覆盖值;请求体中的各行仍携带各自的值。 |
idempotencyKey | string | null | 否 | 优先使用请求头;请求体字段作为备用。 |
dryRun | boolean | 否 | true 时执行校验但不加入队列。 |
metadata | object | null | 否 | 原样透传。 |
rowCountDeclared | integer | 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 Request | errors[](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}
读取导入的当前状态、计数和错误摘要。这是客户端为监控进度而调用的轮询端点。
请求
| 参数 | 位置 | 必填 | 说明 |
|---|---|---|---|
id | path | 是 | 导入的平台 UUID。 |
errors | query | 否 | 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
列出调用方的贷款导入,最新的排在最前。
请求
| 参数 | 位置 | 必填 | 约束 |
|---|---|---|---|
status | query | 否 | 七种生命周期状态之一。 |
kind | query | 否 | 六种贷款类型之一。 |
limit | query | 否 | 1-100;默认 20。 |
offset | query | 否 | 非负数;默认 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 |
|---|---|---|
borrower | borrowers | 与 POST /borrowers 相同。 |
loan | loans | 与 POST /loans 相同。 |
scheduled_repayment | scheduled_repayments | 计划还款 schema。 |
actual_payment | actual_payments | 与 POST /payments 相同。 |
collateral | collateral | 抵押品 schema。 |
collateral_valuation | collateral_valuations | 抵押品估值 schema。 |
不在此列表中的 kind 会返回 400 UNKNOWN_KIND,响应中会列出允许的值,因此拼写错误无需反复试错即可纠正。
何时使用此接口
以下情况请使用异步导入:
- 您要加载历史存档——典型的历史数据加载可达数百万行。
- 您的批次超过批量 NDJSON 的任一上限(10 000 行或 10 MB)。
- 您希望能在加载中途取消——批量 NDJSON 没有取消接口,因为请求本身就是加载过程。
- 您的客户端可以接受轮询——导入完成时不会推送通知。
对于能放入单个同步请求的小型业务批次,批量 NDJSON 是更简单的方式。