Импортиране на банково CSV в Beancount с bea

Обикновен банков CSV файл не изисква Python importer. Картирайте колоните му с --csv, задайте името на изходната сметка с --account, категоризирайте редовете с --rules, след което прегледайте и приложете записите с bea import.

Нужен ви е съществуващ ledger. Ако започвате нови книги, следвайте CLI quick start. Запазете оригиналното банково извлечение, за да можете да го сравните с прегледа.

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

Сумите следват банковата конвенция за знаци: разходите са отрицателни, а депозитите – положителни. Валутата по подразбиране е оперативната валута на ledger-а, така че този файл не се нуждае от колона за валута. Поставете колона с банково описание в narration и запазете payee за търговеца.

Създайте ledger-а и отворете подсметката за гориво, използвана по-долу:

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

Правилата съвпадат първо с payee, след това с narration, като не се прави разлика между главни и малки букви. Първото съвпадащо правило печели. Редове, за които никое правило не съвпада, се осчетоводяват в Expenses:Uncategorized с флаг ! за по-късен преглед. Ръководството IMPORTING на продукта документира пълния справочник за картиране, включително двойката debit и credit, колоната category и четенето на заглавен ред с --csv auto.

Нищо не се записва в ledger-а още. Прегледът отчита 3 ready, 0 exact duplicates, 0 possible duplicates и излиза с код 0. Неговата колона RULE посочва печелившия модел за всеки ред или unmatched за реда Unknown Shop. Прегледайте датите, payee-тата, подписаните изходни суми, целевите сметки, съвпаденията за дубликати и предложения diff на файла. Поправете грешно правило или категория и направете отново преглед. Отворете всички липсващи сметки преди прилагане на импорта: правило, което посочва сметка, която ledger-ът не е отворил, причинява грешка при валидация.

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"

Картирането на колоните се запомня за всеки ledger, заглавен ред и изходна сметка, така че --apply се изпълнява отново без флагове и отчита, използвайки запомненото картиране на колоните. То преизчислява прегледа спрямо текущите файлове, валидира целия кандидат ledger преди запис и записва 3 записа. bea check не отчита грешки. Опашката ! изброява единния несъвпадащ ред: Unknown Shop с mystery при -9.99 USD. Успешната проверка доказва само че ledger-ът е балансиран и валиден. Тя не казва нищо за това дали този ред принадлежи в Expenses:Uncategorized, затова го прекатегоризирайте съзнателно в ledger-а си. Проверката завършва при 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 с хеш на съдържанието, така че идентичният файл съвпада с всеки ред. Запазете тези метаданни при редактиране на импортирани записи. Импортирането добавя записи; то не актуализира или изтрива съществуваща транзакция. Правете корекциите съзнателно в ledger-а си и след това изпълнете bea check. Масовото добавяне на JSON записи с bea add transactions няма откриване на дубликати.

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

По-късно изтегляне може да повтори ред с различно narration или банкови идентификатори. Датата, нормализираният payee и подписаната изходна сума все още го маркират като възможно съвпадение:

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

По подразбиране --duplicates review отказва да приложи неразрешени съвпадения. При проверка втори файл, повтарящ реда 2026-08-02 Whole Foods -20.00 USD с различно narration, се прегледа като 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, за да запазите легитимни повторени покупки. Решението се отнася за всички възможни съвпадения в това извикване. Точните дубликати остават пропуснати. Конфликтите в идентификаторите все още блокират записа. --no-input и --yes не заобикалят този преглед. Осъзнато решение да пропуснете всеки ред излиза с код 0 и без добавяния в ledger-а.

6. Използване на Python importer за други формати​

За формати, които картирането на колони не може да изрази, като OFX или QIF, или CSV с необичайно оформление, bea import извиква конфигуриран importer, използвайки текущия интерфейс на Beangulp: identify(filepath), account(filepath) и extract(filepath, existing). Importer-ът отговаря за банково-специфичното разборване и категоризация. Той трябва да предостави изрични суми в постовите на изходната сметка, така че съвпадението на дубликати да използва действителните банкови суми. Python importer остава усъвършенстваният път за тези формати. За родния CSV на банката опитайте първо --csv.

За първо пробно изпълнение запазете примерната конфигурация за категоризиране на CSV като importers.py до основния си ledger. Тя използва само 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, ...]. Ако няколко importer-а разпознаят файла, изберете един по име. Неизвестно име показва списъка с конфигурирани имена. Познат importer, който не разпознава файла, съобщава това отделно.

CLI запомня пътя на конфигурацията за този основен ledger. Бъдещи изпълнения избират изричния --config, след това запомнения път, а след това importers.py до основния файл. Изходът посочва пътя и откъде идва.

--apply преизчислява прегледа спрямо текущите файлове. Той валидира целия кандидат ledger преди запис. Грешка при валидация оставя оригиналния ledger непроменен и излиза с код 1. Едновременна промяна на ledger-а излиза с код 4; прегледайте промяната и направете нов преглед, преди да опитате отново.

Поддържане на импортите възпроизводими​

По подразбиране проверката за дубликати проверява метаданните bank_id, fitid, transaction_id и imported_id в изходната сметка на importer-а. Използвайте повторени опции --id-key KEY, за да замените този набор.

Ред със стабилен банков идентификатор се записва с метаданни import-id, които посочват вида му, като префикс bank: или ofx:. Ред без такъв се записва с хеш на съдържанието csv:sha256: върху неговата дата, сума, описание и сметка, така че повторното импортиране на същия файл пропуска всеки ред. Записи, написани преди тази конвенция, може все още да носят метаданни bea_import_id, като тези също съвпадат при повторен импорт. Възможните съвпадения се проверяват спрямо съществуващи транзакции и приети редове в същата партида.

Payee-тата, narration-ите и низовите метаданни заменят новите редове с интервали преди прегледа и записа. Кавички и обратни наклонени черти запазват съдържанието си. Затова импортираният търговски текст остава четим на един ред в ledger-а.

Запис в включен файл​

Дръжте --file насочен към основния файл и изберете целевия файл с --into:

bea --file books/main.bean import statement.csv --into 2026.bean
bea --file books/main.bean import statement.csv --into 2026.bean --apply

2026.bean трябва вече да съществува и да бъде включен от основния файл. Неговият път е относителен към основната директория. Пътят на експортния файл остава относителен към вашата работна директория. Прегледът идентифицира файла, който ще се промени.

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

bea --file books/main.bean --json --no-input import statement.csv --apply --duplicates skip

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

Отстраняване на проблеми с importer​

Конфигурациите на importer-ите се изпълняват в управлявания engine. Ако конфигурация импортира 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.py

bea engine status отчита активираните функции. Инсталирането на банков importer до frontend-а bea не го прави достъпен вътре в engine-а. Конфигурация, която импортира допълнителни пакети, се нуждае от тези зависимости в engine-а; активирането само на Beangulp не ги инсталира. Използвайте CSV mapper-а или конверторите по-долу, когато тези importer зависимости не са налични.

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

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