> ## 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으로 고객별 잔액과 거래 내역의 일일 피드를 구축하세요. 지속 연결, webhook, 커서 기반 변경 피드, 재설정, 동의 종료, 중지 방법을 다룹니다.

지속적인 은행 데이터 피드는 고객이 다시 로그인하지 않아도 회계 또는 장부 기장 애플리케이션에 각 고객의 은행 계좌 잔액과 거래 내역을 매일 제공합니다.
Didit을 사용하면 지속적인 액세스 권한이 있는 링크를 만들고, 새 데이터가 도착하면 webhook을 받고, 커서로 변경된 내용만 읽고, 동의가 언제 종료되는지 확인하고, 고객이 떠날 때 연결을 중지하거나 삭제할 수 있습니다.

이 가이드는 고객 한 명에 대한 매일 피드를 처음부터 설정하는 과정을 안내합니다.
같은 코드를 모든 고객에게 사용하며, 고객과 은행마다 연결을 하나씩 만듭니다.

## 필요한 항목

* 샌드박스 애플리케이션에서 사용할 은행 데이터 권한이 있는 API 키. 자세한 내용은 [빠른 시작](https://docs.didit.me/ko/core-technology/bank-verification/quickstart.md#1단계-bank-data-권한으로-api-키-만들기)을 참고하세요.
* `bank.*` 이벤트를 수신하는 webhook 대상. [은행 webhook](https://docs.didit.me/ko/core-technology/bank-verification/webhooks.md)을 참고하세요.
* 고객별 연결 ID, 변경 피드 커서, 동의 종료 시점을 저장할 데이터베이스 테이블.

## 1단계: 지속적인 접근 권한으로 링크 만들기

```bash theme={null}
curl -X POST https://verification.didit.me/v3/bank/links/ \
  -H "x-api-key: $DIDIT_API_KEY" -H "content-type: application/json" \
  -d '{
    "access": "ongoing",
    "country": "ESP",
    "segment": "business",
    "data": ["accounts", "balances", "transactions"],
    "history_from": "2026-01-01",
    "consent_days": 180,
    "ownership": { "compare": "none" },
    "end_user": { "reference": "client-7731", "email": "ana@example.com" },
    "redirect_url": "http://localhost:3000/bank/return",
    "vendor_data": "client-7731"
  }'
```

* `access: ongoing`은 동의가 끝날 때까지 접근을 유지합니다. `consent_days`는 요청 값입니다. 실제 만료일은 은행이 결정하며 연결 정보에 표시됩니다.
* `history_from`은 특정 날짜(예: 올해 초)부터의 내역을 요청합니다. 대신 `history_days`(1\~365)를 사용할 수 있으며, 두 값을 함께 사용해서는 안 됩니다. 은행이 요청한 만큼의 내역을 제공하지 않을 수 있으므로, 각 계좌의 `history_coverage`에서 실제 제공 범위를 확인하십시오.
* `ownership.compare: none`을 설정하면 계좌 소유자 비교를 건너뛰므로 기준 신원 정보가 필요하지 않습니다. Didit에서 인증된 기업과 계좌 소유자를 비교하려면 `business`를 사용하십시오.
* `end_user.reference`는 최종 사용자를 식별하는 귀사의 ID입니다. 검색할 수 있으며, Didit이 같은 최종 사용자가 같은 계좌를 다시 연결하는 경우를 인식할 수 있게 해 줍니다.
* 최종 사용자를 [호스팅 인증 페이지](https://docs.didit.me/ko/integration/bank-link/hosted-link.md)로 안내하고, [리디렉션 URL](https://docs.didit.me/ko/integration/bank-link/return-to-your-site.md)을 통해 제품으로 돌려보내십시오.

연결 `id`를 최종 사용자와 함께 저장하십시오.

## Step 2: 연결 완료 대기

고객이 절차를 마치면 `connection_id`와 함께 `bank.link.completed`가 전송됩니다.
브라우저는 신뢰할 수 없으므로 서버에서 이를 확인하세요:

```bash theme={null}
curl https://verification.didit.me/v3/bank/links/$LINK_ID/ -H "x-api-key: $DIDIT_API_KEY"
```

`connection_id`를 저장하고 `bank.connection.created`를 기다리세요. 이 이벤트가 도착하면 계좌, 잔액, 최근 거래 내역을 읽을 수 있습니다(`sync.initial_status`가 `succeeded` 또는 `partial`인 경우).
과거 데이터 보완 수집이 끝나면 `bank.connection.history_complete`가 전송됩니다.
각 계좌에 대해 `history_coverage.oldest_booking_date`는 은행이 실제로 제공한 데이터가 언제까지 거슬러 올라가는지 알려 줍니다.

## 3단계: 첫 번째 사본 불러오기

빈 커서로 요청하면 현재 모든 거래가 `reset: true`와 함께 `added`로 반환됩니다.
페이지를 넘기며 모두 읽고, 커서는 마지막에만 저장합니다:

```bash theme={null}
curl "https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/transactions/sync/?limit=500" \
  -H "x-api-key: $DIDIT_API_KEY"
```

```python theme={null}
cursor, page_token = stored_cursor or "", None
while True:
    params = {"limit": 500, "page_token": page_token} if page_token else {"cursor": cursor, "limit": 500}
    page = get(f"/v3/bank/connections/{connection_id}/transactions/sync/", params)
    if page["reset"] and not page_token:
        wipe_local_copy(connection_id)       # replace, never append
    apply(page["added"], page["modified"], page["removed"])
    if not page["has_more"]:
        store_cursor(connection_id, page["next_cursor"])
        break
    page_token = page["next_page_token"]
```

* 첫 번째 읽기는 실제 스냅샷입니다. 읽기가 시작된 시점에 연결에 있던 모든 거래를 정확히 한 번씩 `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` 기준 upsert로 적용하십시오. 이미 보유한 거래는 업데이트되고, 아직 보유하지 않은 거래는 추가됩니다.
* `removed`에는 `reason`이 포함됩니다. 보유하지 않은 `id`는 무시하십시오. 보류 중인 거래가 확정되면 `pending_booked`와 함께 `removed`에 포함되어 빠지고, 확정된 거래는 `added`로 도착합니다.

거래 `id`를 키로 사용하십시오. 이 값은 조회, 동기화, 갱신 전반에서 동일하게 유지됩니다.
`identity_quality`를 확인하십시오. `derived`인 경우 은행의 정정이 `removed` 한 건과 `added` 한 건으로 나타날 수 있습니다.
조회에는 요금이 청구되지 않습니다. 다만 데이터는 동기화가 실행될 때만 바뀌므로 webhook마다 한 번 조회하면 충분합니다.
더 빨리 가져오려면 Sync Now를 사용하십시오: [요청 시 은행 데이터 새로 고침](https://docs.didit.me/ko/use-cases/refresh-bank-data-on-demand.md).

## 5단계: 재설정 처리

재생 기간보다 오래된 커서는 `bootstrap: true`와 함께 `410 cursor_expired`로 응답합니다.
변경 로그는 90일 동안 재생할 수 있으므로 일일 작업에서는 이런 경우가 드뭅니다.
빈 커서에서 다시 시작하고, 기존 사본에 결과를 추가하지 말고 결과로 교체하세요.
빈 커서에서 수행한 모든 읽기에는 `reset: true`가 포함되므로, 새 연결과 만료된 커서를 같은 코드 경로로 처리할 수 있습니다.

## 6단계: 동의 만료 모니터링

동의에는 만료 날짜가 있으며, 이 값은 `consent.expires_at`입니다.
Didit은 만료 14일, 7일, 1일 전에 `bank.connection.consent_expiring` 이벤트를 보냅니다.

갱신하려면 [`renew_connection`](https://docs.didit.me/ko/standalone-apis/bank-connection-renew)을 호출합니다. 남은 기간이 30일이 되기 전까지는 `409 renewal_not_needed`로 응답합니다.
고객이 갱신을 완료하는 페이지는 아직 제공되지 않습니다.

고객이 갱신하지 않고 동의가 만료되도록 두면 연결 상태는 `renewal_required`가 됩니다. 이 경우에도 동기화된 데이터는 여전히 조회할 수 있습니다.
자세한 내용은 [은행 동의 갱신](https://docs.didit.me/ko/use-cases/renew-bank-consent.md)을 참고하세요.

## 7단계: 접근 중지 및 삭제

* 고객이 제품을 떠나면 [`revoke_connection`](https://docs.didit.me/ko/standalone-apis/bank-connection-revoke)을 호출하여 즉시 데이터 읽기를 중지하거나, [`delete_connection`](https://docs.didit.me/ko/standalone-apis/bank-connection-delete)을 호출하여 읽기를 중지하고 저장된 데이터를 삭제합니다.
* 고객이 은행에서 공유를 중단하면 `bank.connection.revoked`가 `ended_by`와 함께 도착합니다. 해당 연결의 피드 수신을 중지하십시오.

## 가격

활성 연결당 월별로 과금됩니다.
이 가격에는 연결의 모든 계정, 잔액, 은행이 제공하는 경우 최대 365일의 거래 내역, 자동 동기화, 은행 한도 내의 실시간 동기화, 갱신, webhook, 모든 조회가 포함됩니다.
아무도 완료하지 않은 링크는 무료이며, `renewal_required`, `paused`, `revoked` 상태의 연결도 마찬가지로 무료입니다.
자세한 내용은 [요금](https://docs.didit.me/ko/getting-started/bank-verification-pricing.md#은행-데이터-및-지속-접근)을 참고하세요.

## 체크리스트

* [ ] 고객과 은행마다 연결 하나를 두고, 커서와 동의 종료일을 함께 저장합니다.
* [ ] webhook 핸들러는 이벤트 ID를 기준으로 멱등하게 동작합니다.
* [ ] `reset: true`는 사본을 교체하며, 절대 추가하지 않습니다.
* [ ] `removed`는 사유와 함께 처리합니다.
* [ ] 동의 리마인더를 고객에게 보내는 자체 알림과 연결합니다.
* [ ] `bank.connection.revoked`를 받으면 피드를 중단합니다.
* [ ] [샌드박스](https://docs.didit.me/ko/core-technology/bank-verification/sandbox.md#좋은-테스트-계획) 요금제 테스트를 통과합니다.


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