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がもう一方の勘定を提供します。両方のカテゴリはbea initによって作成されたUSDテンプレートに含まれています。
銀行のネイティブ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 10CLIはこのルート台帳の設定パスを記憶します。今後の実行では、明示的な--config、次に記憶されたパス、その次にルートの横のimporters.pyを選択します。出力はパスとその出所を名前で示します。
--applyは現在のファイルに対してプレビューを再計算します。書き込み前に完全な候補台帳を検証します。検証に失敗した場合、元の台帳は変更されず、終了コード1で終了します。同時の台帳変更は終了コード4で終了します。変更を検査し、再試行する前に新しいプレビューを実行してください。
4. 可能性のある重複を解決する
同じサンプルインポートを繰り返すと、既存のエントリはスキップされます。重複するエクスポートには、判断が必要な行も含まれる場合があります：
| プレビューステータス | 意味 | 対処方法 |
|---|---|---|
new | 重複の証拠が見つかりませんでした | 金額とカテゴリを確認してください |
duplicate | 安定したIDと取引詳細が一致するか、同一の非取引ディレクティブが存在します | すでにスキップされています |
possible_duplicate | 日付、正規化された支払先、符号付きソース金額/通貨が一致します | プレビューと既存のエントリを比較してください |
conflict | 安定したIDが異なる取引詳細と一致します | IDまたはデータの不一致を解決し、再度プレビューしてください |
異なる銀行IDは重複を排除しません。銀行は後のダウンロードでIDを変更することがあります。また、2つの実際の購入が日付、支払先、金額を共有することもあります。
すべての可能なマッチを確認した後、次のいずれかの代替案を選択してください：
bea import bank.csv --apply --duplicates skipbea import bank.csv --apply --duplicates includeこの決定は、その呼び出し内のすべての可能なマッチに適用されます。正確な重複はスキップされたままです。ID競合は書き込みをブロックします。
デフォルトの--duplicates reviewは、未解決のマッチの適用を拒否します。終了コード4で終了し、影響を受けるプレビュー行を名前で示します。--no-inputと--yesはそのレビューをバイパスしません。すべての行をスキップする意図的な決定は、台帳への追加なしで終了コード0で終了します。
インポートを繰り返し可能に保つ
デフォルトでは、重複マッチングはインポーターのソース勘定内のbank_id、fitid、transaction_id、imported_idメタデータをチェックします。繰り返しの--id-key KEYオプションを使用して、そのセットを置き換えてください。
CLIはまた、元のエクスポート内の行を識別するためにbea_import_idメタデータを書き込みます。インポートしたエントリを編集するときはそれを保持してください。可能なマッチは、既存の取引と同じバッチ内の受け入れられた行に対してチェックされます。
支払先、説明、および文字列メタデータは、プレビューと書き込みの前に改行をスペースに置き換えます。引用符とバックスラッシュは内容を保持します。したがって、インポートされた取引者テキストは単一の台帳行で読みやすいままです。
インポートはエントリを追加します。既存の取引を更新または削除しません。台帳で意図的に修正し、その後bea checkを実行してください。bea add transactionsによるバルクJSONエントリには重複検出がありません。
インクルードされたファイルに書き込む
--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 --apply2026.beanはすでに存在し、ルートにインクルードされている必要があります。そのパスはルートディレクトリに対する相対パスです。エクスポートパスは作業ディレクトリに対する相対パスのままです。プレビューは変更されるファイルを識別します。
スクリプトでインポートを使用する
bea --json --no-input import bank.csv --apply --duplicates skip可能なマッチに対する意図したポリシーである場合にのみskipを選択してください。JSONはプレビューと書き込み数をdata内に返します。拒否された適用は、written: 0で標準エラー出力のerror.resultにプレビューを置きます。常に終了ステータスを確認してください。無人インポートをスケジュールする前に、JSONと終了コードリファレンスを参照してください。
インポーターのトラブルシューティング
設定がサードパーティのパッケージをインポートする場合、それらのパッケージはbeaを実行するPython環境に存在する必要があります。例：
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です。
Pythonインポーターを使用しない一度きりの変換には、CSVコンバーターまたはOFXおよびQIFコンバーターを試してください。生成されたエントリを帳簿に追加する前に確認してください。