Позиция 3: API истории операций (GET /api/transactions)

Назначение

Эндпоинт /api/transactions предоставляет список транзакций с учётом фильтров, сортировки и пагинации для отображения в SPA (таблица "История операций").

Метод и URL

Метод: GET
URL: /api/transactions

Параметры запроса (query)

Все параметры опциональны, если не указано иное.

accountId: number — идентификатор счёта (accounts.id). Если не передан, выбираются транзакции по всем счетам.
from: string — дата начала периода (включительно) в формате YYYY-MM-DD.
to: string — дата конца периода (включительно) в формате YYYY-MM-DD.
direction: string — направления движения, одно или несколько значений через запятую:
- income — приход;
- expense — расход;
- transfer — переводы между счетами. Пример: direction=income,expense.
categoryId: number — идентификатор категории (categories.id).
search: string — строка поиска по полю description (поиск по подстроке, регистронезависимый).
amountMin: number — минимальная сумма операции в копейках (BIGINT).
amountMax: number — максимальная сумма операции в копейках (BIGINT).
onlyUnconfirmed: boolean — если true, возвращаются только транзакции с неподтверждённой категорией (is_category_confirmed = FALSE).
sortBy: string — поле сортировки:
- date — сортировка по operation_at;
- amount — сортировка по amount_signed.
sortOrder: string — порядок сортировки: asc или desc.
page: number — номер страницы, начиная с 1. По умолчанию 1.
pageSize: number — размер страницы (количество записей на странице). Допустимые значения: 10, 50, 100. По умолчанию 50.

Структура ответа

Ответ содержит массив транзакций и данные пагинации.

{
  "items": [
    {
      "id": 123,
      "operationAt": "2026-02-26T14:06:57+03:00",
      "accountId": 1,
      "accountAlias": "Текущий",
      "amountSigned": -50000,
      "commission": 0,
      "description": "Оплата товаров и услуг. OZON.RU. по карте *2249",
      "direction": "expense",
      "categoryId": 5,
      "categoryName": "Дом",
      "isCategoryConfirmed": false,
      "comment": "еда"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "totalItems": 874,
  "totalPages": 18
}

Поля элементов items:

id — идентификатор транзакции (transactions.id).
operationAt — дата и время операции в формате ISO 8601 (из transactions.operation_at).
accountId — идентификатор счёта (accounts.id).
accountAlias — алиас счёта (accounts.alias). Если алиас не задан, можно возвращать null или сгенерированное значение.
amountSigned — сумма операции в копейках.
commission — комиссия по операции в копейках.
description — описание операции из банка.
direction — направление транзакции (income / expense / transfer).
categoryId — идентификатор категории (categories.id), может быть null.
categoryName — имя категории (categories.name), может быть null.
isCategoryConfirmed — признак того, что категория подтверждена пользователем.
comment — пользовательский комментарий к транзакции.

Поля пагинации:

page — текущая страница.
pageSize — размер страницы.
totalItems — общее количество транзакций, удовлетворяющих фильтрам.
totalPages — общее количество страниц при заданном pageSize.

Замечания по реализации

Справочные данные (accountAlias, categoryName) могут возвращаться либо сразу в ответе, либо SPA может подставлять их по accountId и categoryId из кэшированных справочников, полученных через отдельные эндпоинты (/api/accounts, /api/categories).
Фильтрация по search выполняется по полю description (ILIKE %search%).
Фильтры по сумме (amountMin, amountMax) применяются к amount_signed.
Параметр onlyUnconfirmed=true добавляет условие is_category_confirmed = FALSE.
Комбинация sortBy=date&sortOrder=desc используется как значение по умолчанию (последние операции сверху).

5.6 KiB Raw Blame History Unescape Escape