跳转到主要内容
Didit 的立即同步功能可随时通过一次调用,从银行读取某个连接的最新数据。 实时同步已包含在该连接的月度价格中,不会额外收费。 唯一的限制来自银行。

自动同步

  • 首次同步在用户连接时运行。
  • 此后,每个处于活动状态的持续连接每天自动同步一到四次,具体次数取决于银行。连接上的 sync.frequency_per_day 显示次数,sync.next_sync_at 显示下次计划同步的时间。
  • 如果银行允许每天进行更多无需人工参与的读取,则始终至少保留两次用于实时同步。
  • 当一次同步存储了变更时,会发送 bank.data.updated,此时您可以使用游标读取变更数据流。
  • 同步失败后会以退避方式重试。连续失败 24 小时后,连接保持为 active,并带有 sync.status: failing,同时发送 bank.sync.failed。恢复正常后会随之发送 bank.sync.recovered。
  • 当银行要求用户重新登录时,连接会变为 renewal_required。

一次调用即可立即同步

添加 "wait": true,一次请求即可返回最新数据:
请求头 Prefer: wait=25 的效果相同。该调用最多等待 25 秒:
如果同步已在运行,您将获得相同的 sync_id,而不会创建第二个任务。 收到 200 或 bank.data.updated 后,请使用已存储的游标读取变更流。 之后如需查看同步的执行情况,请使用 get_sync_run。

价格

自动同步和实时同步都包含在连接的月费中,参见定价。 实时同步从不产生额外费用。

银行的每日限额

银行会限制在用户不在场时可以获取数据的频率。 欧洲相关规定允许银行限制无人值守访问,即每个账户每天最多四次读取。 这是上限,而非承诺:银行可能允许更少的次数,也可能同意更多。
  • 自动同步与实时同步共用同一额度,自动同步计划从不使用一天中的最后两次读取。
  • 连接上的 sync.live_syncs_left_today 表示今天还剩多少次实时同步,sync.budgets[] 显示每个分项额度:scope(connection 或 account)、resource、limit、remaining 和 resets_at。
  • 当用户在 Bank Link 中在场时(用于续期或重新连接),读取不受限制。
  • 当天的额度用完时,调用会返回 429 refresh_limit_reached,并附带 Retry-After 请求头(距离额度重置的秒数),以及包含 live_syncs_left_today 和 budgets 的 sync 对象。请等待这段时间,同时依赖自动同步。
  • 您的 API 速率限制是独立的:每个应用每分钟 600 次读取和 300 次写入,并带有 X-RateLimit-* 请求头。

了解数据的新鲜程度

  • 连接和每个账户上的 sync.last_synced_at,表示 Didit 最近一次从银行获取数据的时间,而不是你最近一次读取数据的时间。
  • 两个读取交易的接口都会返回 X-Bank-Last-Synced-At。

需要处理的错误

相关内容

最后修改于 2026年11月22日