TL;DR: Bank Statement Parser 是一個開源 Python 函式庫，可將七種銀行對帳單格式（CAMT.053、PAIN.001、CSV、OFX、QFX、MT940 及 PDF）解析為 pandas DataFrame。混合 PDF 管線搭配餘額驗證、REST API、交易增強、帳本匯出，吞吐量達 27K+ tx/s。
Bank Statement Parser 是一個開源 Python 函式庫，可將七種格式的銀行對帳單解析為結構化的 pandas DataFrame。確定性核心在本機處理結構化格式，零網路呼叫。可選的混合 PDF 管線透過本機 LLM（經由 Ollama）處理數位及掃描對帳單。
適用對象
- 財務團隊：正從 MT940 遷移至 CAMT.053，需要一個在過渡期間同時處理新舊格式的解析器，加上處理銀行未提供結構化匯出的 PDF 對帳單。
- 金融科技開發人員：建構對帳、報表或記帳管線，想要單一依賴項並內建餘額驗證、分類及帳本匯出功能。
- 合規團隊：需要預設 PII 遮蔽、確定性輸出，以及可在差異進入帳本前標記的黃金法則驗證。
- 純文字記帳使用者：想要從 PDF 銀行對帳單自動匯入 hledger 或 beancount 日記帳。
- 任何人：當本機開源工具就能完成工作時，拒絕將敏感財務資料傳送至第三方 SaaS。
支援的格式
| 格式 | 標準 | 檔案類型 | 解析器/方法 |
|---|---|---|---|
| CAMT.053 | ISO 20022 銀行對客戶對帳單 | .xml |
CamtParser |
| PAIN.001 | ISO 20022 貸記轉帳啟動 | .xml |
Pain001Parser |
| CSV | 一般銀行匯出 | .csv |
CsvStatementParser |
| OFX | Open Financial Exchange | .ofx |
OfxParser |
| QFX | Quicken Financial Exchange | .qfx |
QfxParser |
| MT940 | SWIFT 標準 | .mt940, .sta |
Mt940Parser |
| 數位及掃描對帳單 | .pdf |
smart_ingest() |
所有格式都會產生具有一致欄位名稱的標準化 pandas DataFrame，使下游處理與格式無關。
核心功能
- 混合 PDF 管線：
smart_ingest()將 PDF 路由至三條路徑——確定性表格擷取、文字 LLM 或視覺 LLM——並自動執行黃金法則餘額驗證。 - 格式自動偵測：
detect_statement_format()辨識格式；create_parser()實例化對應的解析器。 - 餘額驗證：黃金法則檢查（
opening + credits − debits == closing），狀態為 VERIFIED / DISCREPANCY / FAILED。 - 多幣別驗證：
verify_balance_multi_currency()依幣別群組分組交易，獨立驗證。 - REST API：FastAPI 微服務，提供
/ingest及/health端點，可用於正式部署。 - 交易增強：LLM 驅動的交易分類，支援可插拔的分類架構（預設為 Plaid 13 類別）。
- 互動式審核：透過
--type review逐筆檢視差異，可執行接受/編輯/跳過/刪除操作。 - 帳本匯出：
to_hledger()及to_beancount()支援純文字記帳工作流程。 - 批次掃描：
scan_and_ingest()處理整個資料夾樹狀結構，自動跨檔案去重。 - 帳戶對應：從 JSON 設定檔讀取正規表示式帳戶對應規則，用於帳本匯出。
- 串流解析：使用
parse_streaming()處理大型檔案（50 MB+、50K+ 筆交易），記憶體用量固定。 - 平行處理：透過
parse_files_parallel()使用 ProcessPoolExecutor 同時解析多個檔案。 - 去重：冪等
transaction_hash（MD5 指紋），適用於安全的增量匯入。 - 記憶體中解析：
from_string()及from_bytes()適用於 SFTP 和 API 工作流程，無磁碟 I/O。 - 安全 ZIP 處理：
iter_secure_xml_entries()具有壓縮比限制、條目大小上限及加密條目拒絕功能。 - 匯出：CSV、JSON、Excel（
.xlsx）、Polars DataFrame、hledger 及 beancount 日記帳。
安全與隱私
- PII 遮蔽：預設在 CLI 輸出中遮蔽姓名、IBAN 及地址。透過
--show-pii選擇顯示。 - XXE 保護：XML 解析使用
resolve_entities=False、no_network=True、load_dtd=False。 - ZIP 炸彈保護：壓縮比限制（預設 100:1）、條目大小上限（10 MB）、加密條目拒絕。
- 路徑遍歷防護：危險模式阻擋清單及符號連結解析。
- 供應鏈安全：SHA-256 雜湊鎖定相依性、CycloneDX SBOM、建置來源證明。
- 僅限本機 LLM：混合 PDF 管線使用 Ollama 進行本機推論——不會將資料傳送至雲端 API。
效能
| 指標 | 數值 |
|---|---|
| CAMT.053 吞吐量 | 27,000+ tx/s |
| PAIN.001 吞吐量 | 52,000+ tx/s |
| 每筆交易延遲（CAMT） | 37 微秒 |
| 每筆交易延遲（PAIN.001） | 19 微秒 |
| 首次回傳結果時間 | < 2 ms |
| 記憶體擴展（1K-50K tx） | 固定（串流） |
| 測試覆蓋率 | 100% 分支覆蓋率 |
| 測試數量 | 29 個測試檔案中共 718 項 |
開始建構
[開始安裝與範例 ❯][01]
[01]: /getting-started/index.html “入門” “GitHub 儲存庫”