照合
照合インターフェースを使うと、プラットフォームが割り当てた UUID ではなく独自の呼び出し元 ID を使って、Waafir に何が取り込まれたかを確認できます。ルートは 2 つだけと意図的に最小限にしていますが、堅牢な連携を運用面で支える要です。健全な日次のデータ取り込みは、必ず照合の呼び出しで締めくくられます。
呼び出し元 ID で照合する理由
externalId: "L-001" のローンを送信したとき、自社システムはすでにその名前で行を識別しています。プラットフォームに「L-001 はありますか」と問い合わせるのは自然な次の手順です。しかも、先にプラットフォーム UUID に変換する必要がないため、照合ロジックを帳簿で使っているのと同じ識別子に対して実行できます。
プラットフォームは、externalId が有効な行についてポートフォリオ内で一意であることを保証しています。そのため、externalId による検索は単一行の読み取りで済みます。
ルート
| メソッド | パス | 用途 |
|---|---|---|
GET | /api/v1/monitoring/loan/loans/{externalId}?portfolioId=<UUID> | 呼び出し元 ID で単一のローンを読み取ります。 |
GET | /api/v1/monitoring/loan/counts | エンティティごとの行数の合計を読み取ります。ポートフォリオ、日付、エンティティで絞り込むこともできます。 |
GET /api/v1/monitoring/loan/loans/{externalId}
送信した externalId で単一のローンを読み取ります。取り消し済み(ソフト削除)の行は除外されます。
リクエスト
| パラメーター | 位置 | 必須 | 制約 |
|---|---|---|---|
externalId | path | はい | 1〜255 文字。URL で安全でない文字はパーセントエンコードしてください。 |
portfolioId | query | はい | ローンを所有するポートフォリオの UUID。 |
externalId はポートフォリオ間では一意ではなく、ポートフォリオ内でのみ一意であるため、portfolioId が必須です。
レスポンス — 200 OK
{
"loan": {
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"borrowerId": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "L-001",
"predecessorLoanId": null,
"principalAmount": "10000.0000",
"currencyCode": "USD",
"interestRateApr": "0.180000",
"disbursementDate": "2026-01-15",
"termMonths": 12,
"repaymentFrequency": "monthly",
"productType": "Term loan",
"status": "active",
"metadata": {},
"createdAt": "2026-01-15T08:00:00Z",
"updatedAt": "2026-01-15T08:00:00Z"
},
"borrower": {
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "B-001",
"name": "J***",
"email": "j***@example.com",
"phone": "***-***-1234",
"nationalIdLast4": "1234",
"countryCode": "KE",
"dob": "1985-03-20",
"gender": "female",
"incomeBand": null,
"employmentStatus": null
}
}レスポンスには、ローンの借り手が PII をマスキングした状態で埋め込まれます。これは投資家スコープのビューで、借り手の GET エンドポイントと同じマスキングが適用されます。マスキングにより、呼び出し元のシステムに PII を露出させずに「このローンが正しい借り手に紐付いている」ことを確認できます。生の PII が必要な管理者は、借り手を UUID で取得するインターフェースで ?unmask=true を使用し、監査ログに記録されます。
金額フィールドは保存時の完全な精度で表示されます(金額は小数部 4 桁、interestRateApr は 6 桁)。クライアントでは浮動小数点数に変換せず、不透明な 10 進数文字列として扱ってください。
ステータスコード
| ステータス | 発生条件 |
|---|---|
200 OK | 貴組織内でローンが見つかりました。 |
400 Bad Request | portfolioId が欠落しているか形式が不正、または externalId に不正なパーセントエンコードが含まれています。 |
404 Not Found | 指定したポートフォリオにローンが有効なものとして存在しない、またはポートフォリオが他の組織に属しています。 |
cURL
curl https://app.waafir.io/api/v1/monitoring/loan/loans/L-001?portfolioId=ddf63d12-1234-5678-9abc-def012345678 \
-H "Authorization: Bearer $WAAFIR_PAT"GET /api/v1/monitoring/loan/counts
エンティティごとの行数を読み取ります。ポートフォリオ、日付、単一のエンティティで絞り込むこともできます。ソフト削除された行は除外されます。
リクエスト
| パラメーター | 位置 | 必須 | 制約 |
|---|---|---|---|
portfolioId | query | いいえ | UUID。単一のポートフォリオに絞り込みます。省略すると組織全体の集計になります。 |
date | query | いいえ | YYYY-MM-DD。指定すると、レスポンスにエンティティごとの onDate 件数が含まれます。 |
entity | query | いいえ | borrowers、loans、scheduled_repayments、actual_payments、collateral、collateral_valuations のいずれか(大文字・小文字を区別しません)。指定すると、そのエンティティのみが返されます。 |
レスポンス — 200 OK
デフォルトの集計(6 つのエンティティすべて):
{
"counts": {
"borrowers": { "total": 1200 },
"loans": { "total": 3450 },
"scheduled_repayments": { "total": 41400 },
"actual_payments": { "total": 32118 },
"collateral": { "total": 600 },
"collateral_valuations": { "total": 1840 }
},
"date": null,
"portfolioId": null
}?date=2026-05-22 を指定すると、各エンティティに、指定日に作成された行の数を示す onDate 件数が加わります。
{
"counts": {
"borrowers": { "total": 1200, "onDate": 0 },
"loans": { "total": 3450, "onDate": 12 },
"scheduled_repayments": { "total": 41400, "onDate": 144 },
"actual_payments": { "total": 32118, "onDate": 1207 },
"collateral": { "total": 600, "onDate": 0 },
"collateral_valuations": { "total": 1840, "onDate": 0 }
},
"date": "2026-05-22",
"portfolioId": null
}?entity=loans を指定すると、loans のエントリのみが表示されます。
ステータスコード
| ステータス | 発生条件 |
|---|---|
200 OK | クエリが解析され、件数が返されました。 |
400 Bad Request | portfolioId、date、entity のいずれかの形式が不正です。 |
存在しない portfolioId や他の組織に属する portfolioId を指定しても 404 は返されず、すべての件数がゼロの 200 が返されます。これは意図的な動作です。件数インターフェースは自社データの読み取りであり、未知のポートフォリオは行を持たないポートフォリオと機能的に区別できません。
cURL
# Full daily reconciliation for one portfolio:
curl "https://app.waafir.io/api/v1/monitoring/loan/counts?portfolioId=ddf63d12-1234-5678-9abc-def012345678&date=2026-05-22" \
-H "Authorization: Bearer $WAAFIR_PAT"一般的な日次照合
その日の送信を終えたら、正規の照合フローは次のとおりです。
GET /counts?date=<today>を呼び出します。対象のポートフォリオを指定し、各エンティティのonDate件数を今日送信した件数と比較します。件数が一致すれば、バッチは問題なく取り込まれています。- 不一致がある場合は、該当する行を個別に検索します。
GET /loans/{externalId}を使用します。検索の負荷は小さく(それぞれインデックススキャン 1 回)、プラットフォームが割り当てた UUID を含む正規の行の状態が返されるため、それを使ってさらに調査できます。 - 行レベルの調査には、単一レコードの GET エンドポイントと非同期インポートのエラーページングエンドポイントを使用します。これらが行ごとの失敗の詳細を提供するインターフェースです。
照合インターフェースは、意図的に読み取り専用かつ低コストに設計されています。これは連携のハートビートであり、負荷をかけるためのインターフェースではありません。ポートフォリオごとに 1 日 1〜2 回呼び出してください。照合専用のレート制限はありませんが、短い間隔のループでポーリングしないでください。