Skip to content

Bafff/ynab-bank-converters

BranchesTags

Repository files navigation

Конвертеры банковских выписок для YNAB

Набор Python-скриптов для конвертации экспортов из банков и платёжных сервисов в формат CSV, совместимый с YNAB (You Need A Budget). Поддерживает несколько португальских банков и международных платёжных сервисов с интеллектуальным удалением дубликатов и маппингом категорий.

🇬🇧 English version: README_EN.md

📋 Поддерживаемые сервисы

Сервис Скрипт Описание
Caixa Geral de Depósitos caixa_to_ynab.py Конвертер португальского национального банка с автоматической фильтрацией транзакций Curve
Revolut revolut_to_ynab.py Мультивалютный платёжный сервис и обмен валют
Curve Card curve_to_ynab.py Виртуальная платёжная карта с обработкой возвратов
Coverflex coverflex_to_ynab.py Сервис продуктовых карт и талонов на питание
Wirex wirex_to_ynab.py Мультивалютная карта с поддержкой криптовалют

✨ Ключевые возможности

  • Без внешних зависимостей - Использует только стандартную библиотеку Python
  • Умное предотвращение дубликатов - Автоматически исключает дублирующие транзакции при использовании связанных карт
  • Автоматический маппинг категорий - Сопоставляет банковские категории с категориями YNAB по настраиваемым правилам
  • Поддержка различных кодировок - Обрабатывает Windows-1252, UTF-8 и другие кодировки
  • Конвертация форматов дат - Преобразует различные форматы дат в совместимый с YNAB формат MM/DD/YYYY
  • Обработка возвратов - Выявляет и фильтрует возвращённые транзакции в экспортах Curve

🚀 Быстрый старт

Требования

  • Python 3.6 или выше (дополнительные пакеты не требуются)
  • Файлы экспорта из банка/сервиса в формате CSV или текстовом формате
  • Аккаунт YNAB (бесплатный или платный)

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

  1. Экспортируйте транзакции из вашего банка/сервиса
  2. Запустите соответствующий конвертер:
# Банк Caixa
python3 caixa_to_ynab.py statement.csv

# Revolut
python3 revolut_to_ynab.py account-statement.csv

# Curve Card
python3 curve_to_ynab.py Transactions.csv

# Coverflex
python3 coverflex_to_ynab.py coverflex_transactions.txt

# Wirex
python3 wirex_to_ynab.py Statement_All_accounts.csv
  1. Импортируйте в YNAB:
    • Откройте YNAB
    • Перейдите к вашему счёту
    • Нажмите "Import" → "File Import"
    • Выберите созданный файл *_ynab.csv

📖 Подробная документация по конвертерам

Caixa Geral de Depósitos (caixa_to_ynab.py)

Конвертирует CSV/TSV экспорты из CaixaDirect в формат YNAB.

Инструкции по экспорту:

  1. Войдите в CaixaDirect
  2. Перейдите в "Movimentos" (Транзакции)
  3. Выберите диапазон дат
  4. Скачайте как CSV или TSV

Возможности:

  • Автоматическое определение формата CSV/TSV
  • Поддержка кодировок Windows-1252 и UTF-8
  • Исключает транзакции Curve Card (паттерны: CAR WAL, COMPRAS C.DEB, CR VCHER)
  • Сопоставляет португальские банковские категории с категориями YNAB
  • Конвертирует португальский формат дат (DD-MM-YYYY) в формат YNAB
  • Правильно обрабатывает колонки дебета/кредита

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

python3 caixa_to_ynab.py comprovativo.csv
# Создаёт: comprovativo_ynab.csv

Опциональный маппинг категорий: Создайте файл category_mapping.json в той же директории:

{
  "caixa_categories": {
    "COMPRAS": "Продукты",
    "COMBUSTIVEL": "Транспорт",
    "RESTAURACAO / BARES": "Рестораны"
  }
}

Revolut (revolut_to_ynab.py)

Конвертирует CSV экспорты из Revolut в формат YNAB.

Инструкции по экспорту:

  1. Откройте приложение/веб-версию Revolut
  2. Перейдите в "Accounts" → Выберите счёт
  3. Нажмите "Statement" → "Export"
  4. Выберите формат CSV

Возможности:

  • Обрабатывает все типы транзакций (Card Payment, Transfer, ATM, Deposit, Fee, Refund)
  • Автоматически фильтрует отменённые транзакции (REVERTED)
  • Исключает транзакции сберегательных кошельков
  • Объединяет комиссии с суммами транзакций
  • Включает комиссии в поле memo для прозрачности

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

python3 revolut_to_ynab.py account-statement.csv
# Создаёт: account-statement_ynab.csv

Curve Card (curve_to_ynab.py)

Конвертирует CSV экспорты из Curve в формат YNAB с обработкой возвратов.

Инструкции по экспорту:

  1. Откройте приложение Curve
  2. Перейдите в "Transactions"
  3. Нажмите иконку "Export"
  4. Выберите диапазон дат и скачайте CSV

Возможности:

  • Исключает Curve Points (CPT) по умолчанию
  • Обрабатывает Curve Cash (кэшбэк) как доход
  • Сохраняет встроенные категории Curve
  • Может фильтровать возвращённые транзакции используя refunded_originals.json

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

# Базовая конвертация
python3 curve_to_ynab.py Transactions.csv
# Создаёт: Transactions_ynab.csv

# Включить транзакции Curve Points
python3 curve_to_ynab.py Transactions.csv --include-cpt

# Пропустить транзакции Curve Cash
python3 curve_to_ynab.py Transactions.csv --skip-cash

Обработка возвратов: Сначала выявите возвращённые транзакции:

python3 utils/find_refunds.py Transactions.csv
# Создаёт: refunded_originals.json

Затем запустите конвертер - он автоматически исключит возвращённые оригинальные транзакции.

Coverflex (coverflex_to_ynab.py)

Конвертирует текстовые файлы транзакций Coverflex в формат YNAB.

Инструкции по экспорту:

  1. Откройте приложение/веб-версию Coverflex
  2. Перейдите в историю транзакций
  3. Скопируйте текст транзакций или экспортируйте в файл

Формат входных данных:

Pingo Doce 02/08/2025 -10.50€
Continente 05/08/2025 -25.30€
Top-up 01/08/2025 +100.00€

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

python3 coverflex_to_ynab.py coverflex_2025.txt
# Создаёт: coverflex_2025_ynab.csv

Wirex (wirex_to_ynab.py)

Конвертирует CSV экспорты из Wirex в формат YNAB.

Инструкции по экспорту:

  1. Войдите в приложение/веб-версию Wirex
  2. Перейдите в "Statements"
  3. Выберите "All accounts" и диапазон дат
  4. Скачайте CSV

Возможности:

  • Обрабатывает множество типов транзакций (Card Payment, Exchange, Fee, Rewards)
  • Исключает транзакции CRV*** (дубликаты Curve)
  • Обрабатывает обмен криптовалют
  • Обрабатывает криптобэк-вознаграждения

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

python3 wirex_to_ynab.py Statement_All_accounts.csv
# Создаёт: Statement_All_accounts_ynab.csv

🛠️ Вспомогательные скрипты

Поиск возвратов (utils/find_refunds.py)

Анализирует транзакции Curve для выявления возвращённых покупок и их оригинальных транзакций.

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

python3 utils/find_refunds.py Transactions.csv

Выходные данные:

  • refunded_originals.json - Список ID возвращённых транзакций
  • refund_analysis.txt - Детальный отчёт анализа

Генерация платежей арендодателю (utils/generate_landlord_payments.py)

Пример скрипта, показывающий как программно создавать транзакции YNAB. Полезен для создания регулярных платежей или пакетов единовременных транзакций.

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

python3 utils/generate_landlord_payments.py
# Создаёт: landlord_payments_ynab.csv

Вы можете модифицировать этот скрипт как шаблон для своих собственных генераторов транзакций.

🎯 Маппинг категорий

Все конвертеры поддерживают автоматический маппинг категорий с использованием файла category_mapping.json. Этот файл сопоставляет банковские категории и названия получателей с вашими категориями YNAB.

Настройка:

  1. Скопируйте category_mapping.example.json в category_mapping.json
  2. Отредактируйте категории в соответствии с вашей настройкой YNAB
  3. Поместите файл в ту же директорию, что и скрипты конвертеров

Пример:

{
  "caixa_categories": {
    "COMPRAS": "Нужды: Продукты",
    "COMBUSTIVEL": "Транспорт: Топливо"
  },
  "payee_rules": {
    "BOLT": "Транспорт: Такси",
    "PINGO DOCE": "Нужды: Продукты"
  }
}

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

  • Данные никуда не отправляются - Вся обработка происходит локально на вашем компьютере
  • Без внешних зависимостей - Использует только стандартную библиотеку Python
  • Данные игнорируются Git - Файл .gitignore предотвращает случайные коммиты финансовых данных
  • Только примеры конфигурации - В репозитории нет персональных данных

Что игнорируется Git:

  • Все файлы CSV, TSV, TXT (экспорты транзакций)
  • Все PDF файлы (банковские выписки)
  • Созданные выходные файлы YNAB
  • Файлы анализа транзакций
  • Персональные конфигурационные файлы

📁 Структура репозитория

ynab-converter/
├── README.md                      # Этот файл (Русская документация)
├── README_EN.md                   # Английская документация
├── .gitignore                     # Предотвращает коммит персональных данных
├── caixa_to_ynab.py              # Конвертер банка Caixa
├── revolut_to_ynab.py            # Конвертер Revolut
├── curve_to_ynab.py              # Конвертер Curve Card
├── coverflex_to_ynab.py          # Конвертер Coverflex
├── wirex_to_ynab.py              # Конвертер Wirex
├── category_mapping.example.json  # Пример конфигурации категорий
└── utils/
    ├── find_refunds.py           # Инструмент обнаружения возвратов
    └── generate_landlord_payments.py  # Пример генератора транзакций

💡 Советы и лучшие практики

  1. Предотвращение дубликатов:

    • Используйте конвертер Caixa для вашего банковского счёта
    • Используйте конвертеры Curve/Wirex для транзакций по картам
    • Конвертер Caixa автоматически исключает транзакции Curve

  2. Маппинг категорий:

    • Сначала настройте категории в YNAB
    • Используйте точные названия категорий в category_mapping.json
    • Категории могут включать эмодзи, если вы используете их в YNAB

  3. Обработка возвратов:

    • Запускайте find_refunds.py на экспортах Curve перед конвертацией
    • Это предотвратит дублирующие записи при импорте и оригинала, и возврата

  4. Диапазоны дат:

    • Экспортируйте по одному месяцу за раз для упрощения сверки
    • Используйте одинаковые диапазоны дат для всех сервисов

  5. Резервное копирование:

    • Сохраняйте оригинальные файлы экспорта в качестве резервной копии
    • YNAB позволяет повторный импорт с обнаружением дубликатов

🐛 Решение проблем

Проблема: "No module named 'csv'"

  • Решение: Обновите Python до версии 3.6 или выше

Проблема: Ошибки кодировки при открытии CSV

  • Решение: Скрипт автоматически определяет кодировку. Если проблемы сохраняются, проверьте формат экспорта банка.

Проблема: Категории не применяются в YNAB

  • Решение: Убедитесь, что названия категорий в category_mapping.json точно совпадают с вашими категориями YNAB (включая эмодзи)

Проблема: Дублирующиеся транзакции в YNAB

  • Решение:
    • Убедитесь, что используете конвертер Caixa для банковских транзакций (он исключает Curve)
    • Запустите find_refunds.py перед конвертацией транзакций Curve
    • Используйте встроенное обнаружение дубликатов YNAB при импорте

Проблема: Неправильный формат даты

  • Решение: Все конвертеры выдают формат MM/DD/YYYY. Проверьте настройки формата даты в YNAB.

🤝 Участие в разработке

Приветствуются вклады в проект! Не стесняйтесь:

  • Добавлять поддержку новых банков/сервисов
  • Улучшать существующие конвертеры
  • Исправлять баги
  • Улучшать документацию

📄 Лицензия

Этот проект предоставляется как есть для личного использования. Можете свободно модифицировать и адаптировать под свои нужды.

⚠️ Отказ от ответственности

Этот инструмент не связан с YNAB, Caixa Geral de Depósitos, Revolut, Curve, Coverflex, Wirex или любым другим финансовым учреждением. Используйте на свой риск. Всегда проверяйте конвертированные данные перед импортом в YNAB.

Сделано с ❤️ для сообщества YNAB

About

Convert transactions to prepare them to be imported into YNAB

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages