> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 立即同步：按需刷新银行数据

> 使用 Didit，只需一次调用即可随时获取连接的最新银行数据并等待结果，同时了解银行每日限额及 429 响应内容。

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

## 自动同步

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

## 一次调用即可立即同步

添加 `"wait": true`，一次请求即可返回最新数据：

```bash theme={null}
curl -X POST https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/refresh/ \
  -H "x-api-key: $DIDIT_API_KEY" -H "content-type: application/json" \
  -d '{ "wait": true }'
```

请求头 `Prefer: wait=25` 的效果相同。该调用最多等待 25 秒：

| 返回结果 | 含义 |
| - | - |
| `200` | 同步已完成。响应体为该同步记录，包含其 `outcome`、各账户的 `added`、`modified` 和 `removed` 数量，以及 `balances_changed`。 |
| `202` | 银行在 25 秒内未作出响应，或您未请求等待。响应体包含 `sync_id`：请使用 `get_sync_run` 读取同步记录，或订阅 `bank.sync.completed`。仅当同步存储了变更时，才会随后发送 `bank.data.updated`。 |

```json theme={null}
{
  "id": "d4a9e7b2-1c58-4f03-96ab-5e2d8c7f0b14",
  "trigger": "requested",
  "status": "succeeded",
  "outcome": "succeeded",
  "balances_changed": true,
  "results": [{ "resource": "transactions", "outcome": "succeeded", "added": 3, "modified": 0, "removed": 1 }]
}
```

如果同步已在运行，您将获得相同的 `sync_id`，而不会创建第二个任务。
收到 `200` 或 `bank.data.updated` 后，请使用已存储的游标读取变更流。
之后如需查看同步的执行情况，请使用 [`get_sync_run`](https://docs.didit.me/zh/standalone-apis/bank-sync-run-get)。

## 价格

自动同步和实时同步都包含在连接的月费中，参见[定价](https://docs.didit.me/zh/getting-started/bank-verification-pricing.md)。
实时同步从不产生额外费用。

## 银行的每日限额

银行会限制在用户不在场时可以获取数据的频率。
欧洲相关规定允许银行限制无人值守访问，即每个账户每天最多四次读取。
这是上限，而非承诺：银行可能允许更少的次数，也可能同意更多。

* 自动同步与实时同步共用同一额度，自动同步计划从不使用一天中的最后两次读取。
* 连接上的 `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`。

## 需要处理的错误

| 错误 | 含义 | 处理方式 |
| - | - | - |
| `429 refresh_limit_reached` | 该银行的预算已用完。 | 等待 `Retry-After` 指定的时间，并依赖自动同步。 |
| `409 connection_not_active` | 连接状态不是 `active`。 | 检查其状态。 |
| `409 consent_expired` | 同意已结束。 | [续期](https://docs.didit.me/zh/use-cases/renew-bank-consent.md)。 |

## 相关内容

* [面向会计的持续银行数据流](https://docs.didit.me/zh/use-cases/bank-data-for-accounting.md)
* [银行 Webhook](https://docs.didit.me/zh/core-technology/bank-verification/webhooks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.