Kaspi Statement Analyzer

Локальный анализатор PDF-выписок Kaspi Gold. Скрипт извлекает операции из таблиц выписки, отделяет переводы между своими счетами, определяет входящие и исходящие переводы, классифицирует покупки и создаёт удобный HTML-отчёт вместе с CSV и JSON.

PDF и данные операций никуда не отправляются: обработка полностью выполняется на вашем компьютере.

Что создаёт скрипт

После запуска в папке отчёта появятся три файла:

• report.html — готовый визуальный отчёт с итогами, категориями, отправителями, получателями, продавцами и поиском по операциям;
• transactions.csv — все операции в табличном виде; открывается в Excel, Numbers, LibreOffice и Google Sheets;
• summary.json — агрегаты и результат контрольной сверки в машиночитаемом формате.

В отчёте рассчитываются:

• количество и сумма переводов вам;
• количество и сумма ваших переводов другим людям;
• покупки по категориям;
• расходы по месяцам;
• популярные продавцы;
• отправители и получатели переводов;
• снятия, комиссии, возвраты и другие операции;
• отдельные внутренние переводы между Kaspi Gold и собственными счетами;
• продавцы, для которых ещё не назначена категория.

Требования

• Python 3.10 или новее;
• текстовая PDF-выписка Kaspi Gold;
• интернет требуется только один раз для установки библиотеки чтения PDF.

Проверить Python:

python3 --version

Если команда отсутствует, установите Python с python.org или через Homebrew:

brew install python

Быстрый запуск на macOS или Linux

Откройте Terminal и перейдите в папку проекта:

cd kaspi-statement-analyzer

Создайте отдельное виртуальное окружение:

python3 -m venv .venv
source .venv/bin/activate

Установите проект:

python -m pip install --upgrade pip
python -m pip install -e .

Создайте отчёт из выписки:

kaspi-report ~/Downloads/statement.pdf \
  --categories categories.yaml \
  --output report

Откройте файл report/report.html двойным щелчком в Finder или командой:

open report/report.html

Быстрый запуск на Windows

Откройте PowerShell в папке проекта и выполните:

py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .
kaspi-report "C:\Users\Name\Downloads\statement.pdf" --categories categories.yaml --output report

Затем откройте report\report.html в браузере.

Если PowerShell запрещает активацию окружения, один раз выполните:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Запуск без установки команды

После установки зависимостей скрипт также можно запускать как Python-модуль:

python -m kaspi_analyzer /путь/к/выписке.pdf -c categories.yaml -o report

Пути с пробелами необходимо заключать в кавычки:

kaspi-report "/Users/name/Downloads/Kaspi Gold August.pdf" -c categories.yaml -o "reports/August 2026"

Как настроить категории

Kaspi указывает название продавца, но не передаёт в этой выписке банковскую MCC-категорию. Поэтому категории определяются по ключевым словам из файла categories.yaml.

Пример:

Продукты:
  - MAGNUM
  - GALMART

Кафе и рестораны:
  - BURGER KING
  - PIZZA

Правила:

1. Регистр букв не важен: Magnum и MAGNUM считаются одинаковыми.
2. Достаточно указать уникальную часть названия.
3. Категории проверяются сверху вниз. Если подходят два правила, используется первое.
4. Покупки без совпадения попадают в Прочее.

Практичный порядок настройки:

1. Запустите отчёт с готовым categories.yaml.
2. Откройте блок «Продавцы без категории» в report.html.
3. Добавьте характерные части названий в нужные категории.
4. Запустите ту же команду ещё раз. Файлы отчёта будут обновлены.

Можно создавать собственные категории без изменения Python-кода:

Домашние животные:
  - ZOOМАРКЕТ
  - PETSHOP

Образование:
  - COURSERA
  - UDEMY
  - ШКОЛА

Как определяется тип операции

• Пополнение с положительной суммой и именем вида Имя И. — «Перевод мне».
• Перевод — «Мой перевод».
• Перевод на свой счет и Поступление со своего счета — внутреннее движение, которое не считается внешним доходом или расходом.
• Покупка с отрицательной суммой — расход на покупку.
• Положительная Покупка или операция с текстом Возврат — возврат/отмена.
• Снятие — снятие наличных.
• Разное — комиссия или другая служебная операция.

Определение переводов вам основано на формате имени в PDF. Пополнение через банкомат, с карты другого банка или из другого сервиса будет отмечено как «Другое пополнение».

Контроль правильности

В начале выписки Kaspi размещает краткую сводку по типам операций. Скрипт независимо суммирует все извлечённые строки и сверяет:

• начальный остаток + все операции = конечный остаток;
• пополнения;
• поступления со своих счетов;
• переводы;
• переводы на свои счета;
• покупки;
• снятия;
• операции «Разное».

Результат отображается вверху report.html и подробно — в блоке «Проверка по сводке Kaspi». Если есть расхождение, не используйте статистику до проверки исходного PDF.

Работа с CSV в Excel

transactions.csv записывается в UTF-8 с BOM, разделитель — точка с запятой, десятичный разделитель — запятая. Для русской локали Excel файл обычно открывается корректно двойным щелчком.

Если Excel поместил всю строку в одну колонку:

1. Откройте вкладку «Данные».
2. Выберите «Из текста/CSV».
3. Укажите кодировку UTF-8.
4. Выберите разделитель ;.
5. Загрузите таблицу.

Повторное использование

Для новой выписки достаточно изменить путь к PDF и, при желании, папку результата:

kaspi-report ~/Downloads/new_statement.pdf -c categories.yaml -o reports/2026-09

Каждый отчёт лучше сохранять в отдельную папку. Текущая версия обрабатывает одну выписку за запуск и не объединяет пересекающиеся периоды автоматически.

Проверка проекта

Запуск встроенных тестов без дополнительных библиотек:

python -m unittest discover -s tests -v

Проверка справки CLI:

kaspi-report --help
kaspi-report --version

Частые проблемы

«В PDF не найдена таблица операций»

Скорее всего, это скан или PDF другого формата. Поддерживается официальная текстовая выписка Kaspi Gold с колонками «Дата», «Сумма», «Операция», «Детали». Для сканов потребуется отдельный OCR-режим.

«PDF не найден»

Проверьте полный путь. Перетащите файл из Finder или Проводника прямо в окно терминала — путь подставится автоматически.

Ошибка установки pdfplumber

Обновите pip и повторите установку:

python -m pip install --upgrade pip
python -m pip install -e .

Часть продавцов находится в «Прочее»

Это ожидаемо при первом запуске. Добавьте их в categories.yaml и сформируйте отчёт повторно.

Суммы не сошлись

Не редактируйте PDF перед обработкой. Скачайте выписку из Kaspi повторно и проверьте, что выбран полный период. Если расхождение сохраняется, посмотрите summary.json: там указана разница по каждой контрольной группе.

Приватность

• Скрипт не выполняет сетевых запросов.
• PDF не копируется в папку отчёта.
• В report.html, transactions.csv и summary.json содержатся реальные финансовые данные и имена контрагентов.
• Не отправляйте папку report третьим лицам и не добавляйте её в публичный Git-репозиторий.
• В .gitignore уже добавлены *.pdf, report/ и reports/.

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

kaspi-statement-analyzer/
├── categories.yaml              # редактируемые правила категорий
├── pyproject.toml               # установка проекта и команда kaspi-report
├── requirements.txt             # список зависимостей
├── README.md                    # эта инструкция
├── src/kaspi_analyzer/
│   ├── parser.py                # извлечение таблиц из PDF
│   ├── classifier.py            # типы операций и категории
│   ├── validation.py            # контроль по сводке Kaspi
│   ├── report.py                # HTML, CSV и JSON
│   └── cli.py                   # интерфейс командной строки
└── tests/                       # автоматические тесты