跳转到主要内容
POST
curl
Didit 的“刷新银行连接”端点会请求立即同步,并返回 202 和 sync_id。 发送 "wait": true 可最多等待 25 秒,并在一次调用中获得已完成的同步结果,且不额外收费。 由于银行限制无人值守访问,此调用可能返回 429 refresh_limit_reached 以及 Retry-After。 请参阅按需刷新银行数据。

授权

x-api-key
string
header
必填

您的应用 API 密钥,可在 Business Console 的开发者 -> API 密钥中获取。主密钥拥有完全访问权限。命名密钥可以设置范围:可按资源设置无权限、只读或读写,可限定为部分工作流或已批准的会话,可限定为一组 IP 地址,并可设置过期日期。401 表示密钥错误、已被撤销或已过期;403 表示未发送密钥、密钥无权访问该资源或执行该操作,或请求来自其 IP 列表之外的地址;会话相关路由返回 404,表示该会话不在密钥的工作流或状态范围内。没有媒体访问权限的密钥会将图片、视频和 PDF 的 URL 返回为 null;没有会话写入权限的密钥会将会话链接和令牌返回为 null。请参阅 https://docs.didit.me/console/api-keys。

请求头

Idempotency-Key
string

您为单次操作选择的可选重试安全密钥,最长 255 个字符(可使用 UUID)。使用相同密钥、endpoint、查询参数和请求体重复发送的请求,会返回第一次的响应,状态码和响应体均相同,且不会再次运行或计费。同一密钥若用于其他 endpoint、查询参数或请求体,将返回 409 idempotency_key_reused;若第一个请求仍在处理中,则返回 409 idempotency_key_in_progress 及 Retry-After。失败的请求(任何 4xx 或 5xx)不会被存储,因此您可以使用相同密钥再次发送。无论您使用 API 密钥还是访问 token 调用,密钥都归属于您的应用。请参阅重试与幂等性。

Required string length: 1 - 255
Prefer
string

wait=<seconds> 会将调用最多挂起指定的秒数(最多 25 秒),与请求体中的 wait: true 作用相同。

示例:

"wait=25"

路径参数

id
string<uuid>
必填

连接 ID。

请求体

application/json

刷新的可选请求体。

wait
boolean
默认值:false

true 会将调用最多挂起 25 秒,并以 200 响应已完成的同步结果,因此一次请求即可返回最新数据。若银行在此时间内未响应,调用将返回 202:请使用 sync_id 通过 get_sync_run 读取同步结果,或订阅 bank.sync.completed。仅当同步存储了变更时,才会发送 bank.data.updated。请求头 Prefer: wait=<seconds>(最多 25)效果相同。

响应

同步在 25 秒内完成。

由带 wait 的刷新返回的已完成同步:同步运行记录,包含其 outcome、results 中的各账户数量以及 balances_changed。

id
string<uuid>
必填
connection_id
string<uuid>
必填
trigger
enum<string>
必填
可用选项:
initial,
scheduled,
requested
status
enum<string>
必填
可用选项:
queued,
running,
succeeded,
partial,
failed
started_at
string<date-time> | null
必填
finished_at
string<date-time> | null
必填
results
object[]
必填

本次运行按账户和资源分别执行了什么。

error
object | null
必填

整个运行失败的原因。未失败时为 null。单个账户和资源的错误见 results。

outcome
enum<string>
必填

同步的结束方式。

可用选项:
succeeded,
partial,
failed
balances_changed
boolean
必填

是否有任何余额发生变化。

最后修改于 2026年11月22日