跳转到主要内容
持续银行数据流可以让会计或记账产品每天获取每位客户的银行账户余额和交易数据,客户无需重新登录。 借助 Didit,您可以创建一个具有持续访问权限的链接,在有新数据到达时接收 Webhook,使用游标只读取变更的内容,跟踪同意何时到期,并在客户离开时停止或删除该连接。 本指南带您从零开始,为一位客户搭建每日数据流。 同一套代码适用于所有客户:每位客户、每家银行对应一个连接。

您需要准备的内容

  • 具有银行数据权限的 API 密钥,用于您的沙盒应用。请参阅 快速入门。
  • 用于接收 bank.* 事件的 Webhook 目标。请参阅 银行 Webhook。
  • 数据库中的一张表,用于为每个客户存储连接 ID、变更流游标和同意到期时间。

步骤 1 创建具有持续访问权限的链接

  • access: ongoing 会让访问权限保持开启,直至同意结束。consent_days 只是一项请求:实际日期由银行决定,并显示在连接信息中。
  • history_from 用于请求从某个日期开始的历史记录,例如年初。如果您更倾向于使用 history_days(1 至 365),可以改用它,但两者不能同时使用。银行可能提供的数据较少:每个账户都会通过 history_coverage 报告实际覆盖范围。
  • ownership.compare: none 会跳过账户持有人比对,因此无需提供参考身份。如需将账户持有人与 Didit 中已验证的企业进行比对,请使用 business。
  • end_user.reference 是您为该客户设置的 ID。它可以被搜索,并可让 Didit 识别同一客户再次连接相同账户的情况。
  • 将客户引导至托管验证页面,并通过重定向 URL将其返回您的产品。
请将链接的 id 与客户一起存储。

步骤 2 等待连接

客户端完成操作后,会收到包含 connection_id 的 bank.link.completed。 请确认该事件,因为绝不能信任浏览器:
保存 connection_id,然后等待 bank.connection.created。此时即可读取账户、余额和近期交易(sync.initial_status 为 succeeded 或 partial)。 bank.connection.history_complete 会在历史数据回填结束后发出。 对于每个账户,history_coverage.oldest_booking_date 表示银行实际提供的历史数据最早可追溯到的记账日期。

步骤 3: 加载第一份副本

空游标会返回所有当前交易,每笔都标记为 added 且 reset: true。 逐页读取,并仅在最后保存游标:
  • 首次读取是真正的快照:它返回连接在读取开始时拥有的每一笔交易,每笔仅以 added 形式返回一次,并且是其当前状态,即使您在翻页时运行了同步。
  • 翻页期间发生的变更会在从 next_cursor 开始的下一次读取中返回:您已收到的交易会以 modified 形式再次返回,新交易则以 added 形式返回。
  • 仅在收到 has_more: false 的响应后,才保存 next_cursor。
  • 如果翻页中途失败,请从您已保存的游标重新开始。
  • 使用 GET /v3/bank/accounts/{account_id}/balances/ 读取余额。

步骤 4 - 在每个 Webhook 到达时保持数据最新

Didit 会在每个活跃的持续连接上自动同步,每天一到四次,具体取决于银行(sync.frequency_per_day)。 当一次同步存储了变更时,bank.data.updated 会随 connection_id、account_ids 和计数一同送达。 使用您保存的游标调用变更信息流:
  • added 为新交易,包括待处理交易。
  • modified 为已变更的交易,内容为其当前状态。对每一条按 id 执行插入或更新操作:您已持有的交易会被更新,尚未持有的交易则会被新增。
  • removed 带有 reason。忽略您没有的 id。当待处理交易入账时,它会以 pending_booked 原因出现在 removed 中,入账后的交易则会出现在 added 中。
请将交易的 id 用作主键:它在多次读取、同步和续期之间保持不变。 检查 identity_quality:当其值为 derived 时,银行更正可能表现为一条 removed 加一条 added。 读取操作不计费,但数据只有在同步运行时才会变化,因此每个 Webhook 读取一次即可。 如需更快获取数据,请使用 Sync Now:按需刷新银行数据。

第 5 步 处理重置

游标早于重放窗口时,接口返回 410 cursor_expired,并带有 bootstrap: true。 变更日志可重放 90 天,因此对于每日运行的任务,这种情况很少见。 请从空游标重新开始,并用返回的结果替换您的副本,而不是追加到现有副本中。 从空游标发起的每次读取都会带有 reset: true,因此新连接和过期游标可以走同一段代码路径。

步骤 6 关注同意的到期时间

同意有一个到期日期:consent.expires_at。 Didit 会在到期前 14 天、7 天和 1 天发送 bank.connection.consent_expiring。 需要续期时,调用 renew_connection。在剩余有效期超过 30 天时,它会返回 409 renewal_not_needed。 供终端用户完成续期的页面暂不可用。 如果终端用户任由同意过期,连接状态将变为 renewal_required:您仍可以读取已同步的数据。 详情请参阅银行同意的续期。

步骤 7 停止访问并删除

  • 客户离开您的产品:调用 revoke_connection 立即停止读取,或调用 delete_connection 停止读取并删除已存储的数据。
  • 客户在银行停止共享:bank.connection.revoked 会随附 ended_by 到达。请停止该连接的数据推送。

价格

持续访问按每个活跃连接每月计费。 该价格包含连接中的所有账户、余额、交易、银行提供时最多 365 天的历史记录、自动同步、在银行限制范围内的实时同步、续期、Webhook 以及所有读取操作。 未完成的链接免费,状态为 renewal_required、paused 或 revoked 的连接同样免费。 请参阅 定价。

检查清单

  • 每个客户与每家银行只建立一个连接,并保存其游标和授权到期时间。
  • Webhook 处理程序具备幂等性,以事件 ID 为键。
  • reset: true 会替换您的副本,绝不会追加。
  • 已处理 removed 及其原因。
  • 授权到期提醒已与您向客户发出的通知对接。
  • bank.connection.revoked 会停止数据推送。
  • 沙盒中的沙盒套餐通过测试。
最后修改于 2026年11月22日