Импорт банковских выписок через CLI

Используйте bea import для предпросмотра банковской выписки, проверки дубликатов и добавления проверенных записей в ваш локальный реестр.

Вам нужен существующий реестр и импортер на Python для точного формата экспорта вашего банка. Если вы начинаете новую бухгалтерию, следуйте краткому руководству по CLI. Сохраните исходную банковскую выписку, чтобы можно было сравнить её с предпросмотром.

1. Выберите импортер​

Импортер читает файл банка и предоставляет счета транзакций. Bea не угадывает формат и не классифицирует покупки с помощью модели ИИ.

Ваша конфигурация importers.py экспортирует CONFIG = [importer, ...]. Импортеры используют текущий интерфейс Beangulp: identify(filepath), account(filepath) и extract(filepath, existing). Проводки по счетам-источникам требуют явных сумм для сопоставления дубликатов.

Для первой пробной попытки сохраните пример конфигурации категоризированного CSV как importers.py рядом с вашим корневым реестром. Он использует только Beancount и стандартную библиотеку Python, поэтому работает с установкой Homebrew.

Сохраните этот образец как bank.csv в той же папке:

Date,Payee,Narration,Amount,Currency,Category,BankID
2026-08-02,Cafe,Coffee,-5.25,USD,Expenses:Dining,bank-001
2026-08-03,Employer,Salary,1000,USD,Income:Salary,bank-002

В образце используется знаковая сумма по счету: расход отрицательный, а депозит положительный. Category предоставляет другой счет. Обе категории есть в шаблоне USD, созданном bea init.

Используйте импортер, написанный для вашего банка, при импорте его нативного CSV, OFX или QIF. Примерная конфигурация ожидает ровно указанные выше столбцы. Выполняйте только те конфигурации Python, которым вы доверяете.

2. Предпросмотр записей​

Выполните это из папки, содержащей main.bean:

bea import bank.csv --config importers.py

В реестр пока ничего не записывается. Проверьте даты, получателей, знаковые суммы источников, счета назначения, совпадения дубликатов и предлагаемый diff файла в предпросмотре.

Для образца предпросмотр должен содержать расход на питание в размере 5,25 USD и депозит зарплаты в размере 1 000 USD. Исправьте неправильную категорию в импортере или исходных данных, затем снова выполните предпросмотр. Откройте недостающие счета перед применением импорта.

Если несколько импортеров распознают файл, выберите один по имени:

bea import bank.csv --config importers.py --importer categorized-checking

Неизвестное имя выводит список настроенных имён. Известный импортер, который не распознаёт файл, сообщает об этом отдельно.

3. Примените проверенные записи​

bea import bank.csv --apply
bea check
bea list transaction --limit 10

CLI запоминает путь к конфигурации для этого корневого реестра. Будущие запуски сначала используют явный --config, затем запомненный путь, затем importers.py рядом с корнем. Вывод указывает путь и откуда он взялся.

--apply пересчитывает предпросмотр по текущим файлам. Он проверяет полный реестр-кандидат перед записью. Сбой проверки оставляет исходный реестр без изменений и завершается с кодом 1. Одновременное изменение реестра завершается с кодом 4; проверьте изменение и выполните свежий предпросмотр перед повторной попыткой.

4. Разрешите возможные дубликаты​

Повторение того же импорта образца пропускает его существующие записи. Перекрывающаяся выписка также может содержать строки, требующие решения:

Другой банковский ID не исключает дубликат. Банки могут менять ID при последующих загрузках. Две реальные покупки также могут иметь одинаковую дату, получателя и сумму.

После проверки каждого возможного совпадения выберите одну из этих альтернатив:

bea import bank.csv --apply --duplicates skip

bea import bank.csv --apply --duplicates include

Решение применяется ко всем возможным совпадениям в этом вызове. Точные дубликаты остаются пропущенными. Конфликты ID по-прежнему блокируют запись.

По умолчанию --duplicates review отказывается применять нерешённые совпадения. Он завершается с кодом 4 и называет затронутые строки предпросмотра. --no-input и --yes не обходят эту проверку. Намеренное решение пропустить каждую строку завершается с кодом 0 без добавлений в реестр.

Сохраняйте импорт повторяемым​

По умолчанию сопоставление дубликатов проверяет метаданные bank_id, fitid, transaction_id и imported_id внутри счёта-источника импортера. Используйте повторяющиеся опции --id-key KEY, чтобы заменить этот набор.

CLI также записывает метаданные bea_import_id для идентификации строки в исходной выписке. Сохраняйте их при редактировании импортированных записей. Возможные совпадения проверяются по существующим транзакциям и принятым строкам в том же пакете.

Получатели, описания и строковые метаданные заменяют переносы строк на пробелы перед предпросмотром и записью. Кавычки и обратные слэши сохраняют своё содержимое. Импортированный текст продавца поэтому остаётся читаемым в одной строке реестра.

Импорт добавляет записи; он не обновляет и не удаляет существующую транзакцию. Вносите исправления осознанно в свой реестр и после этого выполняйте bea check. Массовое добавление записей в JSON с помощью bea add transactions не имеет обнаружения дубликатов.

Запись во включённый файл​

Держите --file направленным на корень и выбирайте назначение с помощью --into:

bea --file ~/my-books/main.bean import bank.csv --into 2026.bean
bea --file ~/my-books/main.bean import bank.csv --into 2026.bean --apply

Файл 2026.bean должен уже существовать и быть включён корневым реестром. Его путь указывается относительно корневой папки. Путь к выписке остаётся относительным к вашей рабочей папке. Предпросмотр определяет файл, который будет изменён.

Использование импорта в скриптах​

bea --json --no-input import bank.csv --apply --duplicates skip

Выбирайте skip только когда это ваша намеренная политика для возможных совпадений. JSON возвращает предпросмотр и количество записей внутри data. Отказанные применения помещают предпросмотр в error.result на stderr с written: 0. Всегда проверяйте код выхода. См. справочник по JSON и кодам выхода перед планированием неавтоматизированных импортов.

Устранение неполадок импортера​

Если конфигурация импортирует сторонние пакеты, эти пакеты должны быть в окружении Python, где выполняется bea. Например:

uv run --with beancount-io --with beangulp \
  bea --file ~/my-books/main.bean import bank.ofx --config importers.py

Добавьте --with YOUR_IMPORTER_PACKAGE для отдельно установленного банковского импортера. Это использует отдельное окружение от Homebrew.

При исключении импортера добавьте --debug перед командой, чтобы показать его трассировку:

bea --debug import bank.csv --config importers.py

Вывод импортера захватывается в importer_output, чтобы он не портил JSON. В режиме отладки JSON трассировка находится в error.traceback.

Для разового преобразования без импортера Python попробуйте конвертер CSV или конвертер OFX и QIF. Проверьте сгенерированные записи перед добавлением их в вашу бухгалтерию.