Iframeステップ 2/2

backend を設定する

正規化された銀行データをサーバーで受け取り、callback を正しく確認応答します。

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

連携チェックリスト

0/4

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

1. callback URL を作成する

JSON 本文の POST を受け付ける HTTPS エンドポイントをサーバーに公開します。

必要な処理が終わったら、HTTP 200 と次の JSON を返してください。

{
    "status": "ok"
}

別のステータスコードや異なる JSON を返すと、widget はフローが正常に完了したことをフロントエンドに通知しません。

operation_id は冪等として扱ってください。同じ配信が繰り返されても、システム上に 2 件の操作が作られてはなりません。

2. POST で届く内容

本文は OpenAPI リファレンスの POST /entities/ と同じ JSON です。操作を照合するために必要なフィールド:

フィールド	用途
`success`	読み取りが成功した場合は `true`。
`payload`	正規化データ（口座、ポートフォリオ、カードなど）。
`statistics.operation_id`	フロントエンドが生成した `operation_id`。
`statistics.token`	あとからの再取得用に保管された認証情報（トークン化が有効な場合）。
`statistics.code`	金融機関コード（`bbva`、`caixabank` など）。
`statistics.SESSION`	セッション ID。サポートチケットで有用です。
`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 key を関連付ける

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

widget を読み込むドメイン（フロントエンドの origin）
作成した callback URL
api_key

ドメインが登録されるまで、widget は動作しません。

4. フローをテストする

widget を読み込むページを開き、次でサインインします。

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

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

エンドポイントがまだない状態で POST を確認したい場合は、https://pipedream.com/ などのサービスで一時 URL を作り、それを callback に設定してください。

5. データを再取得する（任意）

ここまでの統合は one-shot です。ユーザーが widget を開くたびに 1 回読み取ります。

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

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

エラーコードをよく確認してください。無効なパスワードは再試行しないでください。金融機関がメンテナンス中の場合は再試行できます。

token が使えなくなった場合（パスワード変更または新しい 2FA）は、wr_conf.token にその値を渡して widget を再度開き、ユーザーに再認証してもらいます。

最終更新 2026-08-15