Імпорт банківських виписок за допомогою CLI

Використовуйте bea import, щоб переглянути банківську виписку, перевірити дублікати і додати перевірені записи до вашого локального журналу.

Вам потрібен існуючий журнал і імпортер Python для точного формату експорту вашого банку. Якщо ви починаєте нові книги, слідуйте за швидким стартом CLI. Зберігайте оригінальну банківську виписку, щоб можна було порівняти її с переглядом.

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

Імпортер читає файл банку і постачає рахунки транзакцій. Bea не вгадує формат і не категоризує покупки за допомогою моделі AI.

Ваша конфігурація 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

Поки що нічого не записується в журнал. Перегляньте дати, получателей, підписані суми джерела, рахунки призначення, відповідності дублікатів і пропонований диф файлу в перегляді.

Для приклада перегляд повинен містити 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. Перегляньте згенеровані записи перед додаваньем их в ваші книги.