Звичайний банк CSV не потребує імпортера на Python. Відобразіть його стовпці за допомогою --csv, назвіть рахунок джерела за допомогою --account, категоризуйте рядки з --rules, а потім перегляньте та застосуйте записи за допомогою bea import.
Вам потрібен існуючий журнал. Якщо ви починаєте нові книги, дотримуйтесь швидкого старту CLI. Збережіть оригінальний банківський експорт, щоб порівняти його з попереднім переглядом.
1. Відобразіть стовпці CSV
Збережіть цей приклад як statement.csv, потім виконайте наведені нижче команди з тієї ж директорії:
Date,Payee,Narration,Amount
2026-08-02,Whole Foods,groceries,-20.00
2026-08-03,Shell,gas,-40.00
2026-08-04,Unknown Shop,mystery,-9.99Суми використовують банківську конвенцію знаків: витрати — негативні, а внесок — позитивний. Валюта за замовчуванням — операційна валюта журналу, тому в цьому файлі не потрібен стовпець валюти. Помістіть стовпець опису банку в narration та збережіть payee для продавця.
Створіть журнал і відкрийте підрахунок палива, який використовується нижче:
bea --no-input init books --currency USD --date 2026-08-01 \
--opening-balance "Assets:Checking 1000"
bea --file books/main.bean add open --date 2026-08-01 --account Expenses:Transport:Fuel -c USDШаблон вже відкриває Expenses:Groceries та інші загальні рахунки. Він не відкриває Expenses:Transport:Fuel, тому друга команда відкриває його перед імпортом. Глобальні опції, такі як --file, розміщуються перед підкомандою.
2. Перегляньте записи
Збережіть ці правила категоризації як rules.toml, а потім перегляньте:
cat > rules.toml <<'EOF'
[[rule]]
match = "whole foods|trader joe|corner market"
account = "Expenses:Groceries"
[[rule]]
match = "shell|chevron|exxon"
account = "Expenses:Transport:Fuel"
EOF
bea --file books/main.bean import statement.csv --csv date=Date,amount=Amount,payee=Payee,narration=Narration --account Assets:Checking --rules rules.tomlПравила спочатку співпадають із отримувачем платежу, потім з описом транзакції, ігноруючи регістр. Перше співпадіння виграє. Рядки, для яких немає відповідних правил, розміщуються в Expenses:Uncategorized з прапорцем ! для подальшого перегляду. Посібник продукту IMPORTING guide документує повний довідник відображення, включно з парою debit та credit, стовпцем category та читанням заголовка --csv auto.
Ще нічого не записано в журнал. Попередній перегляд виводить 3 ready, 0 exact duplicates, 0 possible duplicates і виходить з кодом 0. Його стовпець RULE називає виграшний шаблон для кожного рядка, або unmatched для рядка Unknown Shop. Перевірте дати, отримувачів, підписані суми джерела, цільові рахунки, дублікати співпадінь і пропоноване різницево файла. Виправте неправильне правило або категорію, потім перегляньте знову. Відкрийте всі відсутні рахунки перед застосуванням імпорту: правило, яке називає рахунок, який журнал не відкриває, не проходить валідацію.
3. Застосуйте переглянуті записи
bea --file books/main.bean import statement.csv --apply
bea --file books/main.bean check
bea --file books/main.bean list transaction --flag '!'
bea --file books/main.bean query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"Відповідність стовпців запам'ятовується для кожного реєстру, рядка заголовка та вихідного рахунку, тому --apply повторно запускається без прапорців і звітує, використовуючи запам’ятовану відповідність стовпців. Він повторно обчислює попередній перегляд на основі поточних файлів, перевіряє повний кандидатський реєстр перед записом і записує 3 записи. bea check повідомляє про відсутність помилок. Черга ! містить один невідповідний рядок: Unknown Shop з mystery на -9.99 USD. Успішна перевірка лише підтверджує баланс реєстру та його валідність. Вона нічого не говорить про те, чи належить цей рядок до Expenses:Uncategorized, тому перекваліфікуйте його свідомо у вашому реєстрі. Перевірка завершується на 930.01 USD: початковий баланс 1,000 USD мінус 69.99 USD витрат.
4. Повторні імпорти нічого не додають
bea --file books/main.bean import statement.csv --applyУ попередньому перегляді повідомляється 0 ready, 3 exact duplicates, а під час запуску записується 0 записів з кодом завершення 0. Кожен записаний рядок має метадані import-id із хешем вмісту, тому ідентичний файл відповідає кожному рядку. Зберігайте ці метадані під час редагування імпортованих записів. Імпорт додає записи; він не оновлює і не видаляє наявні транзакції. Внесіть виправлення свідомо у вашому реєстрі та запустіть bea check пізніше. Масовий імпорт JSON із bea add transactions не має виявлення дублікатів.
5. Вирішення можливих дублікатів
Пізніше завантаження може повторити рядок з іншим описом або банківськими ID. Дата, нормалізований одержувач та підписана сума джерела все ще позначають його як можливу відповідність:
| Статус попереднього перегляду | Значення | Що робити |
|---|---|---|
new | Не виявлено доказів дубліката | Перевірте суми та категорії |
duplicate | Стабільний ID та деталі транзакції збігаються, або існує ідентична директива без транзакції | Вже пропущено |
possible_duplicate | Дата, нормалізований одержувач і підписана сума/валюта джерела збігаються | Порівняйте попередній перегляд із наявним записом |
conflict | Стабільний ID збігається з різними деталями транзакції | Вирішіть розбіжність у ID або даних, потім повторіть попередній перегляд |
Інший банківський ID не виключає дублікат. Банки можуть змінювати ID при наступних завантаженнях. Дві реальні покупки також можуть мати однакову дату, одержувача та суму, тому можливе співпадіння — це доказ, а не підтвердження. Bea не робить припущень з AI-моделі і ніколи не категоризує за вас поза межами ваших правил.
За замовчуванням --duplicates review відмовляється застосовувати нерозв'язані збіги. Під час перевірки другий файл, що повторює рядок 2026-08-02 Whole Foods -20.00 USD з іншою анотацією, відобразився як 1 можливий дубль, а --apply вийшов з кодом 4 без записів. Після перегляду всіх можливих збігів виберіть одну з цих альтернатив:
bea --file books/main.bean import statement.csv --apply --duplicates skip
bea --file books/main.bean import statement.csv --apply --duplicates includeВиберіть include, щоб зберегти законні повторні покупки. Це рішення застосовується до всіх можливих збігів у цьому виклику. Точні дублікати залишаються пропущеними. Конфлікти ID все ще блокують запис. --no-input і --yes не обходять цей огляд. Умисне рішення пропустити кожен рядок завершує роботу з кодом 0 без додавання записів у книгу.
6. Використовуйте Python-імпортер для інших форматів
Для форматів, які не можна виразити відображенням колонок, таких як OFX, QIF або CSV з нестандартним розташуванням колонок, bea import викликає налаштований імпортер, використовуючи поточний інтерфейс Beangulp: identify(filepath), account(filepath) та extract(filepath, existing). Імпортер відповідає за специфічний для банку розбір і категоризацію. Він повинен надавати явні суми на проводках з рахунку-джерела, щоб дублікати порівнювалися за фактичними банківськими сумами. Python-імпортер залишається просунутим шляхом для цих форматів. Для рідного CSV банку спробуйте спочатку --csv.
Для першого практичного запуску збережіть приклад конфігурації категоризованого CSV як importers.py поруч із головною книгою. Він використовує лише Beancount та стандартну бібліотеку Python, тож працює з інсталяцією Homebrew. Приклад bank.csv використовує підписану суму на розрахунковому рахунку: витрати на харчування -5.25 USD і депозит заробітної плати 1,000 USD. Конфігурація очікує точно свої задокументовані колонки. Виконуйте лише ті конфігурації Python, яким довіряєте.
bea --file books/main.bean import bank.csv --config importers.py
bea --file books/main.bean import bank.csv --config importers.py --importer categorized-checking
bea --file books/main.bean import bank.csv --config importers.py --applyВаша конфігурація importers.py експортує CONFIG = [importer, ...]. Якщо кілька імпортерів розпізнають файл, виберіть один за назвою. Невідома назва виводить список налаштованих імен. Відомий імпортер, який не розпізнав файл, повідомляє про це окремо.
CLI запам'ятовує шлях конфігурації для цієї головної книги. Майбутні запуски вибирають спочатку явний --config, потім запам'ятований шлях, а потім importers.py поруч із головною книгою. Вивід називає шлях і звідки він походить.
--apply повторно обчислює попередній перегляд за поточними файлами. Він перевіряє повний кандидатський реєстр перед записом. Помилка валідації залишає оригінальний реєстр без змін і завершує процес з кодом 1. Паралельна зміна реєстру завершує процес з кодом 4; перевірте зміну та виконайте свіжий перегляд перед повторною спробою.
Зберігайте імпорти повторюваними
За замовчуванням перевірка дублікатів порівнює метадані bank_id, fitid, transaction_id та imported_id у межах облікового запису-джерела імпортера. Використовуйте повторювані опції --id-key KEY, щоб замінити цей набір.
Рядок зі стабільним банківським ідентифікатором записується з метаданими import-id, які називають його тип, наприклад префіксом bank: або ofx:. Рядок без нього записується з хешем вмісту csv:sha256: за датою, сумою, описом і обліковим записом, тому повторний імпорт того самого файлу пропускає кожен рядок. Записи, зроблені до цієї конвенції, можуть все ще містити метадані bea_import_id, і вони все ще співпадають при повторному імпорті. Потенційні співпадіння перевіряються щодо існуючих транзакцій і прийнятих рядків у тому ж пакеті.
Одержувачі, описи та метадані рядків замінюють розриви рядків на пробіли перед переглядом і записом. Кавички та зворотні косі риски зберігають свій вміст. Текст імпортованих торговців тому залишається читабельним в одному рядку реєстру.
Запис у включений файл
Зберігайте --file, спрямований на корінь, і виберіть пункт призначення за допомогою --into:
bea --file books/main.bean import statement.csv --into 2026.bean
bea --file books/main.bean import statement.csv --into 2026.bean --apply2026.bean повинен уже існувати і бути включеним коренем. Його шлях відносний до кореневого каталогу. Шлях експорту залишається відносним до вашого робочого каталогу. Попередній перегляд ідентифікує файл, який буде змінений.
Використовуйте імпорти у сценарії
bea --file books/main.bean --json --no-input import statement.csv --apply --duplicates skipВибирайте skip лише тоді, коли це ваша задумана політика для потенційних співпадінь. JSON повертає попередній перегляд і кількість записів всередині data. Відмовлені запити поміщають попередній перегляд у error.result на stderr з written: 0. Завжди перевіряйте статус виходу. Перед плануванням безперервних імпортів дивіться JSON та довідку про коди виходу.
Усунення несправностей імпортера
Конфігурації імпортерів запускаються в керованому двигуні. Якщо конфігурація імпортує Beangulp, встановіть системну бібліотеку libmagic і активуйте Beangulp там один раз:
bea engine enable beangulp
bea --file books/main.bean import bank.ofx --config importers.py
bea --debug --file books/main.bean import bank.csv --config importers.pybea engine status повідомляє про активовані функції. Встановлення банківського імпортера разом з фронтендом bea не робить його доступним всередині двигуна. Конфігурація, що імпортує додаткові пакети, потребує цих залежностей у двигуні; активація лише Beangulp їх не встановлює. Використовуйте CSV-маппер або вказані нижче конвертери, коли ці залежності імпортера недоступні.
Для винятку імпортера поставте --debug перед командою, щоб показати її трасування стека. Вивід імпортера захоплюється в importer_output, щоб він не пошкодив JSON. У режимі налагодження JSON трасування стека - це error.traceback.
Для одноразового конвертування без Python-імпортера спробуйте перетворювач CSV або перетворювач OFX та QIF. Перегляньте згенеровані записи перед їх додаванням до ваших книг.