クックブック
このクックブックは、自社のローンポートフォリオをWaafirのモニタリングAPIに接続するフィンテック企業のエンジニア向けです。各レシピでは、1つのタスクを3つのリファレンスクライアント(cURL、TypeScript、Python)すべてで最初から最後まで説明するため、読者が頭の中で言語間の置き換えをする必要はありません。レシピは正常系だけでなく、実際の連携で遭遇する失敗やエッジケースの処理に重点を置いています。
対象読者
Waafirの組織管理者から個人アクセストークン(PAT)を発行されており、日次のローンテープデータ(借り手、ローン、返済予定、実際の支払い、担保、担保評価)をWaafirに送信するコードを書いている方を対象としています。送信された内容はすべて、まず送信時のまま記録され、その後行として保存されます。そこから、そのポートフォリオにリンクされたすべてのデータルームの投資家向けモニタリングタブにデータが提供されます。
レシピの使い方
どのレシピも同じ構成です。短い導入の説明、決まった順序で並ぶ3つのコードブロック、簡潔な検証の段落です。コードブロックは次のとおりです。
- cURL:シェルにそのままコピー&ペーストして使えます。最も前提が少なく、単発の確認やCIでのチェックに便利です。
- TypeScript:公開されているJSONの契約に対して
fetchを使用します。SDKのインストールは不要です。 - Python:同じJSONの契約に対して
requestsを使用します。標準ライブラリで十分で、Waafir専用のパッケージは不要です。
認証
すべてのエンドポイントで、Authorization ヘッダーにPATが必要です。
Authorization: Bearer <YOUR_PAT>PATは1つのWaafir組織にスコープが限定されており、すべてのリクエストでその組織のIDを伝えます。シークレットとして扱い、漏洩した場合はダッシュボードからローテーションしてください。これらのレシピ全体で使用するAPIのベースURLは https://app.waafir.io です。最初にサンドボックスのテナントに対して連携する場合は、ステージングのURLに置き換えてください。
レシピで使用する規則
- cURLの例に含まれるシェル変数はすべて
${UPPER_CASE_NAME}の形式で書かれているため、一度exportすれば複数のレシピで再利用できます。 - TypeScriptとPythonの例では、
BASE_URLとPATを環境変数から読み込むことを前提としています。お使いの設定ローダーに合わせて調整してください。 Idempotency-Keyヘッダーは、安全なリトライのためのプラットフォーム共通の規則です。正確なセマンティクスについてはリトライのレシピをご覧ください。- すべての書き込みエンドポイントは、お客様独自の
external_idの値を受け付けます。呼び出し元が指定した識別子が、取り込み、照合、テープのダウンロードを通じて正規のハンドルとして使われます。Waafirの内部UUIDを知る必要はありません。
クックブックで扱わない内容
クックブックはタスク指向です。エンドポイントの網羅的な定義、リクエストとレスポンスのスキーマ、エラーコードのリファレンスについては、クックブックとあわせて公開予定のAPIリファレンスのセクションをご覧ください。ポートフォリオとは何か、データルームとどう関係するかといった製品の概念については、データルームと基本概念のセクションをご覧ください。
レシピ一覧
- 非同期NDJSONでローンテープを一括インポートする:基本となる取り込みフロー。直接アップロード、コミット、完了までのポーリング。
- データをコミットする前にドライランで読み込みを検証する:
?dryRun=trueを使った同じフロー。行が書き込まれる前に、ファイルの内容を把握できます。 - 冪等キーで安全にリトライする:一時的なネットワーク障害を、重複したインポートを作らずに乗り切ります。
- インポート後に部分的な失敗のエラーを調査する:インポートが
partialで終わったときに、行ごとのエラーをページ単位で確認します。 - 実行中のインポートをキャンセルする:長時間実行中のインポートを、行が中途半端に書き込まれることなく、次のバッチの区切りで停止します。
- 外部IDでデータを照合する:お客様独自の識別子で行が登録されたことを確認し、日次の件数を検証します。