> ## 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, типизированные балансы, проведённые и ожидающие транзакции, лента изменений с курсором.

API банковских данных Didit хранит счета, балансы и транзакции каждого подключения и отдаёт их через endpoint'ы для чтения с пагинацией (`cursor` для списков, `page_token` для чтения транзакций).
Суммы передаются десятичными строками с отдельным полем `currency` в формате ISO 4217, даты указываются в формате ISO 8601, а страны указываются в формате ISO alpha-3.
Запросы на чтение никогда не тарифицируются.

## Счета

`GET /v3/bank/connections/{id}/accounts/` возвращает список счетов подключения, а `GET /v3/bank/accounts/{account_id}/` возвращает один счёт.

| Поле | Значение |
| - | - |
| `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` и `status` со значениями `complete`, `partial`, `empty`, `unavailable` или `unknown`. |

Используйте `account_ref`, чтобы распознать банковский счёт, когда человек подключает его повторно, а `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` и одна запись `added`.
* **`status`** принимает значения `booked` или `pending`. У транзакции в ожидании свой id. Когда банк проводит её, проведённая транзакция приходит как `added`, а транзакция в ожидании приходит как `removed` с `reason: pending_booked`. `pending_id` заполняется только там, где банк связывает эти записи.
* **`amount`** имеет знак: отрицательное значение означает списание. `direction` повторяет знак.
* **`bank_reference`**: неизменяемая ссылка на запись банка; равна `null`, если банк её не передаёт. Didit никогда не формирует её сам.
* **`category`**: собственная категоризация Didit, когда она применима.
* Исправление банком проведённой транзакции помечается как `modified`. Сторно создаёт новую транзакцию; `reverses_id` заполняется, если банк связывает её с исходной.

### Поля, которые банк не передаёт, равны null

Каждое поле, которое банк не передаёт, имеет значение `null`.
Учреждение перечисляет поля, которые, как известно, передаются, в `transaction_fields`, а также в `pending_transactions`, `pending_linkage`, `balance_types` и `history_days_max`, чтобы пробелы не обнаруживались в продакшне.
Чтобы проверить свой код на банке, который передаёт мало данных, используйте тестового клиента `sparse_fields` в [песочнице](https://docs.didit.me/ru/core-technology/bank-verification/sandbox.md).

### Постраничное чтение диапазона дат

Продолжайте чтение с `page_token`, пока `has_more` равен true.
Токен фиксирует снимок данных запроса на один час: добавления, появившиеся после первой страницы, в него не входят; каждая строка возвращается в текущем состоянии; строка, удалённая во время постраничного чтения, выпадает из последующих страниц и появляется в ленте изменений.
Истёкший токен возвращает ответ `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
}
```

* Пустой курсор возвращает все текущие транзакции как `added` с `reset: true`. Замените ими свою копию, а не добавляйте их к ней.
* Продолжайте постраничную выборку с помощью `page_token`, пока `has_more` равен true. Сохраняйте `next_cursor` только после ответа с `has_more: false`. Если при постраничной выборке произошла ошибка, начните заново с ранее сохранённого курсора.
* Курсор непрозрачен и привязан к подключению и среде. Журнал изменений можно воспроизводить повторно в течение 90 дней. Более старый курсор возвращает `410 cursor_expired` с `bootstrap: true`: начните заново с пустого курсора и замените свою копию.
* `removed[].reason` принимает значения `pending_booked`, `pending_expired`, `bank_removed` или `access_removed`.

Пошаговое описание есть в разделе [Непрерывная банковская лента для бухгалтерии](https://docs.didit.me/ru/use-cases/bank-data-for-accounting.md).

## Заголовки

Оба запроса на чтение транзакций возвращают заголовки `X-RateLimit-*` (600 запросов на чтение и 300 на запись в минуту на приложение, при превышении возвращается код 429 с заголовком `Retry-After`) и `X-Bank-Last-Synced-At`.
Лимиты API и собственные лимиты банка на получение данных различаются: см. раздел [Обновление данных банка по запросу](https://docs.didit.me/ru/use-cases/refresh-bank-data-on-demand.md).


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