入门

集成流程

这是 iframe 集成的正常路径。callback 在通知 frontend 之前发送。

sequenceDiagram
participant User as 用户
participant Web
participant Widget as Wealth Reader Widget
participant API as Wealth Reader API
participant Bank as 金融机构
User->>Web: 打开应用
Web->>Widget: 使用 operation_id 加载 iframe
User->>Widget: 选择机构并同意授权
Widget->>API: 使用 operation_id 请求数据
API->>Bank: 查询
Bank-->>API: 响应
API-->>Widget: 返回标准化数据
Widget->>Web: POST 至 callback（operation_id + token + payload）
Web-->>Widget: HTTP 200 与 status ok
Widget-->>Web: postMessage flow completed
Web-->>User: 显示成功完成

职责分工

角色	职责
前端	生成唯一的 `operation_id`，加载 widget，并监听 `postMessage`。
widget	向用户展示银行、登录、2FA 和错误。
Wealth Reader API	与金融机构通信并标准化响应。
后端	公开 callback URL，返回 `{"status":"ok"}`，并保存 `operation_id`、`token` 和 payload。

如果失败

密码错误、2FA 或金融机构错误：由 widget 与用户处理。前端可能通过 postMessage 收到错误 JSON；在读取成功完成之前，不会调用 callback。
您的 callback 未返回 200 + {"status":"ok"}：用户看不到成功，前端也收不到 flow completed。
token 失效（密码变更、新的 2FA）：再次打开 widget 并传入该 token，以便用户重新认证。

各消息详情以及 callback 正文见 iframe 各页。

下一步

如果通过 iframe 集成，请继续阅读 frontend，然后是 backend。如果无法嵌入 iframe，请前往 OAuth。

最后更新于 2026-08-15