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

概要

すべてのローン領域エンドポイントは、このページに記載した規約を共有します。最初にこのページをお読みください。各インターフェースのページは、内容を繰り返さずにこのページを参照します。

ベース URL とバージョニング

ローン領域のルートはすべて /api/v1/monitoring/loan/ 配下にマウントされています。v に続く整数はメジャーバージョンです。メジャーバージョンの更新は破壊的変更であり、明示的な非推奨の告知を行ったうえでのみ実施されます。メジャーバージョン内のマイナーな変更は追加のみ(新しい任意フィールド、新しいエンドポイント、新しい列挙値)で、理解できないフィールドを無視する連携を壊すことはありません。

本番環境のホストは https://app.waafir.io です。完全な URL を得るには、このリファレンスサイトに記載された任意のパスの前にホストを付けます。例:https://app.waafir.io/api/v1/monitoring/loan/borrowers。

認証

すべてのリクエストには、Bearer トークンを含む Authorization ヘッダーを付けます。

Authorization: Bearer <PAT>

<PAT> は、Waafir のコントロールプレーンが単一の組織に対して発行する個人用アクセストークンです。トークンの組織が、すべての読み取りと書き込みのテナント範囲を決定します。トークンがすでに組織を固定しているため、URL やボディに組織パラメーターはありません。

組織をまたいだリクエストには、403 Forbidden ではなく 404 Not Found が返されます。 403 を返すと、id によって他テナントのリソースの存在が漏れてしまいます。404 を返す方針により、未知の id と他テナントの id はまったく同じように扱われます。

Authorization ヘッダーがないリクエスト、未知のトークンを使ったリクエスト、失効したトークンを使ったリクエストには 401 Unauthorized が返されます。

連携上の保証

すべての変更系ルートは、以下の保証を守ります。いずれもクライアントコードが前提にしてよいものです。ここで一度読んでおけば、堅牢な連携を一度で実装できます。

呼び出し元が指定する ID

すべてのエンティティのリクエストボディには id フィールドがあり、UUID として呼び出し元が指定します。プラットフォームが代わりに ID を生成することはありません。これがこのリストにある他のすべての規約の土台です。冪等性、照合、リプレイはいずれも、呼び出し元が選んだ識別子で行を特定できることを前提としています。

同じ id で行を再度 POST すると、409 ID_CONFLICT と、id を指す fieldErrors エントリが返されます。ID は慎重に選んでください。生成した UUIDv4 を推奨しますが、正しい形式の UUID であれば何でも使えます。

id に加えて、すべてのエンティティは externalId を持ちます。これは最大 255 文字の自由形式の文字列で、自社システムから行を特定するために使います。externalId は有効な行についてポートフォリオ内で一意であり、これによって呼び出し元 ID による照合が可能になっています。

Idempotency-Key ヘッダー

すべての変更系ルートは、任意の Idempotency-Key HTTP ヘッダーを読み取ります。指定されている場合、プラットフォームは内部アーカイブと照らし合わせて重複を排除します。同じキーを持つ 2 回目のリクエストには、ボディが多少異なっていても 1 回目と同じレスポンスが返されます。これにより、リクエストが届いたかどうか判断できなくなるネットワークの瞬断をクライアントが乗り切れます。

このヘッダーは送信時に大文字と小文字を区別しません(Idempotency-Key、idempotency-key、IDEMPOTENCY-KEY のいずれも有効です)。値は不透明な文字列として扱われます。論理的な操作ごとに安定した値を選んでください。一般的には UUIDv4 にルートの識別子を付けたものを使います。

?dryRun=true

すべての変更系ルートは ?dryRun=true クエリパラメーターを受け付けます。ドライランのリクエストは検証とテナントチェックを実行して検証済みの入力を返しますが、何も記録せず、行も保存しません。実際に書き込む前に、ボディが正しく解析されることを確認するために使います。

ドライランが成功した場合のレスポンスの形は { "dryRun": true, "validatedInput": <body> } で、ステータスは 200 OK です。ドライラン中の検証エラーは、実際の書き込みと同じ 400 の形で返されます。違いは副作用の有無だけです。

fieldErrors 検証エンベロープ

検証エラーの場合は、構造化されたエンベロープとともに 400 Bad Request が返されます。

{
  "error": "Validation failed",
  "fieldErrors": [
    { "path": "interestRateApr", "message": "interestRateApr must be >= 0" },
    { "path": "termMonths", "message": "termMonths must be > 0" }
  ]
}

path は問題のあるフィールドへのドット区切りのパス、message は人が読める説明です。このエンベロープはすべてのルートで共通のため、クライアント側の 1 つのハンドラーですべての検証エラーを一貫して表示できます。

大文字・小文字を区別しない列挙値と「もしかして」ヒント

ドメインの列挙値(ローンのステータス、支払方法、返済頻度、通貨コードなど)は、送信時に大文字・小文字を問わず受け付けます。プラットフォームは保存前に正規の小文字形式へ正規化します。

一致しない場合は 400 が返され、fieldErrors エントリに問題の値と、最も近い受け付け可能な値が示されます。

{
  "error": "Validation failed",
  "fieldErrors": [
    {
      "path": "status",
      "message": "got 'restruktured', did you mean 'restructured'?"
    }
  ]
}

候補は小規模な編集距離の指標で算出されるため、文字の入れ替わりや 1 文字の打ち間違いを確実に検出できます。

metadata JSONB のパススルー

すべてのエンティティは、オブジェクト型の任意の metadata フィールドを受け付けます。プラットフォームはこのオブジェクトをそのまま保存します。キーを削除することも、値を変換することもありません。社内 ID、ソースシステム、抽出タイムスタンプ、キャンペーンコードなど、プラットフォーム自体が理解する必要のないクライアント側のコンテキストを付けるために使います。

metadata を受け付けないインターフェースが 2 つあります。ローンのステータス遷移ルートと、返済の取り消しルートです。その理由は各ルートの説明に記載しています。

呼び出し元 ID による照合

すべてのエンティティは、送信した externalId によってポートフォリオの範囲内で特定できます。照合インターフェース(GET /loans/{externalId} と GET /counts)はこれを利用し、プラットフォームが割り当てた UUID を一切使わずに書き込みを確認できるようにしています。正確な形式は照合のページを参照してください。

金額の表現

金額は送信時に、小数部が最大 4 桁の10 進数字の文字列で表します。IEEE-754 の 2 進浮動小数点数では 10 進のセント単位を正確に表現できないため、JavaScript の number は拒否されます。

{ "amount": "100.50", "currencyCode": "USD" }

小数部が 4 桁を超える値や、数字、先頭のマイナス記号、1 つの小数点以外の文字を含む値には、400 と fieldErrors エントリが返されます。空文字列は拒否されます。

通貨コードは ISO-4217 の 3 文字コードです。プラットフォームは一般的なコードを明示的に認識します。大文字 3 文字の形に合う未知のコードは受け付けてそのまま保存するため、新興市場の珍しいコードがブロックされることはありません。

日付の形式

日付は送信時に、YYYY-MM-DD 形式の ISO-8601 カレンダー日付の文字列で表します。

{ "disbursementDate": "2026-01-15" }

タイムゾーンの要素はありません。日付はポートフォリオ側の解釈によるカレンダー上の日付であり、プラットフォームは変換を行いません。

取り消しのセマンティクス

API 呼び出しで行が消去されることはありません。取り消しやその他の取り消し処理では、行を取り消し済みとしてマークします。その結果、次のようになります。

  • 取り消しても externalId は解放されません。 externalId が一意なのは、ポートフォリオ内の有効な行の間だけです。取り消された行はもう有効ではないため、修正後の再送信でその externalId を再利用できます。
  • 照合の読み取りでは、デフォルトで取り消し済みの行は返されません。 GET /loans/{externalId} と GET /counts のデフォルトのレスポンスでは、ソフト削除された行が除外されます。
  • 送信記録はどのような場合でも保持されます。 行が取り消された場合でも、その行を作成した送信の記録は監査のためにそのまま残ります。

すべての送信が記録されます

成功したすべての変更は、行が書き込まれる前に生のリクエストボディを記録します。連携への影響は次のとおりです。

  • 200/201 は送信が永続的に記録されたことを意味します。後続の処理で後から問題が指摘された場合も同様です。監査証跡は、プラットフォームがリクエストを受け付けた時点から始まります。
  • 409 ID_CONFLICT でもアーカイブされます。 送信記録には競合と試行された送信の両方が保持されるため、何が送信されたかについて曖昧さのないまま後から調査できます。
  • 非同期インポートはコミット時に記録されます。 アップロードされた NDJSON ファイルとインポートそのものが記録となり、非同期インポートには行ごとの記録は別途ありません。

送信記録は変更できません。公開 API から直接読み取ることはできませんが、照合インターフェースが信頼できる根拠となっているのはこの記録があるからです。照合で見えるすべての行には、対応するアーカイブエントリが存在します。

このリファレンスの他のページの構成

このリファレンスサイトの以降の各ページでは、取り込み方式 1 つ、または照合インターフェースを説明します。各ルートのページは同じ構成です。1 文での目的の説明、リクエストの形(ヘッダー、クエリ、ボディ)、ステータスコードごとのレスポンスの形、そして最小限の cURL 呼び出し例です。フィールドごとの制約は一覧しやすい表にまとめています。詳しい例や 3 言語のコードサンプルは「クックブック」にあります。

エラーとステータスコードのページは、このサイトのすべてのルートで使われるレスポンスエンベロープをまとめたリファレンスです。連携の前に一度通読し、予期しない 200 以外のステータスが返されたときに参照してください。