invoice_ocr

invoice_ocr 是一个基于 .NET 8 WinForms 开发的百度增值税发票 OCR 桌面程序。程序可以批量选择 PDF 发票，调用百度智能云 OCR 接口提取购方、销方、金额、税额、开票日期等信息，并将识别结果导出为 Excel 文件。

• 选择指定目录中的全部 PDF 文件；
• 一次选择一个或多个 PDF 发票文件；
• 自动获取并缓存百度 OCR Access Token；
• 批量、串行调用百度增值税发票识别接口；
• 显示当前进度、识别状态及错误信息；
• 支持中途停止批量识别；
• 提取购方、销方、发票号码、日期、金额和税额等常用字段；
• 将全部识别结果导出为 .xlsx 文件；
• 通过 appsettings.json 配置 API Key、Secret Key 和接口参数；
• 对重复添加的 PDF 文件自动去重；
• 单个文件识别失败时继续处理后续文件。

• .NET 8
• Windows Forms
• C#
• 百度智能云 OCR API
• ClosedXML 0.105.0

• Windows 10 或 Windows 11
• Visual Studio 2022 17.8 或更高版本
• .NET 8 SDK
• Visual Studio 工作负载：.NET 桌面开发

本项目目标框架为 net8.0-windows，不能直接在 Linux 或 macOS 上运行 WinForms 界面。

invoice_ocr/
├─ Models/
│  ├─ AppSettings.cs          # 配置文件根模型
│  ├─ BaiduOcrOptions.cs      # 百度 OCR 配置及参数校验
│  └─ InvoiceRecord.cs        # 发票识别结果模型
├─ Services/
│  ├─ BaiduOcrClient.cs       # Token 获取、PDF 上传、结果解析
│  ├─ BaiduOcrException.cs    # 百度 OCR 业务异常
│  ├─ ConfigService.cs        # appsettings.json 读取
│  └─ ExcelExporter.cs        # Excel 导出
├─ MainForm.cs                # WinForms 主界面和批量识别流程
├─ Program.cs                 # 程序入口
├─ appsettings.json           # 百度 OCR 配置
├─ invoice_ocr.csproj         # 项目文件
└─ invoice_ocr.sln            # Visual Studio 解决方案

本项目默认使用百度增值税发票识别接口：

https://aip.baidubce.com/rest/2.0/ocr/v1/vat_invoice

Access Token 获取接口：

https://aip.baidubce.com/oauth/2.0/token

用户最初提供的接口：

https://aip.baidubce.com/rest/2.0/ocr/v1/receipt

主要用于通用票据类识别，并不对应本项目所需的增值税发票结构化字段。项目因此默认配置为 vat_invoice 接口。

1. 登录百度智能云控制台。
2. 开通文字识别 OCR 服务。
3. 创建应用并启用增值税发票识别能力。
4. 获取应用的 API Key 和 Secret Key。
5. 将密钥填写到项目的 appsettings.json 中。

百度官方文档：

• 增值税发票识别：https://ai.baidu.com/ai-doc/OCR/nk3h7xy2t
• 鉴权认证机制：https://ai.baidu.com/ai-doc/REFERENCE/Ck3dwjhhu

编辑 appsettings.json：

{
  "BaiduOcr": {
    "ApiKey": "请填写百度OCR应用的API Key",
    "SecretKey": "请填写百度OCR应用的Secret Key",
    "TokenEndpoint": "https://aip.baidubce.com/oauth/2.0/token",
    "OcrEndpoint": "https://aip.baidubce.com/rest/2.0/ocr/v1/vat_invoice",
    "PdfPageNumber": 1,
    "InvoiceType": "normal",
    "SealTag": false,
    "RequestIntervalMilliseconds": 300,
    "TimeoutSeconds": 60
  }
}

InvoiceType 取值说明：

• normal：普通发票、增值税专用发票、电子发票等；
• roll：卷式发票。

API Key 和 Secret Key 属于敏感凭证。不要将包含真实密钥的 appsettings.json 提交到公开 Git 仓库。

1. 使用 Visual Studio 2022 打开 invoice_ocr.sln。
2. 等待 NuGet 自动还原 ClosedXML。
3. 修改 appsettings.json，填写百度 OCR 的 API Key 和 Secret Key。
4. 选择 Debug 或 Release 配置。
5. 按 F5 运行程序。

在项目目录中运行：

dotnet restore
dotnet build -c Release
dotnet run --project invoice_ocr.csproj

1. 启动程序。
2. 点击 选择目录，添加该目录当前层级中的全部 PDF 文件；或点击 选择PDF文件，一次选择多个 PDF。
3. 确认列表中的文件和状态。
4. 点击 开始识别。
5. 等待识别完成，结果会显示在表格中。
6. 点击 导出Excel，选择保存位置。
7. 导出完成后可选择立即打开生成的 .xlsx 文件。

“选择目录”只扫描所选目录的当前层级，不会递归扫描子目录。

程序当前展示并导出以下字段：

百度接口未返回某个字段时，对应单元格会保持为空。

导出的工作簿包含一个名为 发票识别结果 的工作表，字段包括：

• 文件名；
• 识别状态；
• 发票基本信息；
• 购方和销方信息；
• 不含税金额、税额、价税合计；
• 收款人、复核人、开票人和备注；
• 错误信息；
• PDF 源文件完整路径。

程序使用 ClosedXML 生成 Excel 文件，运行电脑不需要安装 Microsoft Excel。打开导出文件则需要系统中存在可处理 .xlsx 的应用程序。

程序将 PDF 文件读取为字节数组并转换为 Base64，然后通过 pdf_file 参数上传。

根据当前项目实现：

• 仅接受扩展名为 .pdf 的文件；
• 默认识别第 1 页，可通过 PdfPageNumber 修改；
• 请求内容 URL 编码后的估算大小不能超过 8 MB；
• 超过限制时程序会提示压缩或拆分 PDF；
• 加密、损坏或扫描质量过低的 PDF 可能无法识别；
• 多页 PDF 当前只提取配置页码对应的一页。

• 文件按照文件名排序后加入列表；
• 相同完整路径的文件不会重复添加；
• OCR 请求采用串行执行，降低超过账户 QPS 限制的概率；
• 每个请求之间按 RequestIntervalMilliseconds 等待；
• 某个文件失败不会影响后续文件；
• 点击 停止 后，当前任务会被取消，未完成文件不会继续识别；
• 再次点击 开始识别 会重新处理列表中的全部文件。

dotnet publish invoice_ocr.csproj `
  -c Release `
  -r win-x64 `
  --self-contained true `
  -p:PublishSingleFile=true

发布结果默认位于：

bin\Release\net8.0-windows\win-x64\publish

请确保 appsettings.json 与程序可执行文件位于同一目录。项目文件已设置在构建和发布时复制该配置文件。

dotnet publish invoice_ocr.csproj -c Release -r win-x64 --self-contained false

这种方式生成的文件更小，但目标电脑必须安装对应的 .NET 8 Desktop Runtime。

确认修改的是程序运行目录中的 appsettings.json，而不是其他副本。重新构建后，请检查：

bin\Debug\net8.0-windows\appsettings.json

或：

bin\Release\net8.0-windows\appsettings.json

检查：

• API Key 和 Secret Key 是否正确；
• 百度 OCR 应用是否已启用；
• 电脑是否可以访问 aip.baidubce.com；
• 公司代理、防火墙或安全软件是否拦截 HTTPS 请求；
• 系统时间是否明显不准确。

确认当前百度应用已开通增值税发票识别，并检查免费额度、付费额度和调用频率限制。具体错误码会显示在程序的“错误信息”列中。

压缩 PDF、降低扫描分辨率、拆分 PDF，或只保留需要识别的发票页面后重试。

建议：

• 使用清晰、方向正确的 PDF；
• 避免严重倾斜、反光、遮挡和低分辨率扫描件；
• 检查 PdfPageNumber 是否指向发票所在页面；
• 确认发票类型与 InvoiceType 设置相符；
• 对关键金额和税号进行人工复核。

检查：

• 目标文件是否已在 Excel 中打开；
• 保存目录是否有写入权限；
• 文件名是否合法；
• 磁盘空间是否充足。

• 不要在源码中硬编码 API Key 和 Secret Key；
• 不要把真实密钥提交到 Git；
• 生产环境可改用 Windows 凭据管理器、环境变量或企业密钥管理服务；
• 发票可能包含企业税号、地址、银行账户等敏感信息，请限制导出文件的访问权限；
• 使用共享电脑时，应及时清理临时文件和导出的 Excel 文件；
• OCR 结果仅供辅助录入，财务入账前应人工核验。

常见扩展方向：

• 递归扫描子目录；
• 支持拖放 PDF 文件；
• 支持图片格式发票；
• 增加识别失败重试；
• 根据购方、销方或月份自动分类；
• 增加发票明细行导出；
• 接入数据库并进行重复发票检查；
• 使用异步限流实现可配置并发；
• 将密钥迁移到 Windows 凭据管理器或环境变量；
• 增加日志文件和审计记录。

本项目使用 ClosedXML 创建 Excel 文件。发布或商用前，请自行确认项目代码、第三方依赖以及百度 OCR 服务条款是否符合实际使用场景。