一括 NDJSON
一括 NDJSON インターフェースは、1 回の同期 HTTP リクエストで最大 1 万行を受け付け、単一レコードのルートと同じスキーマで行ごとに検証し、行単位のエラーレポートを返します。1 回の HTTP リクエストに無理なく収まる日次締めのバッチに使用してください。過去データのロードやより大きなバッチには非同期インポートを使用します。
送信形式は改行区切りの JSON です。1 行につき 1 つの有効な JSON オブジェクトを記述し、末尾のカンマ、全体を囲む配列、開始・終了のエンベロープは付けません。オブジェクト間の空行は受け付けられ、スキップされます。
ルート
エンティティごとに 1 つのルートがあります。各行に適用されるスキーマは、URL のエンティティと一致します。
| メソッド | パス | エンティティ |
|---|---|---|
POST | /api/v1/monitoring/loan/bulk/borrowers | borrower |
POST | /api/v1/monitoring/loan/bulk/loans | loan |
POST | /api/v1/monitoring/loan/bulk/scheduled-repayments | scheduled_repayment |
POST | /api/v1/monitoring/loan/bulk/actual-payments | actual_payment |
POST | /api/v1/monitoring/loan/bulk/collateral | collateral |
POST | /api/v1/monitoring/loan/bulk/collateral-valuations | collateral_valuation |
リクエストボディの各行は、単一レコードのページに記載されたエンティティのスキーマを満たす有効な JSON オブジェクトである必要があります。スキーマは同一で、異なるのは送信時のエンベロープだけです。
リクエスト
POST /api/v1/monitoring/loan/bulk/loans HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/x-ndjson
Idempotency-Key: <opaque-key>ヘッダーとクエリパラメーター:
| 名前 | 位置 | 必須 | 備考 |
|---|---|---|---|
Authorization | header | はい | Bearer PAT。 |
Content-Type | header | いいえ | application/x-ndjson を推奨。application/json も受け付けます。 |
Idempotency-Key | header | いいえ | 本番のバッチでは強く推奨します。 |
?dryRun=true | query | いいえ | 検証を実行し、書き込みはスキップします。 |
?portfolioId=<UUID> | query | はい | バッチのテナント基準。欠落または形式不正の場合は 400 portfolio_id_required が返されます。 |
一括インターフェースは portfolioId をクエリ文字列からのみ読み取ります。行ごとのボディにある同名のフィールドは、バッチのラッパー層では無視されます。ボディ内のすべての行は同じポートフォリオを参照する必要があります。
ボディは NDJSON ペイロードそのもので、UTF-8 でエンコードし、末尾を 1 つの改行で終えます。1 万行を超える行や 10 メガバイトを超えるボディは拒否されます。サイズ上限を参照してください。
行ごとの規約
各行はエンティティのスキーマに対して個別に検証されます。行ごとに適用されるルールは、単一レコードの書き込みと同じです。
- 各行は独自の
idUUID と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"
}
]
}| フィールド | 型 | 説明 |
|---|---|---|
totalRows | integer | ボディ内の空でない行の数。 |
succeeded | integer | 保存された行の数。 |
failed | integer | totalRows - succeeded。 |
bronzeSubmissionId | UUID | NDJSON ボディ全体に対する 1 件の送信記録の id。?dryRun=true のレスポンスには含まれません。 |
reused | boolean | Idempotency-Key が以前のバッチと一致し、レスポンスが再構成された場合にのみ存在し、値は true です。それ以外の場合は存在しません。 |
dryRun | boolean | ?dryRun=true のレスポンスにのみ存在し、値は true です。それ以外の場合は存在しません。 |
errors[].rowNumber | integer | リクエストボディ内の 1 から始まる行番号。 |
errors[].code | enum | validation_failed | unique_violation | fk_violation | check_violation | db_error。 |
errors[].message | string | 人が読める要約。validation_failed の場合、検証エラーは 1 つの文にまとめられます。 |
行単位のエラーの形には rowNumber、code、message だけが含まれます。行ごとの fieldErrors 配列も、行ごとの rawRow もありません。元の NDJSON はレスポンスで返されるのではなく、送信記録にそのまま保存されます。
succeeded が 0 でも、エラーレスポンスではありません。バッチは解析され、プラットフォームはすべての行を処理しました。レポートは、何も取り込まれなかったことを示しています。本当に失敗したバッチ(ボディ全体の NDJSON の形式不正、ボディのサイズ超過、未知のポートフォリオ)には、下表のとおり 4xx が返されます。
ステータスコード
このインターフェースのトップレベルのエラーエンベロープでは小文字の code 値を使用し、単一レコードのルートで使用される大文字のコードとは区別されます。2 つのコード空間は意図的に分けられています。
| ステータス | エンベロープ | 発生条件 |
|---|---|---|
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: [...] } | サイズ上限を参照してください。 |
サイズ上限
一括インターフェースのペイロード上限は、次のうち小さい方です。
- 空でない行 1 万行。 それを超える行は、処理の開始前に拒否されます。
- リクエストボディ 10 メガバイト。
いずれかの上限を超えたリクエストには 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での 1 回目の呼び出し。 ボディは 1 件の送信として記録され、すべての行が処理され、行単位のレポートが送信とともに保存されます。 - キー
Kでの 2 回目の呼び出し(ボディが同じ)。 2 件目の記録も再挿入も行われません。プラットフォームはreused: trueを付けて元のレポートを返します。 - キー
Kでの 2 回目の呼び出し(ボディが異なる)。 プラットフォームはやはり元のレポートを返します。元の送信が正式な情報源です。修正したボディで再度 POST する場合は、別のキーを使用する必要があります。
つまり、ネットワークの瞬断後にクライアントが再試行しても安全です。2 回目のリクエストのボディが転送中に切り詰められたり変更されたりしても、プラットフォームは最初に成功した処理の行単位の結果を返します。
送信記録
一括リクエストは、行ごとにではなく、NDJSON ボディ全体を含む 1 件の送信として記録されます。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 を選択してください。
- バッチが 1 万行かつ 10 メガバイトに収まる。
- HTTP レスポンスで行単位のレポートをすぐに受け取りたい。
- 長時間かかる HTTP リクエストを許容できる。一括バッチは通常数秒で完了しますが、データベースの外部キー参照が多い大きなバッチでは時間がかかることがあります。
次の場合は非同期インポートを選択してください。
- バッチがいずれかのサイズ上限を超える。
- 返済、返済予定、借り手の過去アーカイブをロードする。一般的な過去データのロードは数百万行に及びます。
- 実行中のロードを取り消せる選択肢を残しておきたい。