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 将不会通知 frontend 流程已正确完成。

将 operation_id 视为幂等：重复投递不应在您的系统中创建两条操作。

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 时读取一次。

如果需要夜间批处理或“更新”按钮，请使用从 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），请再次打开 widget，并在 wr_conf.token 中传入该值，以便用户重新认证。

最后更新于 2026-08-15