> ## 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を受信し、カーソルを使って変更があった分だけを読み取り、同意の期限切れを監視し、顧客が利用を終了したときに、接続を停止または削除できます。

このガイドでは、ゼロの状態から、1人の顧客向けに毎日フィードを取得するまでの手順を説明します。
同じコードをすべての顧客に使用できます。必要になるのは、顧客と銀行ごとに1つの接続だけです。

## 必要なもの

* サンドボックス用アプリケーションの、銀行データ権限を持つAPIキー。[クイックスタート](https://docs.didit.me/ja/core-technology/bank-verification/quickstart.md#ステップ1-bank-data権限を付与したapiキーを作成する)を参照してください。
* `bank.*`イベントを受信するWebhookの送信先。[銀行データのWebhook](https://docs.didit.me/ja/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/ja/integration/bank-link/hosted-link.md)に案内し、[リダイレクトURL](https://docs.didit.me/ja/integration/bank-link/return-to-your-site.md)で貴社のプロダクトに戻します。

リンクの`id`をクライアントとともに保存してください。

## ステップ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` として1回ずつ返します。ページを読み取っている間に同期が実行されても、この点は変わりません。
* ページを読み取っている間に行われた変更は、`next_cursor` からの次の読み取りで返されます。受け取り済みの取引は `modified` として再度返され、新しい取引は `added` として返されます。
* `has_more: false` を含むレスポンスを受け取った後にのみ、`next_cursor` を保存してください。
* ページの読み取りが途中で失敗した場合は、保存しておいたカーソルから読み取りをやり直してください。
* 残高は `GET /v3/bank/accounts/{account_id}/balances/` で読み取ります。

## ステップ4: すべてのWebhookで最新状態を維持する

Didit は、有効な継続中の接続をすべて、銀行によって異なりますが1日に1〜4回、自動で同期します（`sync.frequency_per_day`）。
同期で変更が保存されると、`bank.data.updated` が`connection_id`、`account_ids`、件数とともに届きます。
保存済みのカーソルを使って変更フィードを呼び出します:

* `added` は新しい取引です。保留中の取引も含まれます。
* `modified` は変更された取引で、現在の状態で届きます。それぞれ`id`を基準にアップサートしてください。既に保持している取引は更新し、まだ保持していない取引は追加します。
* `removed` には`reason`が付いています。手元にない`id`は無視してください。保留中の取引が計上されると、その取引は`pending_booked`の理由付きで`removed`に入り、計上された取引は`added`で届きます。

取引の`id`をキーとして使用してください。読み取り、同期、更新をまたいでも変わりません。
`identity_quality`を確認してください。値が`derived`の場合、銀行による訂正が`removed`1件と`added`1件として表示されることがあります。
読み取りは課金されませんが、データが変わるのは同期が実行されたときだけです。そのため、Webhookごとに1回の読み取りで十分です。
より早く取得するには、Sync Nowを使用してください: [オンデマンドで銀行データを更新](https://docs.didit.me/ja/use-cases/refresh-bank-data-on-demand.md)

## Step 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/ja/standalone-apis/bank-connection-renew)を呼び出してください。残りが30日になるまでは、`409 renewal_not_needed` で応答します。
エンドユーザーが同意の更新を完了するページは、まだ提供されていません。

エンドユーザーが同意を失効させたままにした場合、接続は `renewal_required` になります。同期済みのデータは引き続き読み取れます。
詳細は[銀行同意の更新](https://docs.didit.me/ja/use-cases/renew-bank-consent.md)をご覧ください。

## ステップ7: アクセスを停止して削除する

* 顧客が貴社の製品の利用をやめた場合は、[`revoke_connection`](https://docs.didit.me/ja/standalone-apis/bank-connection-revoke)を呼び出して直ちにデータの読み取りを停止するか、[`delete_connection`](https://docs.didit.me/ja/standalone-apis/bank-connection-delete)を呼び出して読み取りを停止し、保存済みのデータを削除してください。
* 顧客が銀行側での共有を停止すると、`bank.connection.revoked` イベントが `ended_by` 付きで届きます。その連携のフィードを停止してください。

## 料金

継続的アクセスは、有効な接続1件あたり月額で課金されます。
この料金には、接続内のすべての口座、残高、取引、銀行が提供する場合は最大365日分の履歴、自動同期、銀行の上限内でのライブ同期、更新、Webhook、およびすべての読み取りが含まれます。
誰も完了しなかったリンクは無料です。`renewal_required`、`paused`、`revoked`の接続も無料です。
詳しくは[料金](https://docs.didit.me/ja/getting-started/bank-verification-pricing.md#銀行データと継続アクセス)をご覧ください。

## チェックリスト

* [ ] 顧客と銀行ごとに1つの連携を、そのカーソルと同意の終了日とともに保存する。
* [ ] Webhookハンドラーを冪等にし、イベントIDをキーにする。
* [ ] `reset: true`では、お使いのコピーを置き換え、追記はしない。
* [ ] `removed`を、その理由とともに処理する。
* [ ] 同意のリマインダーを、御社から顧客へ送る通知と連携させる。
* [ ] `bank.connection.revoked`を受け取ったら、フィードを停止する。
* [ ] [サンドボックス](https://docs.didit.me/ja/core-technology/bank-verification/sandbox.md#優れたテスト計画)のプランのテストに合格する。


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