Iframeステップ 2/2

バックエンドの設定

正規化された銀行データをサーバーで受信し、callback に正しく応答します。

先にフロントエンドのチェックリストを完了してください。ウィジェットは銀行データを postMessage では送信しません。このバックエンドに POST で送信します。

連携チェックリスト

0/4

callback URL を作成する
ドメイン、callback、api_key を関連付ける
テストユーザーで動作を確認する
operation_id、token、statistics.code を保存する

1. callback URL を作成する

サーバーに HTTPS エンドポイントを公開し、JSON 本文を持つ POST リクエストを受け付けます。

必要な処理を完了した後、HTTP 200 と次の JSON を返します。

{
    "status": "ok"
}

別のステータスコードや異なる JSON を返すと、ウィジェットはフロントエンドに正常終了を通知しません。

operation_id を使って冪等性を確保してください。同じデータが再送されても、システムに操作を重複作成してはいけません。

2. POST で届く内容

本文は OpenAPI リファレンスの POST /entities/ と同じ JSON です。操作を関連付けるための主な項目は次のとおりです。

フィールド	用途
`success`	読み取りが正常終了した場合は `true`。
`payload`	正規化されたデータ（口座、投資ポートフォリオ、カードなど）。
`statistics.operation_id`	フロントエンドで生成した `operation_id`。
`statistics.token`	後でデータを更新するために保管する認証情報（トークン化が有効な場合）。
`statistics.code`	金融機関コード（`bbva`、`caixabank` など）。
`statistics.SESSION`	セッション識別子。サポートへの問い合わせに役立ちます。
`statistics.warnings`	読み取りを無効にしない警告（商品データが空など）。

一部を抜粋した例:

{
    "success": true,
    "payload": {
        "user_information": {
            "ID": "12345678Z",
            "name": "LUIS GARCIA BAQUERO"
        },
        "accounts": [
            {
                "uuid": "8076932f04f73e27fe608fee4d12fca8708dec8c",
                "subtype": "checking",
                "code": "ES4914651234561234567890",
                "name": "Cuenta NOMINA",
                "currency": "EUR",
                "balances": {
                    "available": 14302.07,
                    "current": 14302.07
                },
                "transactions": []
            }
        ]
    },
    "statistics": {
        "SESSION": "A1B2C3D4E5F67890",
        "execution_time": 12.4,
        "warnings": [],
        "operation_id": "8f1c2a6e-4b0d-4c3a-9e21-0d5b7a91c4e2",
        "token": "FRJ0mHlaqZwLzu",
        "code": "bbva"
    }
}

payload の完全なスキーマは OpenAPI に記載されています。すべてのキーが常に含まれるとは限りません。product_types と、その金融機関でユーザーが保有する商品によって異なります。

3. ドメイン、callback、API キーを関連付ける

クライアントエリアで次の項目を関連付けます。

ウィジェットを読み込むドメイン（フロントエンドのオリジン）
作成した callback URL
自分の api_key

ドメインの登録が完了するまでウィジェットは動作しません。

4. 動作をテストする

ウィジェットを読み込むページを開き、次のユーザーでログインします。

ユーザー	パスワード	結果
`MOCKDATA`	任意	匿名化されたサンプルデータの読み取りが成功します。callback は `success: true` の JSON を受信します。
`MOCKOTP`	任意	二要素認証のチャレンジを再現します。
`MOCKLOGINKO`	任意	ログインエラーを再現します。callback は呼び出されません。

ウェルカムメールがない場合は support@wealthreader.com に依頼してください。

自分の環境にエンドポイントを用意する前に POST を確認する場合は、https://pipedream.com/ などで一時 URL を作成し、callback として設定します。

5. データを更新する（任意）

ここまでの連携は 1 回限りの読み取りです。ユーザーがウィジェットを開くたびに 1 回読み取ります。

夜間バッチや「更新」ボタンが必要な場合は、callback から保存した token と code を使って API を再度呼び出します。ユーザー名とパスワードを再度要求しないでください。

curl --location 'https://api.wealthreader.com/entities/' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'api_key=TU_API_KEY' \
  --data-urlencode 'code=bbva' \
  --data-urlencode 'token=EL_TOKEN_DEL_CALLBACK' \
  --data-urlencode 'product_types=accounts,portfolios'

エラーコードに注意してください。無効なパスワードでは再試行しません。金融機関のメンテナンスによるエラーでは再試行できます。

OpenAPI v3 仕様
Postman コレクション

token が無効になった場合（パスワード変更や新たな 2FA）、その値を wr_conf.token に指定してウィジェットを再度開き、ユーザーに再認証してもらいます。

最終更新 2026-09-10