非同期インポート
非同期インポートインターフェースは、過去データのロードや、一括 NDJSON の 1 万行または 10 メガバイトの上限を超えるバッチのための経路です。フローは 2 段階です。アップロードする内容を申告し、有効期限付きのアップロード URL を受け取り、そこへファイルを直接 PUT してから、プラットフォームにコミットを依頼します。その後はワーカーがファイルを 1 行ずつストリーミング処理し、行ごとのエラーを記録しながら、ステータスエンドポイントを通じて進捗を報告します。
ここで紹介するルートは、インポートフローへのローン領域の入口です。
ライフサイクル
ライフサイクルには 7 つの状態があります。本番のロードの多くは pending_upload → queued → processing → succeeded をたどります。それ以外の状態は失敗のパターンを表します。
| 状態 | 意味 |
|---|---|
pending_upload | インポートの行が存在し、有効期限付きのアップロード URL が有効です。プラットフォームはまだファイルを確認していません。 |
queued | コミットが成功しました。ワーカーはまだファイルを取得していません。 |
processing | ワーカーがファイルを 1 行ずつストリーミング処理しています。 |
succeeded | すべての行が保存されました。 |
partial | ファイルはすべて処理されましたが、少なくとも 1 行が失敗しました。 |
failed | 致命的なエラーにより、完了前に処理が停止しました(例:gzip の形式不正、アップロードされたファイルの欠落、ワーカーの内部エラー)。 |
cancelled | 呼び出し元がインポートを取り消しました。ワーカーは次のチャンク境界で停止しました。 |
pending_upload から先に進まない行は、発行されたもののコミットされなかったアップロード URL を表します。これらは URL の TTL が切れた後、定期的にガベージコレクションされます。
ルート一覧
| メソッド | パス | 用途 |
|---|---|---|
POST | /api/v1/monitoring/loan/imports | 新しいインポートを開始し、有効期限付きのアップロード URL を受け取ります。 |
POST | /api/v1/monitoring/loan/imports/{id}/commit | アップロードを確定し、ワーカーをキューに投入します。 |
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 | はい | 6 つの種類のいずれか。 |
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 が 6 つのローン種類のいずれでもありません。 |
409 Conflict | { error, code: "IDEMPOTENCY_KEY_REUSED", importId, mismatchedFields } | Idempotency-Key が、異なるパラメーターのインポートですでに使用されています。 |
ファイルのアップロード
uploadUrl を取得したら、そこへファイルを直接 PUT します。レスポンスの 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 に切り替え、ワーカーをキューに投入します。
リクエスト
ボディはありません。Idempotency-Key は暗黙的に適用されます。pending_upload 以外の行に対する 2 回目のコミットは何も行わず、現在の状態を返します。
レスポンス
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 は、エラーコードごとの合計と最大 10 件のサンプル行からなる小さな埋め込み要約です。行ごとの完全な一覧が必要な場合は、エラーのページングモードに切り替えてください。
レスポンス — ?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(スキーマが行を拒否した)、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 | いいえ | 7 つのライフサイクル状態のいずれか。 |
kind | query | いいえ | 6 つのローン種類のいずれか。 |
limit | query | いいえ | 1〜100。デフォルトは 20。 |
offset | query | いいえ | 0 以上。デフォルトは 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}
実行中のインポートを取り消します。ワーカーは次のチャンク境界で停止し、すでに保存された行は残ります。すでに終端状態(succeeded、partial、failed、cancelled)にある行を取り消しても何も行われず、既存の状態が返されます。
レスポンス
200 OK:
{ "importId": "1234abcd-...", "status": "cancelled" }| ステータス | 発生条件 |
|---|---|
200 OK | 取り消しが適用された、または行がすでに終端状態でした。 |
404 Not Found | 行が見つからないか、組織をまたいでいます。 |
種類
開始リクエストの kind フィールドによって、各行の検証に使うスキーマと、行を受け取るエンティティが決まります。6 つの種類はエンティティと 1 対 1 で対応します。
| 種類 | エンティティ | スキーマ |
|---|---|---|
borrower | borrowers | POST /borrowers と同じ。 |
loan | loans | POST /loans と同じ。 |
scheduled_repayment | scheduled_repayments | 返済予定のスキーマ。 |
actual_payment | actual_payments | POST /payments と同じ。 |
collateral | collateral | 担保のスキーマ。 |
collateral_valuation | collateral_valuations | 担保評価のスキーマ。 |
この一覧にない kind には 400 UNKNOWN_KIND が返され、レスポンスに許可される値が列挙されるため、打ち間違いも試行錯誤なしに修正できます。
このインターフェースを使う場面
次の場合は非同期インポートを使用してください。
- 過去のアーカイブをロードする。一般的な過去データのロードは数百万行に及びます。
- バッチが一括 NDJSON のいずれかの上限(10 000 行または 10 MB)を超える。
- ロードを途中で取り消せるようにしたい。一括 NDJSON ではリクエストそのものがロードであるため、取り消し用のインターフェースはありません。
- クライアントがポーリングを許容できる。インポートの完了時にプッシュ通知は送られません。
1 回の同期リクエストに収まる小規模な業務バッチには、一括 NDJSON の方が簡単です。