> ## 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 の銀行データモデル。安定したIDを持つ口座、型付きの残高、計上済みと保留中の取引、永続カーソルを使う変更フィードを解説します。

Didit の銀行データAPIは、各接続のアカウント、残高、取引を保存し、ページネーション付きの読み取りエンドポイントを通じて提供します（一覧では`cursor`、取引の読み取りでは`page_token`を使用）。
金額は小数の文字列で表され、通貨はISO 4217の`currency`フィールドで別に示されます。
日付はISO 8601形式で、国はISO alpha-3の国コードで表されます。
読み取りに対して課金されることは一切ありません。

## 口座

`GET /v3/bank/connections/{id}/accounts/` は接続の口座一覧を取得し、`GET /v3/bank/accounts/{account_id}/` は1件の口座を返します。

| フィールド | 意味 |
| - | - |
| `id` | 接続に紐づき、接続が存在する限り変わりません。更新時も同じです。 |
| `account_ref` | 同一アプリケーションおよび同一環境内の複数の接続をまたいで、同じ銀行口座を識別します。銀行の識別子をキー付きハッシュにしたもので、銀行が信頼できる識別子を提供しない場合は`null`になります。 |
| `type`, `usage` | 口座の種類と利用目的です。種類は`current`、`savings`、`card`、`loan`、`investment`、`other`のいずれかです。利用目的は`personal`、`business`、`unknown`のいずれかです。 |
| `identifiers` | IBAN、BIC、その他の識別子です。銀行データに関する権限を持つサーバーサイドからの呼び出し元は、これらを完全な形で受け取ります。 |
| `holders[]` | 各名義人の`name`と`role`です。名義人の役割は`holder`、`joint_holder`、`representative`、`unknown`のいずれかです。 |
| `sync.last_synced_at` | Diditが銀行からデータを最後に取得した日時です。お客様が最後にデータを読み取った日時ではありません。 |
| `history_coverage` | 要求した履歴のうち、銀行から提供された範囲です。`requested_from`、`oldest_booking_date`、`covered_ranges`、`missing_ranges`と、`complete`、`partial`、`empty`、`unavailable`、`unknown`のいずれかの`status`を含みます。 |

人が同じ銀行口座を再度接続したときにその口座を識別するには`account_ref`を、1つの接続内のあらゆる処理には`id`を使用してください。

## 残高

`GET /v3/bank/accounts/{account_id}/balances/` は、基準日付きの種別付き残高を返します。

```json theme={null}
{
  "account_id": "a71f0c2e-...",
  "balances": [
    { "type": "booked", "amount": "18250.34", "currency": "EUR", "reference_date": "2026-11-20" },
    { "type": "available", "amount": "17990.34", "currency": "EUR", "reference_date": "2026-11-21" }
  ],
  "last_synced_at": "2026-11-21T12:04:40Z"
}
```

`type` は `booked`、`available`、`expected` のいずれかです。`iso_type` には、銀行が提供している場合にその銀行の ISO 20022 コードが入ります。

## 取引

`GET /v3/bank/accounts/{account_id}/transactions/`は日付範囲を読み取ります。
`date_from`と`date_to`（銀行が報告する暦日で、両端を含みます）、`status`（既定では`booked`と`pending`の両方）、`limit`（最大500）、`page_token`を受け付けます。
並び順は`effective_date`の降順、次に`id`です。

```json theme={null}
{
  "id": "8f2b...",
  "status": "booked",
  "booking_date": "2026-11-19",
  "value_date": "2026-11-20",
  "amount": "-1210.00",
  "currency": "EUR",
  "direction": "debit",
  "description": "RECIBO SEGURIDAD SOCIAL",
  "counterparty": { "name": "TESORERIA GENERAL SEG SOCIAL", "iban": "ES7620770024003102575766" },
  "remittance": { "unstructured": ["RECIBO SEGURIDAD SOCIAL 10/2026"], "reference": "0028123456789" },
  "bank_transaction_code": "PMNT-RDDT-ESDD",
  "bank_reference": "2026111900012345",
  "identity_quality": "bank_reference",
  "balance_after": "18250.34",
  "category": "taxes_and_social_security"
}
```

* **`id`**は、Didit​が発行するもので、初めて確認された時点で保存されます。同じ取引は、読み取り、同期、更新をまたいでも同じidを保ちます。
* **`identity_quality`**は、この保証の強さを示します。`bank_reference`と`route_id`は安定しています。`derived`は、取引が内容によって照合されたことを意味します。そのため、銀行による訂正は`removed`1件と`added`1件として表示される場合があります。
* **`status`**は`booked`または`pending`です。保留中の取引には独自のidがあります。銀行が計上すると、計上済みの取引は`added`として届き、保留中の取引は`reason: pending_booked`付きの`removed`として届きます。`pending_id`は、銀行がこの2件を紐付けている場合にのみ設定されます。
* **`amount`**は符号付きです。負の値は支出を意味します。`direction`は同じ符号を示します。
* **`bank_reference`**は銀行の変更不可の記帳参照番号で、銀行が提供しない場合は`null`になります。Didit がこの値を生成することはありません。
* **`category`**は、該当する場合に Didit が独自に行う分類です。
* 計上済みの取引に対する銀行による訂正は`modified`になります。取消は新しい取引であり、銀行が紐付けている場合は`reverses_id`が設定されます。

### 銀行が送信しないフィールドはnullになります

銀行が送信しないフィールドは、すべて`null`になります。
金融機関は、送信することが分かっているフィールドを`transaction_fields`に記載します。また、`pending_transactions`、`pending_linkage`、`balance_types`、`history_days_max`も記載するため、本番環境で欠落に後から気づくことがありません。
項目の少ない銀行を想定してコードをテストするには、[サンドボックス](https://docs.didit.me/ja/core-technology/bank-verification/sandbox.md)の`sparse_fields`テスト用顧客を使用してください。

### 日付範囲のページング

`has_more`がtrueの間は、`page_token`を使って読み取りを続けます。
トークンは、読み取りのスナップショットを1時間固定します。最初のページの後に追加された取引はそのスナップショットに含まれません。各行は現在の状態で返されます。ページング中に削除された行は後続のページから除外され、変更フィードに表示されます。
期限切れのトークンは`410 page_expired`で応答します。その場合は、元のクエリから読み取りをやり直してください。

## 変更フィード

`GET /v3/bank/connections/{id}/transactions/sync/` は、`cursor`以降に接続のすべての口座で変更された内容を返します。

```json theme={null}
{
  "added": [ { "id": "...", "status": "booked", "amount": "-35.00" } ],
  "modified": [],
  "removed": [ { "id": "...", "reason": "pending_booked" } ],
  "has_more": false,
  "next_cursor": "...",
  "reset": false
}
```

* 空の cursor を指定すると、現在のすべての取引が`reset: true`付きの`added`として返されます。取引を追加するのではなく、保存しているコピーをこの内容で置き換えてください。
* `has_more`がtrueの間は、`page_token`を使って取得を続けてください。`has_more: false`のレスポンスを受け取った後にのみ`next_cursor`を保存してください。途中でページの取得に失敗した場合は、保存済みの cursor から再開してください。
* cursor は不透明な値で、接続と環境に紐づきます。変更ログは90日間再生可能です。それより古い cursor には、`410 cursor_expired`と`bootstrap: true`が返されます。その場合は空の cursor から最初からやり直し、保存しているコピーを置き換えてください。
* `removed[].reason`は、`pending_booked`、`pending_expired`、`bank_removed`、`access_removed`のいずれかです。

段階的な手順は[会計向けの継続的な銀行フィード](https://docs.didit.me/ja/use-cases/bank-data-for-accounting.md)にあります。

## ヘッダー

取引データを取得する2つの読み取りAPIは、`X-RateLimit-*` ヘッダーと `X-Bank-Last-Synced-At` を返します（アプリケーションあたり1分間に600回の読み取りと300回の書き込みまで。これを超えると、`Retry-After` ヘッダーを含む429が返されます）。
APIのレート制限と、銀行によるデータ取得の制限は別のものです。詳しくは[銀行データをオンデマンドで更新する](https://docs.didit.me/ja/use-cases/refresh-bank-data-on-demand.md)をご覧ください。


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