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 密钥

在客户区关联：

加载组件的域名（前端的 origin）；
刚创建的 callback URL；
您的 api_key。

域名注册完成前，组件无法工作。

4. 测试流程

打开加载组件的页面并登录：

用户	密码	结果
`MOCKDATA`	任意	成功读取匿名化示例数据。callback 收到 `success: true` 的 JSON。
`MOCKOTP`	任意	模拟双因素认证挑战。
`MOCKLOGINKO`	任意	模拟登录错误。不调用 callback。

如没有欢迎邮件，请向 support@wealthreader.com 索取。

如果想在自己的环境部署端点前查看 POST，可在 https://pipedream.com/ 等服务创建临时 URL，并将其设为 callback。

5. 更新数据（可选）

目前的集成是单次读取：用户每次打开组件都会读取一次。

如需夜间批处理或“更新”按钮，请使用从 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