وارد کردن CSV بانکی به Beancount با bea

یک CSV بانکی معمولی به ایمپورتر پایتونی نیاز ندارد. ستونهای آن را با --csv نگاشت کنید، حساب منبع را با --account نامگذاری کنید، ردیفها را با --rules دستهبندی کنید، سپس ورودیها را با bea import پیشنمایش و اعمال کنید.

شما به یک دفتر کل موجود نیاز دارید. اگر کتابهای جدیدی شروع میکنید، از شروع سریع CLI پیروی کنید. خروجی اصلی بانک را نگه دارید تا بتوانید آن را با پیشنمایش مقایسه کنید.

۱. نگاشت ستونهای 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 قبل از زیردستور قرار میگیرند.

۲. پیشنمایش ورودیها​

این قوانین دستهبندی را با نام 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 محصول، مرجع کامل نگاشت، از جمله جفت debit و credit، ستون category و خواندن هدر --csv auto را مستند میکند.

هنوز چیزی در دفتر کل نوشته نشده است. پیشنمایش 3 ready, 0 exact duplicates, 0 possible duplicates را گزارش میدهد و با کد ۰ خارج میشود. ستون RULE آن الگوی برنده را برای هر ردیف نام میبرد، یا برای ردیف Unknown Shop مقدار unmatched را نشان میدهد. تاریخها، فروشندگان، مبالغ منبع علامتدار، حسابهای مقصد، موارد تکراری و diff پیشنهادی فایل را بررسی کنید. یک قانون یا دستهبندی نادرست را اصلاح کنید، سپس دوباره پیشنمایش بگیرید. قبل از اعمال واردات، هر حساب از دست رفته را باز کنید: قانونی که حسابی را نام میبرد که دفتر کل آن را باز نکرده است، در اعتبارسنجی شکست میخورد.

۳. اعمال ورودیهای بررسیشده​

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 بدون هیچ پرچمی دوباره اجرا میشود و با استفاده از نگاشت ستون به خاطر سپردهشده گزارش میدهد. این دستور پیشنمایش را در برابر فایلهای فعلی دوباره محاسبه میکند، کل دفتر کل نامزد را قبل از نوشتن اعتبارسنجی میکند و ۳ ورودی مینویسد. bea check هیچ خطایی گزارش نمیکند. صف ! یک ردیف بدون تطابق را فهرست میکند: Unknown Shop با mystery به مبلغ -9.99 USD. یک بررسی موفق فقط ثابت میکند که دفتر کل متوازن و معتبر است. این بررسی هیچ چیز درباره اینکه آیا آن ردیف متعلق به Expenses:Uncategorized است یا نه، نمیگوید، بنابراین آن را به طور عمدی در دفتر کل خود دستهبندی مجدد کنید. بررسی با 930.01 USD به پایان میرسد: موجودی افتتاحیه 1,000 USD منهای 69.99 USD هزینه.

۴. وارداتهای مکرر چیزی اضافه نمیکنند​

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

پیشنمایش 0 ready, 3 exact duplicates را گزارش میدهد و اجرا با کد ۰ تعداد ۰ ورودی مینویسد. هر ردیف نوشتهشده دارای فراداده import-id با هش محتوا است، بنابراین فایل یکسان با هر ردیف مطابقت دارد. هنگام ویرایش ورودیهای واردشده، آن فراداده را حفظ کنید. وارد کردن ورودیها را اضافه میکند؛ تراکنش موجود را بهروزرسانی یا حذف نمیکند. اصلاحات را به طور عمدی در دفتر کل خود انجام دهید و پس از آن bea check را اجرا کنید. ورود انبوه JSON با bea add transactions تشخیص تکراری ندارد.

۵. حل موارد تکراری احتمالی​

یک دانلود بعدی میتواند یک ردیف را با شرح یا شناسه بانکی متفاوت تکرار کند. تاریخ، فروشنده نرمالسازیشده و مبلغ منبع علامتدار همچنان آن را به عنوان تطابق احتمالی علامتگذاری میکنند:

یک شناسه بانکی متفاوت، تکرار را رد نمیکند. بانکها میتوانند شناسهها را در دانلودهای بعدی تغییر دهند. دو خرید واقعی نیز میتوانند تاریخ، فروشنده و مبلغ مشترکی داشته باشند، بنابراین تطابق احتمالی شواهد است نه اثبات. Bea با یک مدل هوش مصنوعی حدس نمیزند و هرگز فراتر از قوانین شما دستهبندی نمیکند.

پیشفرض --duplicates review از اعمال تطابقهای حلنشده خودداری میکند. در یک اجرای تأییدی، فایل دومی که ردیف 2026-08-02 Whole Foods -20.00 USD را با شرح متفاوتی تکرار میکرد، به عنوان ۱ مورد تکراری احتمالی پیشنمایش شد و --apply با کد ۴ و بدون هیچ نوشتهای خارج شد. پس از بررسی هر تطابق احتمالی، یکی از این گزینههای جایگزین را انتخاب کنید:

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 این بررسی را دور نمیزنند. تصمیم عمدی برای رد کردن هر ردیف با کد ۰ و بدون افزودن به دفتر کل خارج میشود.

۶. استفاده از ایمپورتر پایتونی برای سایر فرمتها​

برای فرمتهایی که نگاشت ستون نمیتواند بیان کند، مانند OFX یا QIF یا یک CSV با چیدمان غیرمعمول، bea import یک ایمپورتر پیکربندیشده را با استفاده از رابط فعلی Beangulp فراخوانی میکند: identify(filepath)، account(filepath) و extract(filepath, existing). ایمپورتر مالک تجزیه و دستهبندی خاص بانک است. این ایمپورتر باید مبالغ صریحی در پستهای حساب منبع ارائه دهد تا تطابق تکراری از مبالغ واقعی بانک استفاده کند. یک ایمپورتر پایتونی همچنان مسیر پیشرفته برای این فرمتها است. برای CSV بومی بانک، ابتدا --csv را امتحان کنید.

برای یک اجرای تمرینی ابتدایی، پیکربندی CSV دستهبندیشده نمونه را با نام importers.py در کنار دفتر کل ریشهای خود ذخیره کنید. این پیکربندی فقط از Beancount و کتابخانه استاندارد پایتون استفاده میکند، بنابراین با نصب Homebrew کار میکند. فایل نمونه bank.csv آن از یک مبلغ علامتدار حساب جاری استفاده میکند: هزینه غذاخوری -5.25 USD و سپرده حقوق 1,000 USD. پیکربندی نمونه دقیقاً انتظار ستونهای مستند خود را دارد. فقط پیکربندیهای پایتونی را اجرا کنید که به آنها اعتماد دارید.

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 پیشنمایش را در برابر فایلهای فعلی دوباره محاسبه میکند. این دستور کل دفتر کل نامزد را قبل از نوشتن اعتبارسنجی میکند. شکست اعتبارسنجی دفتر کل اصلی را بدون تغییر میگذارد و با کد ۱ خارج میشود. تغییر همزمان در دفتر کل با کد ۴ خارج میشود؛ تغییر را بررسی کنید و قبل از تلاش مجدد یک پیشنمایش تازه بگیرید.

وارداتها را تکراریپذیر نگه دارید​

به طور پیشفرض، تطابق تکراری فرادادههای 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 --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 و کدهای خروج مراجعه کنید.

عیبیابی یک ایمپورتر​

پیکربندیهای ایمپورتر در موتور مدیریتشده اجرا میشوند. اگر یک پیکربندی 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 ویژگیهای فعال را گزارش میدهد. نصب یک ایمپورتر بانکی در کنار فرانتاند bea آن را در دسترس موتور قرار نمیدهد. یک پیکربندی که بستههای اضافی را وارد میکند به آن وابستگیها در موتور نیاز دارد؛ فعال کردن Beangulp به تنهایی آنها را نصب نمیکند. زمانی که آن وابستگیهای ایمپورتر در دسترس نیستند، از نگاشتگر CSV یا مبدلهای زیر استفاده کنید.

برای یک استثنای ایمپورتر، --debug را قبل از دستور قرار دهید تا traceback آن نمایش داده شود. خروجی ایمپورتر در importer_output گرفته میشود تا JSON را خراب نکند. در حالت JSON اشکالزدایی، traceback در error.traceback است.

برای تبدیل یکباره بدون ایمپورتر پایتونی، مبدل CSV یا مبدل OFX و QIF را امتحان کنید. قبل از افزودن ورودیهای تولیدشده به کتابهای خود، آنها را بررسی کنید.