银行对账单解析器

数据隐私和合规性

是否有任何数据离开我的基础设施？

不。 银行对账单解析器作为无状态库运行。所有处理——解析、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 格式，使其成为过渡时期的理想选择。