API リファレンス
このセクションは、Waafir のローン領域 API のリファレンスマニュアルです。ローン領域 API は、フィンテック企業が投資家によるモニタリングのためにポートフォリオデータを Waafir へ送り込む HTTP インターフェースです。/api/v1/monitoring/loan/ 配下のすべてのルート、リクエストとレスポンスのスキーマ、すべてのステータスコード、共通の開発者体験の規約、そして想定されるエラーエンベロープを記載しています。
このリファレンスは網羅的ですが、読み物形式ではありません。初めて連携を行い、cURL、TypeScript、Python を並べたエンドツーエンドの手順ガイドが必要な場合は、このリファレンスと併せて「クックブック」をお読みください。両者は組み合わせて読むことを前提に作られています。
API の対象範囲
ローン領域 API は、4 つの取り込み方式と照合インターフェースを提供します。
- 単一レコード CRUD:1 行につき 1 回の HTTP 呼び出しです。新規ローン 1 件、返済 1 件、ステータス遷移 1 回といった、少量の業務書き込みに使用します。
- 一括 NDJSON:1 回の同期呼び出しで最大 1 万行を送信します。1 回の HTTP リクエストに収まる日次締めのバッチに使用します。
- 非同期インポート:ファイルを直接アップロードし、その後非同期で処理します。過去データのロードや、1 万行を超えるバッチに使用します。
- 照合:送信済みの行を独自の呼び出し元 ID で読み戻し、エンティティごとの行数を取得します。今日の分を送信する前に、昨日の送信が問題なく取り込まれたことを確認するために使用します。
各方式はそれぞれ専用のページで説明しています。ページの順序は、多くの連携担当者がたどる順序に合わせています。まず概要を読み、次に最初に使う予定の取り込み方式、続いて照合、最後にエラーリファレンスを読んでください。
6 つのローン領域エンティティ
すべてのルートは、以下のエンティティのいずれか 1 つ以上を対象とします。完全なスキーマはルートごとに記載しており、ここでは一覧のみを示します。
borrower:ローンを借り入れる自然人または法人。任意の PII フィールドを持ち、読み取り時にはマスキングされます。loan:ローン契約そのもの。元本、通貨、APR、期間、返済頻度、ステータスを含みます。scheduled_repayment:契約上の返済スケジュール。支払期日ごとに 1 行です。actual_payment:実際に受け取った返済。償却や一部返済も含みます。collateral:ローンに対して差し入れられた担保。collateral_valuation:担保行のある時点における評価額。複数の評価方法に対応します。
すべてのエンティティは、貴組織内のいずれかのポートフォリオに属します。ポートフォリオは書き込みのたびに指定します。組織は個人用アクセストークンから決まり、リクエストボディに現れることはありません。
認証の要点
すべてのリクエストは Authorization: Bearer <PAT> を付けて送信します。<PAT> は Waafir のコントロールプレーンが発行する個人用アクセストークンです。トークンのスコープは組織単位です。組織 A に発行されたトークンで組織 B のデータを読み書きすることはできず、組織をまたいだ読み取りには、他テナントのリソースの存在を漏らさないよう 403 Forbidden ではなく 404 Not Found が返されます。
認証と認可のモデルの詳細は概要で説明しています。
このリファレンスの使い方
ページを順番に読むことも、必要なインターフェースへ直接移動することもできます。
- 概要:すべてのローン領域ルートが守る共通規約。認証、連携上の保証(呼び出し元が指定する ID、冪等性、ドライラン)、エラーエンベロープ、金額と日付の規約、取り消しのセマンティクス、そしてすべての送信が記録される仕組みを説明します。
- 単一レコード CRUD:単一行の POST、GET、PATCH、取り消しの各ルート。
- 一括 NDJSON:行単位のエラーレポートを備えた同期一括取り込み。
- 非同期インポート:2 段階アップロード、ステータスのポーリング、エラーのページングからなるライフサイクル。
- 照合:呼び出し元 ID による読み戻しと、エンティティごとの行数。
- エラーとステータスコード:ローン領域インターフェースが返すすべてのステータスコード、エラーエンベロープ、名前付きエラーコードをまとめたカタログ。
タスク別のガイド(ポートフォリオのエンドツーエンドのオンボーディング、日次照合の実行、一部失敗したインポートからの復旧など)については、このリファレンスと同時に公開される「クックブック」を参照してください。「クックブック」は各タスクを 3 つの言語で解説します。各ルートが何を受け付け、何を返すかについては、このリファレンスが正式な情報源です。
このリファレンスに含まれないもの
- オンボーディングとトークン:組織の登録、ポートフォリオの作成、個人用アクセストークンの発行方法。これらの手順は、プラットフォーム管理のドキュメントと「クックブック」の入門レシピで説明しています。
- 投資家向け分析:チャートパック、ローンテープのエクスポート、ローンテープのダウンロードインターフェース。これらは別のルートで提供されており、ここでは扱いません。
- Webhook と定期的なテープ配信:ここでは扱いません。