sbertoactual

Автоматизация импорта выписок Сбербанка (дебетовые и кредитные карты) в Actual Budget.

Особенности

• Поддержка форматов: Прямой импорт CSV и PDF выписок (использует Sberbank2Excel).
• Автоматизация категорий: Автоматическое создание групп и категорий в Actual Budget на основе данных из выписки.
• Дедупликация: Каждая транзакция получает уникальный imported_id (на основе даты, суммы и описания), что предотвращает повторный импорт одних и тех же данных.
• Два режима работы: Гибкий CLI для локального использования и REST API сервер для интеграций.

Быстрый старт (Docker)

Это рекомендуемый способ запуска, так как он включает все необходимые зависимости (Node.js, Python, uv).

Docker Compose (рекомендуется)

1. Создайте файл .env на основе примера в разделе "Конфигурация".
2. Запустите сервис:

docker compose up -d

Docker CLI

Если вы предпочитаете обычный запуск:

docker build -t sbertoactual .
docker run -d \
  -p 3000:3000 \
  -v ./data:/app/data \
  --env-file .env \
  --name sbertoactual \
  sbertoactual

Локальная установка

Требования

• Node.js: v20+
• pnpm: Рекомендуется (через Corepack)
• Python 3: Для обработки PDF через uv

Установка зависимостей

1. Установите Node.js пакеты:

   pnpm install

2. Установите инструмент конвертации PDF:

   uv tool install git+https://github.com/Ev2geny/Sberbank2Excel.git

Конфигурация (.env)

| Переменная | Описание | | :--- | :--- | | ACTUAL_SERVER_URL | URL вашего сервера Actual Budget | | ACTUAL_SERVER_PASSWORD | Пароль пользователя | | ACTUAL_SYNC_ID | Sync ID вашего бюджета | | ACTUAL_BUDGET_PASSWORD | Пароль шифрования бюджета (если установлен) | | ACTUAL_ACCOUNT_ID | ID счета в Actual Budget, куда пойдут транзакции | | ACTUAL_GROUP_NAME | Имя группы категорий. По умолчанию: "Импорт из Сбера" | | PORT | Порт сервера. По умолчанию: 3000 |

Использование

Режим командной строки (CLI)

Положите файл выписки в папку data/ и выполните команду с нужным режимом.

Доступные режимы --mode:

• all (по умолчанию): Полный цикл импорта. Выполняет последовательно convert, setup и upload. Самый удобный способ для регулярного импорта.
• convert: Только обработка входного файла (PDF или CSV). Извлекает транзакции и сохраняет их во временный JSON-файл для последующей обработки.
• setup: Проверка и создание категорий. Сканирует обработанные транзакции и автоматически создает недостающие категории в Actual Budget, чтобы избежать ошибок при загрузке.
• upload: Только загрузка данных. Отправляет транзакции на сервер Actual Budget. Благодаря дедупликации по imported_id, вы можете запускать этот режим повторно без риска дублей.
• list: Служебный режим. Выводит список всех счетов из вашего Actual Budget с их ID (помогает найти нужный ACTUAL_ACCOUNT_ID для конфига).

Пример запуска через pnpm:

# Импорт файла
env INPUT_FILE="my_statement.pdf" pnpm start -- --mode=all

Или через установленный глобально пакет:

sber-actual --mode=list

Режим сервера (API)

Запустите сервер для автоматизации загрузки через HTTP:

pnpm run server

Отправьте файл выписки через curl:

# Для PDF
curl -X POST -F "[email protected]" http://localhost:3000/upload

# Для CSV
curl -X POST -F "[email protected]" http://localhost:3000/upload

Разработка и тестирование

• Проверка типов: pnpm run type-check
• Запуск тестов: pnpm test
• Линтинг: pnpm run lint

Лицензия

Проект распространяется под лицензией MIT. Подробности в файле LICENSE.