🇷🇺 Русский | 🇬🇧 English

sbertoactual

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

Особенности

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

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

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

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: v24+ (согласно .nvmrc)
• pnpm: Рекомендуется (через Corepack)

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

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

   pnpm install

Конфигурация (.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
API_KEY	(Опционально) Секретный ключ для защиты сервера. Если установлен, запросы должны содержать заголовок X-API-Key

Важно: версия @actual-app/api не должна отставать от версии вашего Actual server. Если в логах есть out-of-sync-migrations, это почти всегда означает, что локальный API-клиент слишком старый для текущей схемы бюджета на сервере.

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

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

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

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

• all (по умолчанию): Полный цикл импорта. Выполняет последовательно convert, setup и upload. Самый удобный способ для регулярного импорта.
• convert: Только обработка входного файла (PDF или CSV). Извлекает транзакции и сохраняет их в actual_import.csv для последующей обработки.
• 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. Если настроен API_KEY, добавьте заголовок:

# Для PDF
curl -X POST -H "X-API-Key: your-secret-key" -F "file=@statement.pdf" http://localhost:3000/upload

# Для CSV
curl -X POST -H "X-API-Key: your-secret-key" -F "file=@statement.csv" http://localhost:3000/upload

Поддержка PDF

• Для PDF используется @rvboris/sberparse.
• Поведение CSV-импорта не меняется.
• Ошибка out-of-sync-migrations не связана с PDF-парсером: это проблема совместимости @actual-app/api и Actual server.

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

• Проверка типов: pnpm run type-check
• Запуск тестов: pnpm test
• Покрытие: pnpm run coverage
• Линтинг: pnpm run lint
• Руководство для контрибьюторов: CONTRIBUTING.md

Релизный процесс

• npm-релизы управляются через release-please в .github/workflows/npm-publish.yml.
• Каждый push в master обновляет или создаёт release PR.
• После merge release PR workflow проверяет релизный коммит и публикует пакет в npm с provenance.
• Для работы схемы в настройках репозитория GitHub Actions должен быть включён Allow GitHub Actions to create and approve pull requests.

Лицензия

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