> ## 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 のテスト銀行について、サンドボックスアプリケーションから口座・残高・取引を取得するまでの手順を解説します。APIキーとリンクの作成、接続、読み取り、同期、削除まで扱います。

> [!NOTE]
>
> 以下のレスポンスはすべて、重要なフィールドのみを含むように省略しています。
> APIキーはサーバー側に保管してください。ブラウザやアプリに届くことはありません。

銀行データは、サンドボックスのアプリケーションでご利用いただけます。
本番環境のアプリケーションからの呼び出しは、本番環境での利用が発表されるまで`404`を返します。サンドボックスでは料金は発生しません。
このクイックスタートでは、サンドボックスのアプリケーションから、コピー&ペーストで実行できるリクエストを使って、Didit Test Bankの口座、残高、取引までを確認できます。

## ステップ1: Bank data権限を付与したAPIキーを作成する

Bank dataはフルアクセスには含まれません。
アプリケーションのプライマリシークレットを含むフルアクセスのキーは、Bank dataに関するすべての呼び出しで`403 bank_data_access_denied`により拒否されます。

1. [Business Console](https://business.didit.me)で、サンドボックスアプリケーションを開き、**API keys**に移動します。
2. カスタムアクセスでキーを作成し、**Bank data**を追加します。読み取りには**Read**、何かを作成、変更、削除する呼び出しには**Write**を設定します。
3. キーをコピーし、エクスポートします：

```bash theme={null}
export DIDIT_API_KEY="your-sandbox-key"
```

すべてのリソースの一覧は[APIキー](https://docs.didit.me/ja/console/api-keys.md)を参照してください。

## ステップ2: リンクを作成する

リンクは、エンドユーザーが銀行を接続する画面を1回分実行したものです。
Test Bank向けに、継続的なリンクを作成します：

```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",
    "data": ["accounts", "balances", "transactions"],
    "history_days": 90,
    "vendor_data": "client-7731"
  }'
```

`country` は、エンドユーザーの銀行がある国の3文字の国コードです。省略可能です。
わかっている場合に送信すると、エンドユーザーにはその国の銀行だけが表示されます。送信しない場合は、対応している全ての国の中から選択することになります。
1回限りのアクセスにする場合は、`"access": "one_time"` を送信します（デフォルト）。

```json theme={null}
{
  "id": "0b9c4f1e-6a2d-4e8b-9f31-7c5d2e1a8b40",
  "mode": "connect",
  "access": "ongoing",
  "status": "created",
  "url": "https://verify.didit.me/bank/link/...",
  "expires_at": "2026-11-22T13:00:00Z",
  "connection_id": null
}
```

リンクの `id` は、ユーザーと紐づけて保存してください。
`url` と `client_token` は、リンクの作成時に一度だけ返されます。

## ステップ3: リンクを開き、Didit Test Bankに接続する

ブラウザで`url`を開くか、メールまたはチャットで本人に送ります。
本人には同意画面が表示され、**Didit Test Bank**を選択し、テスト用の顧客のいずれかでサインインして、共有する口座を選びます。
テスト用の顧客と、それぞれから取得できるデータは[サンドボックスのページ](https://docs.didit.me/ja/core-technology/bank-verification/sandbox.md)に掲載されています。

完了後に本人をお客様のサイトに戻す方法は、[お客様のサイトに戻す](https://docs.didit.me/ja/integration/bank-link/return-to-your-site.md)を参照してください。
`redirect_url`を指定しない場合、本人はDiditの結果ページで手続きを完了し、結果はWebhookまたは読み取りリクエストで確認できます。

## ステップ4: Webhookを受信して確認する

コンソールで`bank.*`イベントの送信先を登録してください。他の[Webhook](https://docs.didit.me/ja/integration/webhooks.md)と同様です。
エンドユーザーの操作が完了すると、`link_id`と`connection_id`を含む`bank.link.completed`が届きます。その後、最初の同期でアカウントが保存されると`bank.connection.created`が届きます。

ブラウザから送られてきたリンクIDは信用しないでください。
ご自身でリンクの情報を取得して確認してください：

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

```json theme={null}
{ "id": "0b9c4f1e-6a2d-4e8b-9f31-7c5d2e1a8b40", "status": "completed", "connection_id": "5e1d2a70-3b4c-4d5e-8f60-71829304a5b6" }
```

`status`は`completed`、または最終状態のいずれかです（`cancelled`、`expired`、`failed`）。`failed`のリンクには`error.code`が含まれます。`cancelled`の場合は`error: null`となります。

## ステップ5: 口座、残高、取引を読み取る

```bash theme={null}
curl https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/accounts/ -H "x-api-key: $DIDIT_API_KEY"
curl https://verification.didit.me/v3/bank/accounts/$ACCOUNT_ID/balances/ -H "x-api-key: $DIDIT_API_KEY"
curl "https://verification.didit.me/v3/bank/accounts/$ACCOUNT_ID/transactions/?date_from=2026-01-01" -H "x-api-key: $DIDIT_API_KEY"
```

金額は10進数の文字列で、支出はマイナスの値になります。
取引のページには、まだ読み取るデータがある間`next_page_token`が含まれます。
[口座、残高、取引](https://docs.didit.me/ja/core-technology/bank-verification/accounts-balances-transactions.md)を参照してください。

## ステップ6: 変更フィードを追跡する

変更フィードは、前回の読み取り以降に変更された内容のみを返します。
カーソルを指定しない最初の読み取りでは、完全なスナップショットが返されます。これには接続が持つすべての取引が含まれ、それぞれ`added`として返され、レスポンスには`reset: true`が付きます。
最初のページには`has_more: true`と`next_page_token`が含まれ、この時点ではまだ`next_cursor`がない場合があります。`has_more`が`true`の間は`page_token`を使って読み取りを続け、`has_more: false`のページ（最後のページ）の`next_cursor`を保存して次回に使用してください:

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

`reset: true`は、レスポンスが完全なスナップショットであることを意味します。レスポンスを追加するのではなく、お使いのコピーをそのレスポンスで置き換えてください。
`bank.data.updated`は、同期によって新しい内容が保存されたタイミングを通知します。

## ステップ7: 今すぐ同期する

継続的な接続は、自動的に同期されます。
今すぐ銀行データを読み取るには、同期をリクエストします:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/refresh/ -H "x-api-key: $DIDIT_API_KEY"
```

銀行では、ユーザーの操作を伴わない読み取りの回数が1日あたり制限されています。
接続の `sync.live_syncs_left_today` と `sync.budgets` に、残りの回数とリセットされるタイミングが示されます。上限を超えた呼び出しには、リセット時刻とともに `429 refresh_limit_reached` が返されます。
詳しくは [オンデマンドで銀行データを更新する](https://docs.didit.me/ja/use-cases/refresh-bank-data-on-demand.md) を参照してください。

## ステップ8: アクセスの停止と削除

アクセスの停止と削除は、それぞれ別の呼び出しです。

```bash theme={null}
# Stop access at the bank. The connection keeps its data until you delete it.
curl -X POST https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/revoke/ -H "x-api-key: $DIDIT_API_KEY"

# Delete the connection and its data. Irreversible.
curl -X DELETE https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/ -H "x-api-key: $DIDIT_API_KEY"
```

削除された接続のレスポンスに含まれるのは、`id`、`status`、`status_reason`、`created_at`、`erasure` のみです。
詳しくは [データ、同意、削除](https://docs.didit.me/ja/core-technology/bank-verification/data-consent-and-deletion.md) をご覧ください。

## 次のステップ

* [接続](https://docs.didit.me/ja/core-technology/bank-verification/connections.md): 一回限りのアクセスと継続的なアクセス、同意、更新について。
* [銀行関連のWebhook](https://docs.didit.me/ja/core-technology/bank-verification/webhooks.md)
* [料金](https://docs.didit.me/ja/getting-started/bank-verification-pricing.md)
* [APIリファレンス](https://docs.didit.me/ja/standalone-apis/bank-data.md)


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