Waafir
このページは機械翻訳であり、人による確認を待っています。誤りが含まれている可能性があります。

非同期インポート

非同期インポートインターフェースは、過去データのロードや、一括 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 する際にそのまま付ける必要のあるアップロード用ヘッダーが返されます。

リクエストボディ

フィールド型必須制約
kindenumはい6 つの種類のいずれか。
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以降のすべての呼び出しで参照するプラットフォーム識別子。
uploadUrlPUT アップロード用の有効期限付き URL。
headersPUT に含める必要がある 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 が 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}

インポートの現在のステータス、件数、エラーの要約を読み取ります。これは、クライアントが進捗を監視するために呼び出すポーリング用エンドポイントです。

リクエスト

パラメーター位置必須備考
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 は、エラーコードごとの合計と最大 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

呼び出し元のローンインポートを新しい順に一覧表示します。

リクエスト

パラメーター位置必須制約
statusqueryいいえ7 つのライフサイクル状態のいずれか。
kindqueryいいえ6 つのローン種類のいずれか。
limitqueryいいえ1〜100。デフォルトは 20。
offsetqueryいいえ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 で対応します。

種類エンティティスキーマ
borrowerborrowersPOST /borrowers と同じ。
loanloansPOST /loans と同じ。
scheduled_repaymentscheduled_repayments返済予定のスキーマ。
actual_paymentactual_paymentsPOST /payments と同じ。
collateralcollateral担保のスキーマ。
collateral_valuationcollateral_valuations担保評価のスキーマ。

この一覧にない kind には 400 UNKNOWN_KIND が返され、レスポンスに許可される値が列挙されるため、打ち間違いも試行錯誤なしに修正できます。

このインターフェースを使う場面

次の場合は非同期インポートを使用してください。

  • 過去のアーカイブをロードする。一般的な過去データのロードは数百万行に及びます。
  • バッチが一括 NDJSON のいずれかの上限(10 000 行または 10 MB)を超える。
  • ロードを途中で取り消せるようにしたい。一括 NDJSON ではリクエストそのものがロードであるため、取り消し用のインターフェースはありません。
  • クライアントがポーリングを許容できる。インポートの完了時にプッシュ通知は送られません。

1 回の同期リクエストに収まる小規模な業務バッチには、一括 NDJSON の方が簡単です。