銀行對帳單解析器

資料隱私和合規性

是否有任何資料離開我的基礎設施？

**不。 ** 銀行對帳單解析器以無狀態庫運作。所有處理——解析、PII 編輯、存檔提取——都發生在本地運行時記憶體中。沒有 API 呼叫、沒有雲端服務、沒有遙測。 XML 解析器經過強化no_network=True，在解析器層級阻止所有出站存取。您的財務數據永遠不會離開您的環境。

PII 編輯如何運作？

敏感欄位在到達您的應用程式邏輯之前會被屏蔽。解析器識別債務人姓名、債權人姓名、IBAN 和郵政地址，並將其替換為***REDACTED***在控制台輸出和流模式下。

• 在 CLI 輸出和流模式下預設啟用編輯功能。
• 檔案匯出（CSV、JSON、Excel）保留未編輯的資料以供下游處理。
• 選擇加入完整數據--show-pii在 CLI 上或redact_pii=False在 API 中。

提取過程是確定性的嗎？

**是的－每次執行時輸出位元組相同。 **給定相同的輸入文件，解析器每次都會產生相同的結果。沒有隨機性，沒有模型推理，沒有啟發式取樣。 CI 透過 100% 分支覆蓋率的 467 項測試強制執行確定性，包括透過假設進行基於屬性的模糊測試。

該專案遵循哪些合規標準？

此專案維護符合 ISO 13485 的文件並具有完全可追溯性：

• 量化的風險登記冊，包含嚴重性/機率評分和殘餘風險評估。
• 驗證和驗證計劃，包含 5 個階段的 19 個門控步驟。
• 具有影響評估和回滾協議的變更控製程序。
• SOUP Register 涵蓋所有依賴項以及風險等級和 EOL 追蹤。
• 可追溯性矩陣將設計輸入對應到實作和驗證。

每個版本都包含 CycloneDX SBOM、SHA-256 校驗和以及 GitHub 建置來源證明。

效能和可擴充性

銀行對帳單解析器有多快？

每次提交時都會在 CI 中驗證效能閾值：

如何處理大檔案？

**具有有限記憶體的串流 - 在每個檔案 50,000 個事務下進行測試。 ** 使用parse_streaming()增量處理 XML 檔。每筆交易都會產生一個字典；處理後清除元素以防止記憶體增長。記憶體不會隨檔案大小而擴展 - 50K 事務測試 (25+ MB) 使用的記憶體不到 10K 事務測試的 2 倍。

對於超過 50 MB 的檔案（例如，具有 100K 以上付款的主機到主機 PAIN.001 批次），解析器透過基於區塊的命名空間剝離的臨時檔案進行串流 - 完整文件永遠不會載入到記憶體中。

ZIP 檔案如何安全處理？

iter_secure_xml_entries()在提取之前驗證每個成員：

• 條目大小上限（每個條目預設 10 MB）
• 未壓縮總大小上限（預設 50 MB）
• 壓縮比限制（預設100:1）以防止ZIP炸彈
• 加密進入拒絕

沒有文件寫入磁碟。 XML 位元組直接傳遞給解析器from_bytes().

我可以並行解析多個檔案嗎？

**是的。 ** 使用parse_files_parallel()它將工作分配給ProcessPoolExecutor:

from bankstatementparser import parse_files_parallel

results = parse_files_parallel([
    "statements/jan.xml",
    "statements/feb.xml",
    "statements/mar.xml",
])
for r in results:
    print(r.path, r.status, len(r.transactions), "rows")

支援的格式

支援哪些銀行對帳單格式？

格式	標準	文件類型	解析器類別
CAMT.053	ISO 20022 銀行對客戶聲明	.xml	CamtParser
疼痛.001	ISO 20022 學分轉移啟動	.xml	Pain001Parser
CSV	一般銀行出口	.csv	CsvStatementParser
氧氟沙星	開放金融交易所	.ofx	OfxParser
QFX	加快金融交流	.qfx	QfxParser
MT940	SWIFT標準	.mt940, .sta	Mt940Parser

解析器是否處理 CAMT.053 的銀行特定方言？

**是的 - 設計上與命名空間無關。 ** 解析器在處理之前剝離 XML 命名空間，處理任何 CAMT.053 變體（camt.053.001.02, camt.053.001.04或專有銀行包裝器），無需特定於命名空間的配置。 XPath 查詢目標元素結構，而不是命名空間 URI。

對於將 CAMT 包裝在自訂信封中的銀行，請使用from_string()或者from_bytes()直接送入內部文件。

我可以將自訂 CSV 列標題對應到標準架構嗎？

**是的－自動標準化，零配置。 **CsvStatementParser識別常見的標頭變化："Date", "Transaction Date", "Booking Date"全部映射到date場地。"Amount", "Value", "Sum"映射到amount。拆分貸方/借方欄（例如，"Credit"和"Debit"）被自動偵測並組合成單一簽名金額。

輸出格式是什麼？

所有解析器都會產生具有一致列類型的標準化 pandas DataFrame：

格式	關鍵欄
CAMT	Amount, Currency, DrCr, Debtor, Creditor, Reference, ValDt, BookgDt, AccountId
疼痛.001	PmtInfId, PmtMtd, InstdAmt, Currency, CdtrNm, EndToEndId, MsgId, CreDtTm, NbOfTxs
CSV/OFX/QFX/MT940	date, description, amount（標準化）

您也可以匯出為 CSV、JSON、Excel，或轉換為 Polars DataFrame。

財務工作流程

解析器如何處理多幣種語句？

**每筆交易都保留其原始貨幣－沒有隱式轉換。 **Currency字段是從 XML 中提取的Ccy每筆交易的屬性。多幣種報表保持原樣。這get_account_balances()方法傳回每個帳戶的期初和期末餘額以及原始貨幣代碼。跨貨幣對帳留給您的下游邏輯，您可以在其中控制匯率來源。

解析器是否支援傳出和傳入格式？

**是的。 **Pain001Parser處理 ISO 20022 PAIN.001 信用轉帳啟動文件（付款）。CamtParser處理 CAMT.053 銀行對客戶的報表文件（傳入報告）。兩者都支援串流、PII 編輯以及匯出到 CSV、JSON 和 Excel。使用detect_statement_format()自動辨識格式。

當交易條目格式錯誤時會發生什麼事？

行為取決於解析模式：

• parse()（批次模式） -- 格式錯誤的條目缺少必填欄位（Amount, Currency， 或者CdtDbtInd）會被跳過並帶有警告日誌。語句的其餘部分正常解析。
• parse_streaming()（流模式） -- 解析錯誤立即作為異常傳播。無靜默資料遺失。這種快速失敗行為是針對必須考慮每筆交易的財務工作流程而設計的。

重複資料刪除如何運作？

這Deduplicator類別檢測精確的重複項和可疑的匹配項以及可解釋的置信度分數：

from bankstatementparser import CamtParser, Deduplicator

parser = CamtParser("statement.xml")
dedup = Deduplicator()
result = dedup.deduplicate(dedup.from_dataframe(parser.parse()))

print(f"Unique: {len(result.unique_transactions)}")
print(f"Exact duplicates: {len(result.exact_duplicates)}")
print(f"Suspected matches: {len(result.suspected_matches)}")

安裝與相容性

如何安裝銀行對帳單解析器？

pip install bankstatementparser

對於可選的 Polars DataFrame 支援：

pip install bankstatementparser[polars]

支援哪些 Python 版本？

Python 3.9 到 3.14。所有版本均在 CI 中進行了 467 次測試，分支覆蓋率為 100%。

有哪些依賴項？

該庫有 5 個直接依賴項：

• lxml-- XML解析與安全加固 -pandas-- 資料框架與資料操作 -openpyxl-- Excel匯出 -pydantic-- 資料驗證與模型 -defusedxml--XXE保護

所有相依性都有 SHA-256 哈希鎖定版本。 CycloneDX SBOM 對應每個運行時元件。

它可以在 macOS、Linux 和 Windows 上運行嗎？

**是的。 ** 此函式庫適用於 macOS、Linux 和 Windows（透過 WSL）。它沒有特定於平台的依賴性。

再現性和安全性

如何驗證再現性？

python -m pytest                              # 467 tests, 100% branch coverage
python scripts/verify_locked_hashes.py        # SHA-256 hash verification
git log --show-signature -1                   # Verify commit signature

內建了哪些安全保護？

• XXE 保護：resolve_entities=False, no_network=True, load_dtd=False
• ZIP 炸彈保護：壓縮比限制、條目大小上限、加密條目拒絕
• 路徑遍歷預防：危險模式阻止清單和符號連結解析
• 輸入驗證：檔案大小限制（預設 100 MB）、副檔名/格式驗證
• 供應鏈：SHA-256 雜湊鎖定相依性、CycloneDX SBOM、建置來源證明
• 簽名提交：在 CI 中強制執行

銀行對帳單解析器與 pyiso20022 相比如何？

pyiso20022 是一個廣泛的 ISO 20022 工具包，可從 ISO XML 模式產生 Python 資料類別。它涵蓋了廣泛的 ISO 20022 訊息類型（PACS、PAIN、CAMT、ADMI）以及模式驗證。銀行對帳單解析器專為銀行對帳單解析而構建，具有串流支援、PII 編輯、重複資料刪除和跨六種格式（包括非 ISO 格式（CSV、OFX、QFX、MT940））的統一 API。如果您需要將銀行對帳單解析為具有生產級安全性的 DataFrame，請使用銀行對帳單解析器。如果您需要使用完整的 ISO 20022 訊息目錄，請使用 pyiso20022。

SWIFT ISO 20022 遷移截止日期是多少？

SWIFT 發布了分階段遷移時間表：

• 2026 年 11 月：結構化和混合地址成為強制性要求。 MT101多指令訊息將被拒絕。個案管理第一階段開始。
• 2027 年 11 月：所有金融機構都必須能夠本地接收 CAMT.053 報表。 SWIFT 將停止將 MT 轉換為 ISO 格式。
• 2028 年 11 月：MT940、MT942、MT950、MT900 和 MT910 全面退役。這些將被 CAMT.052、CAMT.053 和 CAMT.054 等效項取代。

銀行對帳單解析器支援舊版 MT940 格式和現代 CAMT.053/PAIN.001 格式，使其成為過渡時期的理想選擇。