単一レコード CRUD
単一レコード CRUD インターフェースは少量向けの経路で、1 行につき 1 回の HTTP 呼び出しを行います。新規ローン 1 件、日次バッチに間に合わなかった返済 1 件、ステータス遷移といった業務上の書き込みや、プラットフォーム UUID による読み戻しに使用します。日次締めのバッチには一括 NDJSON を、過去データのロードには非同期インポートを使用してください。
このページのすべてのルートは、概要に記載した規約(Bearer トークン認証、連携上の保証、fieldErrors エンベロープ、取り消しのセマンティクス、すべての送信が記録される仕組み)に従います。以下のルートごとの説明では、ルート固有の形のみを記載します。ルートをまたぐ共通の動作については概要を参照してください。
ルート一覧
| メソッド | パス | 用途 |
|---|---|---|
POST | /api/v1/monitoring/loan/borrowers | 借り手を作成 |
GET | /api/v1/monitoring/loan/borrowers/{id} | UUID で借り手を読み取り(PII マスキングあり) |
POST | /api/v1/monitoring/loan/loans | ローンを作成 |
POST | /api/v1/monitoring/loan/payments | 実際の返済を作成 |
GET | /api/v1/monitoring/loan/payments/{id} | UUID で実際の返済を読み取り |
PATCH | /api/v1/monitoring/loan/loans/{loanRef}/status | ローンを新しいステータスに遷移 |
POST | /api/v1/monitoring/loan/payments/{id}/cancel | 返済をソフト削除 |
すべての変更系ルートは Idempotency-Key ヘッダーと ?dryRun=true クエリパラメーターを受け付け、検証エラー時には構造化された fieldErrors エンベロープを返します。
POST /api/v1/monitoring/loan/borrowers
portfolioId で指定したポートフォリオに借り手を作成します。
リクエスト
POST /api/v1/monitoring/loan/borrowers HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json
Idempotency-Key: <opaque-key>ボディ:
| フィールド | 型 | 必須 | 制約 |
|---|---|---|---|
id | UUID 文字列 | はい | 呼び出し元が指定するプラットフォーム識別子。 |
portfolioId | UUID 文字列 | はい | 所属するポートフォリオ。貴組織内に存在している必要があります。 |
externalId | 文字列 | はい | 1〜255 文字。有効な行について (portfolio, externalId) ごとに一意。 |
name | string | null | いいえ | 借り手の氏名。そのまま保存され、投資家向けの読み取りではマスキングされます。 |
email | string | null | いいえ | RFC 5322 形式のメールアドレス。そのまま保存され、投資家向けの読み取りではマスキングされます。 |
phone | string | null | いいえ | 自由形式の電話番号。そのまま保存され、投資家向けの読み取りではマスキングされます。 |
nationalIdLast4 | string | null | いいえ | ちょうど 4 桁の数字。先頭側の桁が返されることはありません。 |
countryCode | string | null | いいえ | ISO-3166 の 2 文字コード(大文字)。 |
dob | date string | null | いいえ | YYYY-MM-DD。 |
gender | enum | null | いいえ | male | female | non_binary | other | undisclosed(大文字・小文字を区別しません)。 |
incomeBand | string | null | いいえ | 自由形式。 |
employmentStatus | string | null | いいえ | 自由形式。 |
metadata | object | null | いいえ | そのままパススルー。 |
レスポンス
新規書き込みでは 201 Created、冪等なリプレイでは 200 OK が返されます。
{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "BORROWER-001",
"bronzeSubmissionId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789",
"reused": false
}| ステータス | エンベロープ | 発生条件 |
|---|---|---|
200 OK | { id, externalId, bronzeSubmissionId, reused: true } | Idempotency-Key が以前のリクエストと一致。新たな書き込みはありません。 |
201 Created | { id, externalId, bronzeSubmissionId, reused: false } | 新しい行が挿入されました。 |
400 Bad Request | fieldErrors | いずれかのボディフィールドの検証エラー。 |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | portfolioId が存在しないか、他の組織に属しています。 |
409 Conflict | { error, code: "ID_CONFLICT", fieldErrors: [...] } | 同じ id を持つ有効な借り手がすでに存在します。 |
cURL
curl -X POST https://app.waafir.io/api/v1/monitoring/loan/borrowers \
-H "Authorization: Bearer $WAAFIR_PAT" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e" \
-d '{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"externalId": "BORROWER-001",
"gender": "female",
"countryCode": "KE"
}'GET /api/v1/monitoring/loan/borrowers/{id}
プラットフォーム UUID で借り手を読み取ります。PII フィールドはデフォルトでマスキングされます。管理者は ?unmask=true で生の PII を要求でき、その際は監査ログにエントリが書き込まれます。
リクエスト
| パラメーター | 位置 | 必須 | 制約 |
|---|---|---|---|
id | path | はい | 借り手のプラットフォーム UUID。 |
unmask | query | いいえ | true で生の PII を返します。管理者のみ。デフォルトはマスキング。 |
レスポンス
マスキングされた借り手レコードとともに 200 OK が返されます。
{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"externalId": "BORROWER-001",
"name": "J***",
"email": "j***@example.com",
"phone": "***-***-1234",
"nationalIdLast4": "1234",
"countryCode": "KE",
"dob": "1985-03-20",
"gender": "female",
"incomeBand": null,
"employmentStatus": null,
"metadata": {}
}| ステータス | 発生条件 |
|---|---|
200 OK | 行が貴組織内に存在します。呼び出し元が管理者で、かつ ?unmask=true の場合は PII が生の値で返され、それ以外の場合はマスキングされます。 |
400 Bad Request | id が正しい形式の UUID ではありません。 |
404 Not Found | 行が存在しない、取り消し済みである、または他の組織に属しています。 |
PII マスキングは name、email、phone、nationalIdLast4 に適用されます。nationalIdLast4 フィールドは書き込み時点で下 4 桁のみを保存していますが、読み取り時のマスキングにより、管理者以外の読み取りではその 4 桁も隠されます。
管理者以外の呼び出し元が ?unmask=true を指定しても、403 は返されません。レスポンスはマスキングされた形のまま 200 となり、拒否されたマスキング解除の試行が監査ログに記録されます。マスキングされた形が安全なデフォルトであるため、プラットフォームはロールチェックをエラーとして表に出しません。試行をセキュリティチームが把握できるのは監査証跡によってです。
管理者の呼び出し元が ?unmask=true を指定すると生の PII を受け取り、そのリクエストではマスキング解除を記録する監査ログエントリが別途書き込まれます。レスポンスには Cache-Control: private, no-store が付与され、生の PII を含むペイロードが中間者にキャッシュされるのを防ぎます。
POST /api/v1/monitoring/loan/loans
同じポートフォリオ内の既存の借り手に対してローンを作成します。
リクエスト
| フィールド | 型 | 必須 | 制約 |
|---|---|---|---|
id | UUID 文字列 | はい | 呼び出し元が指定するプラットフォーム識別子。 |
portfolioId | UUID 文字列 | はい | 所属するポートフォリオ。 |
borrowerId | UUID 文字列 | はい | 同じポートフォリオ内の有効な借り手。 |
externalId | 文字列 | はい | 1〜255 文字。有効な行についてポートフォリオ内で一意。 |
predecessorLoanId | UUID string | null | いいえ | 条件変更(リストラクチャリング)時に設定し、置き換えられるローンを指します。 |
principalAmount | 10 進数文字列 | はい | 小数部は最大 4 桁。 |
currencyCode | 文字列 | はい | ISO-4217 の 3 文字コード。大文字・小文字を区別しません。 |
interestRateApr | 10 進数文字列 | はい | 小数部は最大 6 桁。>= 0 である必要があります。 |
disbursementDate | 日付文字列 | はい | YYYY-MM-DD。 |
termMonths | 整数 | はい | > 0 である必要があります。 |
repaymentFrequency | enum | はい | monthly | weekly | biweekly | quarterly | bullet(大文字・小文字を区別しません)。 |
productType | string | null | いいえ | 自由形式。例:"Term loan"、"Overdraft"。 |
status | enum | はい | pending | active | paid_off | restructured | written_off | defaulted(大文字・小文字を区別しません)。 |
metadata | object | null | いいえ | そのままパススルー。 |
レスポンス
201 Created(冪等なリプレイでは 200 OK)とともに { id, externalId, bronzeSubmissionId, reused } が返されます。
| ステータス | エンベロープ | 発生条件 |
|---|---|---|
200 OK | { ..., reused: true } | 冪等なリプレイ。 |
201 Created | { ..., reused: false } | 新しいローンが挿入されました。 |
400 Bad Request | fieldErrors | 検証エラー(例:interestRateApr が負の値、currencyCode の形式が不正)。 |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | ポートフォリオが存在しないか、組織をまたいでいます。 |
409 Conflict | { error, code: "ID_CONFLICT" } | 同じ id を持つ有効なローンがすでに存在します。 |
422 Unprocessable Entity | { error, code: "REFERENCED_ENTITY_NOT_FOUND", fieldErrors: [{ path: "borrowerId", ... }] } | borrowerId が同じポートフォリオ内の有効な借り手に解決されません。 |
cURL
curl -X POST https://app.waafir.io/api/v1/monitoring/loan/loans \
-H "Authorization: Bearer $WAAFIR_PAT" \
-H "Content-Type: application/json" \
-d '{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"borrowerId": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "LOAN-001",
"principalAmount": "10000.00",
"currencyCode": "USD",
"interestRateApr": "0.18",
"disbursementDate": "2026-01-15",
"termMonths": 12,
"repaymentFrequency": "monthly",
"status": "active"
}'POST /api/v1/monitoring/loan/payments
既存のローンに対する実際の返済を記録します。受領した返済、一部返済、償却に使用します。条件変更は、返済としてではなく、predecessorLoanId を設定した新しいローンとしてモデル化します。
リクエスト
| フィールド | 型 | 必須 | 制約 |
|---|---|---|---|
id | UUID 文字列 | はい | 呼び出し元が指定するプラットフォーム識別子。 |
portfolioId | UUID 文字列 | はい | 所属するポートフォリオ。 |
loanId | UUID 文字列 | はい | 同じポートフォリオ内の有効なローン。 |
externalId | 文字列 | はい | 1〜255 文字。有効な行についてポートフォリオ内で一意。 |
paymentDate | 日付文字列 | はい | YYYY-MM-DD。 |
amount | 10 進数文字列 | はい | 受領した返済の総額。 |
currencyCode | 文字列 | はい | ISO-4217。 |
principalPaid | 10 進数文字列 | いいえ | デフォルトは "0"。 |
interestPaid | 10 進数文字列 | いいえ | デフォルトは "0"。 |
feesPaid | 10 進数文字列 | いいえ | デフォルトは "0"。 |
writeOffAmount | 10 進数文字列 | いいえ | デフォルトは "0"。下記の債務免除ルールを参照。 |
paymentNotes | string | null | いいえ | writeOffAmount > 0 の場合は "Forgiven"(大文字・小文字を区別しません)である必要があります。 |
paymentMethod | enum | null | いいえ | cash | bank_transfer | card | mobile_money | check | other。 |
metadata | object | null | いいえ | そのままパススルー。 |
債務免除ルール。 writeOffAmount > 0 の場合、paymentNotes は大文字・小文字を区別せずに "Forgiven" と一致する必要があります。プラットフォームは API の境界でリクエストを失敗させるため、不正な返済は何かが記録される前に拒否されます。
レスポンス
201 Created(冪等なリプレイでは 200 OK)とともに { id, externalId, bronzeSubmissionId, reused } が返されます。
| ステータス | エンベロープ | 発生条件 |
|---|---|---|
200 OK | { ..., reused: true } | 冪等なリプレイ。 |
201 Created | { ..., reused: false } | 新しい返済が挿入されました。 |
400 Bad Request | fieldErrors | 検証エラー(金額の形式不正、列挙値の不一致、必須フィールドの欠落)。 |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | ポートフォリオが存在しないか、組織をまたいでいます。 |
409 Conflict | { error, code: "ID_CONFLICT" } | 同じ id を持つ有効な返済がすでに存在します。 |
422 Unprocessable Entity | { error, code: "REFERENCED_ENTITY_NOT_FOUND", fieldErrors: [{ path: "loanId", ... }] } | loanId が同じポートフォリオ内の有効なローンに解決されません。 |
400 Bad Request | { error, code: "CHECK_VIOLATION", fieldErrors: [...] } | 返済の保存時に債務免除ルールによって拒否されました(まれなケースです。同じ形は先に検証で拒否されます)。 |
GET /api/v1/monitoring/loan/payments/{id}
プラットフォーム UUID で実際の返済を読み取ります。取り消し済み(ソフト削除)の行も含まれます。書き込みの確認や、取り消し済みレコードの確認に使用します。
リクエスト
| パラメーター | 位置 | 必須 | 制約 |
|---|---|---|---|
id | path | はい | 返済のプラットフォーム UUID。 |
レスポンス
完全な返済レコードとともに 200 OK が返されます。取り消し済みの行では deletedAt に値が入り、有効な行では deletedAt: null となります。組織をまたぐ UUID や未知の UUID には 404 Not Found が返されます。id が正しい形式の UUID でない場合は 400 Bad Request が返されます。
PATCH /api/v1/monitoring/loan/loans/{loanRef}/status
ローンを新しいステータスに遷移させます。{loanRef} パスセグメントには、ローンのプラットフォーム UUID と externalId のどちらでも指定できます。externalId を指定する場合は、外部 ID がポートフォリオ間で一意ではないため、?portfolioId=<UUID> も指定する必要があります。
リクエスト
PATCH /api/v1/monitoring/loan/loans/LOAN-001/status?portfolioId=ddf63d12-1234-5678-9abc-def012345678 HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json
Idempotency-Key: <opaque-key>ボディ:
| フィールド | 型 | 必須 | 制約 |
|---|---|---|---|
status | enum | はい | active | paid_off | defaulted | written_off | restructured のいずれか(大文字・小文字を区別しません)。 |
effectiveDate | 日付文字列 | はい | YYYY-MM-DD。 |
reason | string | null | いいえ | 1〜500 文字。監査ログに記録されます。 |
ステータス遷移マトリクス
プラットフォームは遷移マトリクスを適用します。無効な遷移には 422 INVALID_STATUS_TRANSITION が返され、fieldErrors に遷移元と遷移先のステータスが示されます。
| 遷移元 | 許可される遷移先 |
|---|---|
pending | active |
active | paid_off, defaulted, written_off, restructured |
paid_off | (終端) |
defaulted | written_off, restructured |
written_off | (終端) |
restructured | (終端) |
ローンを restructured に遷移させた場合、自然な次の手順は、predecessorLoanId を設定して代替ローンを POST /loans することです。この 2 つの書き込みは意図的にアトミックにしていません。代替ローンの POST が失敗した場合、元のローンは restructured のまま残り、次回のクエリ時に照合インターフェースがこの不整合を明らかにします。
レスポンス
成功時は 200 OK が返されます。
{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"externalId": "LOAN-001",
"status": "restructured",
"bronzeSubmissionId": "9d8c7b6a-5432-1098-7654-321098765432",
"reused": false
}| ステータス | エンベロープ | 発生条件 |
|---|---|---|
200 OK | { id, externalId, status, bronzeSubmissionId, reused } | 遷移が適用されました(または reused: true を伴う冪等なリプレイ)。 |
400 Bad Request | fieldErrors | ボディの検証エラー、externalId で検索する際の portfolioId の欠落、列挙値の形式不正。 |
404 Not Found | { error, code: "NOT_FOUND" } | UUID でローンが見つからない、または (portfolioId, externalId) が解決されません。 |
422 Unprocessable Entity | { error, code: "INVALID_STATUS_TRANSITION", fieldErrors: [...] } | 遷移元と遷移先の組み合わせが遷移マトリクスにありません。fieldErrors[].message に許可される遷移先が列挙されます。 |
409 Conflict | { error, code: "IDEMPOTENCY_CONFLICT" } | この Idempotency-Key は別の遷移ですでに使用されています。以前の書き込みはそのまま有効です。新しい遷移は新しいキーで送信してください。 |
指定した effectiveDate は送信とともに記録され、監査ログにも書き込まれますが、レスポンスボディには含まれません。このルートでは意図的に metadata を受け付けません。遷移そのものが監査イベントであり、任意の reason フィールドが人が読めるコンテキストを担います。
POST /api/v1/monitoring/loan/payments/{id}/cancel
以前に記録した返済をソフト削除します。取り消しエンドポイントは、ローン領域で唯一の取り消し用インターフェースです。PATCH /loans/{id}/adjust は存在せず、今後も提供されません。
リクエスト
POST /api/v1/monitoring/loan/payments/7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f/cancel HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/jsonボディ(任意):
| フィールド | 型 | 必須 | 制約 |
|---|---|---|---|
reason | string | null | いいえ | 1〜500 文字。取り消しの監査イベントに記録されます。 |
空のボディも受け付けます。Content-Type ヘッダーを完全に省略してもかまいません。
レスポンス
成功時は 200 OK が返されます。
{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"deletedAt": "2026-03-15T11:02:33Z",
"bronzeSubmissionId": "9d8c7b6a-5432-1098-7654-321098765432",
"reused": false,
"alreadyCancelled": false
}同じ返済に対して 2 回目の呼び出しを行うと、レスポンスの形は同じですが、alreadyCancelled: true となり、deletedAt は最初の取り消し時のタイムスタンプになります。reused フラグは冪等性の状態を示し、alreadyCancelled はこの呼び出しで行が変更されたかどうかを示します。
| ステータス | エンベロープ | 発生条件 |
|---|---|---|
200 OK | { id, deletedAt, bronzeSubmissionId, reused, alreadyCancelled } | 1 回目または 2 回目以降の取り消し。 |
400 Bad Request | fieldErrors | id が正しい形式の UUID ではない、または reason が 500 文字を超えています。 |
404 Not Found | { error, code: "NOT_FOUND" } | 返済が存在しないか、他の組織に属しています。 |
監査の完全性のため、取り消しのたびに(2 回目も含めて)送信記録が書き込まれます。行が変更されるのは 1 回目の呼び出しのみです。
ソフト削除と externalId の再利用
一意性制約は有効な行にのみ適用されるため、取り消された返済の externalId は今後の書き込みで再利用できます。誤った送信を修正する正規の手順は次のとおりです。
- 元の行に対して
POST /api/v1/monitoring/loan/payments/{id}/cancelを実行します。 - 修正したフィールドで新しい行を作成するため、
POST /api/v1/monitoring/loan/paymentsを実行します。同じexternalIdを再利用できますが、idは別の値を指定する必要があります。
これは意図的な設計です。取り消しは非破壊的であり(元の行は監査のために保持されます)、externalId を再利用することで、照合のための業務上の呼び出し元 ID 空間を詰まった状態に保てます。