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

単一レコード 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>

ボディ:

フィールド型必須制約
idUUID 文字列はい呼び出し元が指定するプラットフォーム識別子。
portfolioIdUUID 文字列はい所属するポートフォリオ。貴組織内に存在している必要があります。
externalId文字列はい1〜255 文字。有効な行について (portfolio, externalId) ごとに一意。
namestring | nullいいえ借り手の氏名。そのまま保存され、投資家向けの読み取りではマスキングされます。
emailstring | nullいいえRFC 5322 形式のメールアドレス。そのまま保存され、投資家向けの読み取りではマスキングされます。
phonestring | nullいいえ自由形式の電話番号。そのまま保存され、投資家向けの読み取りではマスキングされます。
nationalIdLast4string | nullいいえちょうど 4 桁の数字。先頭側の桁が返されることはありません。
countryCodestring | nullいいえISO-3166 の 2 文字コード(大文字)。
dobdate string | nullいいえYYYY-MM-DD。
genderenum | nullいいえmale | female | non_binary | other | undisclosed(大文字・小文字を区別しません)。
incomeBandstring | nullいいえ自由形式。
employmentStatusstring | nullいいえ自由形式。
metadataobject | 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 RequestfieldErrorsいずれかのボディフィールドの検証エラー。
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 を要求でき、その際は監査ログにエントリが書き込まれます。

リクエスト

パラメーター位置必須制約
idpathはい借り手のプラットフォーム UUID。
unmaskqueryいいえ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 Requestid が正しい形式の 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

同じポートフォリオ内の既存の借り手に対してローンを作成します。

リクエスト

フィールド型必須制約
idUUID 文字列はい呼び出し元が指定するプラットフォーム識別子。
portfolioIdUUID 文字列はい所属するポートフォリオ。
borrowerIdUUID 文字列はい同じポートフォリオ内の有効な借り手。
externalId文字列はい1〜255 文字。有効な行についてポートフォリオ内で一意。
predecessorLoanIdUUID string | nullいいえ条件変更(リストラクチャリング)時に設定し、置き換えられるローンを指します。
principalAmount10 進数文字列はい小数部は最大 4 桁。
currencyCode文字列はいISO-4217 の 3 文字コード。大文字・小文字を区別しません。
interestRateApr10 進数文字列はい小数部は最大 6 桁。>= 0 である必要があります。
disbursementDate日付文字列はいYYYY-MM-DD。
termMonths整数はい> 0 である必要があります。
repaymentFrequencyenumはいmonthly | weekly | biweekly | quarterly | bullet(大文字・小文字を区別しません)。
productTypestring | nullいいえ自由形式。例:"Term loan"、"Overdraft"。
statusenumはいpending | active | paid_off | restructured | written_off | defaulted(大文字・小文字を区別しません)。
metadataobject | nullいいえそのままパススルー。

レスポンス

201 Created(冪等なリプレイでは 200 OK)とともに { id, externalId, bronzeSubmissionId, reused } が返されます。

ステータスエンベロープ発生条件
200 OK{ ..., reused: true }冪等なリプレイ。
201 Created{ ..., reused: false }新しいローンが挿入されました。
400 Bad RequestfieldErrors検証エラー(例: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 を設定した新しいローンとしてモデル化します。

リクエスト

フィールド型必須制約
idUUID 文字列はい呼び出し元が指定するプラットフォーム識別子。
portfolioIdUUID 文字列はい所属するポートフォリオ。
loanIdUUID 文字列はい同じポートフォリオ内の有効なローン。
externalId文字列はい1〜255 文字。有効な行についてポートフォリオ内で一意。
paymentDate日付文字列はいYYYY-MM-DD。
amount10 進数文字列はい受領した返済の総額。
currencyCode文字列はいISO-4217。
principalPaid10 進数文字列いいえデフォルトは "0"。
interestPaid10 進数文字列いいえデフォルトは "0"。
feesPaid10 進数文字列いいえデフォルトは "0"。
writeOffAmount10 進数文字列いいえデフォルトは "0"。下記の債務免除ルールを参照。
paymentNotesstring | nullいいえwriteOffAmount > 0 の場合は "Forgiven"(大文字・小文字を区別しません)である必要があります。
paymentMethodenum | nullいいえcash | bank_transfer | card | mobile_money | check | other。
metadataobject | nullいいえそのままパススルー。

債務免除ルール。 writeOffAmount > 0 の場合、paymentNotes は大文字・小文字を区別せずに "Forgiven" と一致する必要があります。プラットフォームは API の境界でリクエストを失敗させるため、不正な返済は何かが記録される前に拒否されます。

レスポンス

201 Created(冪等なリプレイでは 200 OK)とともに { id, externalId, bronzeSubmissionId, reused } が返されます。

ステータスエンベロープ発生条件
200 OK{ ..., reused: true }冪等なリプレイ。
201 Created{ ..., reused: false }新しい返済が挿入されました。
400 Bad RequestfieldErrors検証エラー(金額の形式不正、列挙値の不一致、必須フィールドの欠落)。
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 で実際の返済を読み取ります。取り消し済み(ソフト削除)の行も含まれます。書き込みの確認や、取り消し済みレコードの確認に使用します。

リクエスト

パラメーター位置必須制約
idpathはい返済のプラットフォーム 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>

ボディ:

フィールド型必須制約
statusenumはいactive | paid_off | defaulted | written_off | restructured のいずれか(大文字・小文字を区別しません)。
effectiveDate日付文字列はいYYYY-MM-DD。
reasonstring | nullいいえ1〜500 文字。監査ログに記録されます。

ステータス遷移マトリクス

プラットフォームは遷移マトリクスを適用します。無効な遷移には 422 INVALID_STATUS_TRANSITION が返され、fieldErrors に遷移元と遷移先のステータスが示されます。

遷移元許可される遷移先
pendingactive
activepaid_off, defaulted, written_off, restructured
paid_off(終端)
defaultedwritten_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 RequestfieldErrorsボディの検証エラー、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

ボディ(任意):

フィールド型必須制約
reasonstring | 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 RequestfieldErrorsid が正しい形式の UUID ではない、または reason が 500 文字を超えています。
404 Not Found{ error, code: "NOT_FOUND" }返済が存在しないか、他の組織に属しています。

監査の完全性のため、取り消しのたびに(2 回目も含めて)送信記録が書き込まれます。行が変更されるのは 1 回目の呼び出しのみです。

ソフト削除と externalId の再利用

一意性制約は有効な行にのみ適用されるため、取り消された返済の externalId は今後の書き込みで再利用できます。誤った送信を修正する正規の手順は次のとおりです。

  1. 元の行に対して POST /api/v1/monitoring/loan/payments/{id}/cancel を実行します。
  2. 修正したフィールドで新しい行を作成するため、POST /api/v1/monitoring/loan/payments を実行します。同じ externalId を再利用できますが、id は別の値を指定する必要があります。

これは意図的な設計です。取り消しは非破壊的であり(元の行は監査のために保持されます)、externalId を再利用することで、照合のための業務上の呼び出し元 ID 空間を詰まった状態に保てます。