告别手工对账：用 Python 把意大利邮政 PDF 报表一键变成 JSON/CSV

“如果你也在意大利留学、工作或生活，每个月从 Poste Italiane 下载的 PDF 报表一定让你又爱又恨：数据齐全却难以整理，手工誊抄既费时又容易出错。”
这篇文章将手把手教你用一款开源工具——Poste Italiane Documents Parser——把 BancoPosta 对账单、Postepay Evolution 交易明细等 PDF 文件批量转成结构化的 JSON 或 CSV，从此告别机械式复制粘贴。

为什么需要把 PDF 转换成结构化数据
这款工具到底能做什么
支持哪些意大利邮政文档
安装：一行命令搞定依赖
三分钟上手：从单文件到批量目录
把解析器当成 Python 库：嵌入你的项目
输出长什么样：字段逐一拆解
如何写测试：让结果可信
常见疑问与注意事项
下一步可以做什么

1. 为什么需要把 PDF 转换成结构化数据

时间成本：一份 Postepay 月度流水动辄上百行，手工录入平均耗时 30 分钟以上。
错误率：手动复制金额、日期，小数点错位或日期格式不统一，后期对账极其痛苦。
后续分析：只有把数据转成 JSON/CSV，才能用 Excel、Pandas、Tableau 等工具做预算分析、报销汇总、自动分类。

Poste Italiane 并没有提供官方 API，唯一的数据来源就是用户自己下载的 PDF。这款开源解析器填补了空白。

2. 这款工具到底能做什么

一句话总结：

“你扔给它一个或多个 PDF，它告诉你里面是什么类型的报表，并把里面的所有余额、交易、持卡人信息整理成干净的 JSON 或 CSV。”

特色功能：

功能点	说明
自动识别文档类型	无需手动指定，程序读 PDF 第一页就能判断是 BancoPosta 还是 Postepay
数据完整性校验	自动计算期初余额 ± 交易总额是否等于期末余额，发现异常立即报错
批量处理	支持文件夹递归扫描，一次性处理上百份文件
输出 JSON/CSV	默认 JSON，适合程序调用；加 `--format csv` 可直接用 Excel 打开
可嵌入 Python 项目	作为库调用，一行代码返回 Python 字典

3. 支持哪些意大利邮政文档

目前覆盖三类最常用的在线下载报表：

Estratto Conto BancoPosta
传统活期账户月度对账单，含 IBAN、期初/期末余额、逐笔交易。
Rendiconto Postepay Evolution
Postepay Evolution 预付卡的月度汇总，显示卡号、可用余额、充值/消费合计。
Lista Movimenti Postepay Evolution
与“Rendiconto”不同，它列出每一笔交易明细，包括授权日期、入账日期、商户描述。

未来版本可能会增加对 PostePay Standard、PosteMobile 账单的支持；项目接受 Pull Request。

4. 安装：一行命令搞定依赖

前置条件：Python 3.8 以上（含 pip）。

# 克隆仓库
git clone https://github.com/genbs/poste-italiane-parser.git
cd poste-italiane-parser

# 安装依赖
pip install -r requirements.txt

依赖极少，核心用到 pdfplumber 提取文本与表格，pydantic 做数据校验。安装过程不到一分钟。

5. 三分钟上手：从单文件到批量目录

5.1 准备 PDF

~/Documents/poste/
├── conto_corrente_luglio2025.pdf
├── postepay_evolution_giugno2025.pdf
└── altri_pdf/
    └── vecchio_statement.pdf

5.2 解析单个文件

python main.py --path "~/Documents/poste/conto_corrente_luglio2025.pdf"

默认会在同一目录生成 conto_corrente_luglio2025.json，可直接用 VS Code 打开查看。

5.3 解析整个目录并导出 CSV

python main.py "~/Documents/poste" \
               -o ~/Documents/poste/output \
               --format csv \
               --verbose

-o 指定输出文件夹，程序会按原名生成 .csv
--verbose 会在终端打印每份文件的识别类型与校验结果，方便排查异常

6. 把解析器当成 Python 库：嵌入你的项目

如果你已经有一个 Flask、Django 或数据分析脚本，只需把解析器当作库调用：

from poste_italiane_parser import PosteItalianeParser

file_path = "rendiconto_postepay.pdf"

try:
    data = PosteItalianeParser(file_path)
    print("文档类型:", data['document_type'])
    print("持卡人:", data['holder'])
    print("期末余额:", data['final_balance'])
except ValueError as e:
    print("校验失败:", e)
except FileNotFoundError:
    print("文件未找到")

返回的 data 是 Python 字典，可立即喂给 Pandas：

import pandas as pd
df = pd.DataFrame(data['transactions'])
df['value_date'] = pd.to_datetime(df['value_date'])
monthly_total = df.groupby(df['value_date'].dt.month)['value'].sum()
print(monthly_total)

7. 输出长什么样：字段逐一拆解

以最常见的 Estratto Conto BancoPosta 为例，解析后的 JSON 结构如下：

{
  "generated_at": "2025-07-24 10:30:00",
  "document_type": "ESTRATTO_CONTO",
  "currency": "EUR",
  "initial_balance": 1234.56,
  "final_balance": 987.65,
  "iban": "IT60X076011240000001234567890",
  "holder": "Mario Rossi",
  "card_number": null,
  "account_number": "000001234567",
  "period": {
    "start_date": "2025-07-01",
    "end_date": "2025-07-31"
  },
  "customer": {
    "name": "Mario Rossi",
    "street": "Via Roma 1",
    "city": "Milano"
  },
  "transactions": [
    {
      "accounting_date": "2025-07-05 00:00:00",
      "value_date": "2025-07-05 00:00:00",
      "description": "POS 1234567890123456 AMAZON EU",
      "debits": 49.99,
      "credits": 0.0,
      "value": -49.99
    },
    {
      "accounting_date": "2025-07-10 00:00:00",
      "value_date": "2025-07-10 00:00:00",
      "description": "ACCREDITO STIPENDIO",
      "debits": 0.0,
      "credits": 1500.0,
      "value": 1500.0
    }
  ]
}

字段说明（按字母排序）：

account_number – 银行内部账号
card_number – Postepay 卡号，仅在 Lista/Rendiconto 出现
currency – 交易货币，固定 EUR
customer – 持卡人完整地址信息
document_type – 识别出的文档类别
final_balance / initial_balance – 期初/期末账面余额
generated_at – 工具解析时间
holder – 持卡人姓名
iban – 国际银行账号
period – 账单起止日期
transactions – 逐笔交易数组，每项包含：
- accounting_date：入账日期
- value_date：起息日期（部分交易两者不同）
- description：原文描述
- debits / credits：借方/贷方金额
- value：带符号净额（贷正借负）

8. 如何写测试：让结果可信

项目作者出于隐私考虑，没有把真实 PDF 放进仓库，而是采用“结果文件比对”的测试策略。

8.1 创建测试基准文件

在 tests/ 目录新建 my_case.test.json，内容模板：

{
  "path": "tests/sample_statement.pdf",
  "currency": "EUR",
  "holder": "Giuseppe Verdi",
  "initial_balance": 100.0,
  "final_balance": 200.0,
  "iban": "IT60X076011240000001234567890",
  "transactions": [
    {
      "accounting_date": "2025-07-03 00:00:00",
      "value_date": "2025-07-03 00:00:00",
      "description": "BOLLETTINO 12345",
      "credits": 100.0,
      "debits": 0.0
    }
  ]
}

只需列出你关心的字段，程序会自动忽略多余键
支持部分匹配，例如只校验第一笔交易

8.2 运行测试

python -m unittest tests/test_PosteItalianeParser.py -v

若测试失败，终端会指出具体字段差异，方便你快速定位是 PDF 格式变更还是解析逻辑缺陷。

9. 常见疑问与注意事项

疑问	解答
PDF 加密能解析吗？	目前仅支持无密码保护的 PDF；下载时请选择“无密码”选项。
非标准格式会报错吗？	会抛出 `ValueError`，提示“未知文档类型”或“余额校验失败”。
Windows 中文路径支持吗？	支持，使用双引号包裹即可，例如 `--path "D:\文档\poste"`。
能否导出 Excel？	CSV 用 Excel 可直接打开，另存为 xlsx 即可。
商用是否合规？	工具 MIT 协议，可商用，但请遵守意大利个人数据保护法规（GDPR）。

10. 下一步可以做什么

自动化脚本：结合 cron 每月自动下载 PDF → 解析 → 上传到 Google Drive。
个人财务仪表盘：把 JSON 喂给 Grafana，实时展示收支趋势。
企业报销系统：批量解析员工 Postepay 交易，匹配发票金额，减少审计时间。

如果你觉得字段还可以更丰富（例如商户分类、交易国家），欢迎去 GitHub 提 Issue 或 Pull Request。

结语

在数字时代，数据被困在 PDF 里是一种浪费。Poste Italiane Documents Parser 用最朴素的方式解决了最实在的痛点：把银行流水变成可以分析、可以备份、可以对接其他系统的结构化数据。
无论你是留学生做年度预算，还是会计师做企业审计，这款开源工具都值得一试。祝你早日告别手动对账，拥抱自动化。

附录：相关链接

项目仓库：https://github.com/genbs/poste-italiane-parser
在线文档中心：https://comunicazionionline.poste.it/tbr/routes/l1/documenti

意大利邮政PDF报表批量处理秘籍：Python一键生成JSON/CSV