وارد کردن خروجی‌های بانکی با CLI

از bea import برای پیش‌نمایش یک خروجی بانکی، بررسی موارد تکراری، و افزودن ورودی‌های تأییدشده به دفتر کل محلی خود استفاده کنید.

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

1. انتخاب یک ایمپورتر​

یک ایمپورتر فایل بانک را می‌خواند و حساب‌های تراکنش را ارائه می‌دهد. Bea فرمت را حدس نمی‌زند یا خریدها را با یک مدل هوش مصنوعی دسته‌بندی نمی‌کند.

پیکربندی importers.py شما CONFIG = [importer, ...] را صادر می‌کند. ایمپورترها از رابط فعلی Beangulp استفاده می‌کنند: identify(filepath)، account(filepath)، و extract(filepath, existing). ثبت‌های حساب منبع به مبالغ صریح برای تطبیق موارد تکراری نیاز دارند.

برای اولین اجرای تمرینی، پیکربندی مثال CSV دسته‌بندی‌شده را به‌عنوان importers.py در کنار دفتر کل ریشه خود ذخیره کنید. این فقط از Beancount و کتابخانه استاندارد پایتون استفاده می‌کند، بنابراین با نصب 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 بومی بانک، از ایمپورتری که برای بانک شما نوشته شده استفاده کنید. پیکربندی نمونه دقیقاً انتظار ستون‌های بالا را دارد. فقط پیکربندی‌های پایتونی را که به آن‌ها اعتماد دارید اجرا کنید.

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

این را از دایرکتوری حاوی main.bean اجرا کنید:

bea import bank.csv --config importers.py

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

برای نمونه، پیش‌نمایش باید شامل یک هزینه غذاخوری 5.25 دلاری و یک سپرده حقوق 1000 دلاری باشد. یک دسته نادرست را در ایمپورتر یا داده منبع اصلاح کنید، سپس دوباره پیش‌نمایش بگیرید. قبل از اعمال واردات، هر حساب از دست رفته را باز کنید.

اگر چند ایمپورتر فایل را تشخیص دهند، یکی را با نام انتخاب کنید:

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 و کد خروجی مراجعه کنید.

رفع اشکال یک ایمپورتر​

اگر پیکربندی بسته‌های شخص ثالث را وارد کند، آن بسته‌ها باید در محیط پایتون اجراکننده 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 است.

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