> ## 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 Now는 한 번의 호출로 언제든지 연결의 최신 은행 데이터를 읽어옵니다.
실시간 동기화는 연결의 월 요금에 포함되어 있으므로 추가로 청구되는 비용은 없습니다.
유일한 제한은 은행의 제한입니다.

## 자동 동기화

* 첫 번째 동기화는 사용자가 연결할 때 실행됩니다.
* 그 이후에는 활성 상태인 지속 연결이 은행에 따라 하루에 한 번에서 네 번 자동으로 동기화됩니다. 연결의 `sync.frequency_per_day`에서 횟수를 확인할 수 있고, `sync.next_sync_at`에서 다음 동기화 예정 시각을 확인할 수 있습니다.
* 은행이 하루에 사용자 개입 없는 읽기 요청을 더 많이 허용하는 경우에도 실시간 동기화를 위해 하루에 최소 두 번은 항상 남겨 둡니다.
* 동기화로 변경 사항이 저장되면 `bank.data.updated`가 전송되며, 이때 커서를 사용해 [변경 피드](https://docs.didit.me/ko/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/ko/standalone-apis/bank-sync-run-get)으로 확인할 수 있습니다.

## 요금

자동 동기화와 실시간 동기화는 모두 연결의 월간 요금에 포함됩니다. 자세한 내용은 [요금](https://docs.didit.me/ko/getting-started/bank-verification-pricing.md)을 참조하세요.
실시간 동기화로 추가 요금이 부과되는 일은 절대 없습니다.

## 은행의 일일 한도

은행은 고객이 직접 참여하지 않은 상태에서 데이터를 가져오는 빈도를 제한합니다.
유럽 규정에 따라 은행은 계좌당 하루 네 번의 조회로 무인 접근을 제한할 수 있습니다.
이는 상한선일 뿐 보장된 횟수가 아닙니다. 은행은 이보다 적게 허용하거나 더 많은 조회에 동의할 수도 있습니다.

* 자동 동기화와 실시간 동기화는 하나의 예산을 공유하며, 자동 동기화 일정은 하루의 마지막 두 번의 조회를 사용하지 않습니다.
* 연결 정보의 `sync.live_syncs_left_today`는 오늘 남은 실시간 동기화 횟수를 나타내며, `sync.budgets[]`는 각 버킷을 보여줍니다. 각 버킷에는 `scope`(`connection` 또는 `account`), `resource`, `limit`, `remaining`, `resets_at`이 포함됩니다.
* 갱신 또는 재연결을 위해 고객이 Bank Link에 참여하고 있는 동안에는 조회가 제한되지 않습니다.
* 하루 예산을 모두 사용하면 API는 `Retry-After` 헤더(예산이 재설정될 때까지 남은 초)와 `live_syncs_left_today` 및 `budgets`가 포함된 `sync` 객체와 함께 `429 refresh_limit_reached`로 응답합니다. 그 시간만큼 기다리고, 그동안에는 자동 동기화에 의존하십시오.
* 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/ko/use-cases/renew-bank-consent.md). |

## 관련 문서

* [회계를 위한 지속적인 은행 피드](https://docs.didit.me/ko/use-cases/bank-data-for-accounting.md)
* [은행 webhook](https://docs.didit.me/ko/core-technology/bank-verification/webhooks.md)


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