Импортиране на банкови извлечения с 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. Разрешете възможни дубликати​

Повтарянето на същия примерен импорт пропуска съществуващите му записи. Припокриващ се експорт може също да съдържа редове, които изискват решение:

Различен банков идентификатор не изключва дубликат. Банките могат да променят идентификаторите при по-късни изтегляния. Две реални покупки също могат да споделят дата, получател и сума.

След като прегледате всяко възможно съвпадение, изберете една от тези алтернативи:

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

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

Решението се прилага за всички възможни съвпадения в това изпълнение. Точните дубликати остават пропуснати. Конфликтите на идентификатори все още блокират записа.

По подразбиране --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 преди командата, за да покажете нейната traceback:

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

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

За еднократно преобразуване без Python импортер опитайте CSV конвертора или OFX и QIF конвертора. Прегледайте генерираните записи, преди да ги добавите към вашите книги.