腾讯 OCR API 调研

调研日期：2026-07-28。仅查阅腾讯云官方文档、当前锁定 SDK 和本地代码；未创建密钥、未调用付费 API、未上传票据。

官方资料

通用票据识别（高级版）：https://cloud.tencent.com/document/api/866/90802
增值税发票识别：https://cloud.tencent.com/document/api/866/36210
OCR 控制台访问管理：https://cloud.tencent.com/document/product/866/102912
免费额度：https://cloud.tencent.com/document/product/866/35945
计费概述：https://cloud.tencent.com/document/product/866/17619
混贴票据计费说明：https://cloud.tencent.com/document/product/866/48522
错误码计费说明：https://cloud.tencent.com/document/product/866/45470
新手常见问题：https://cloud.tencent.com/document/product/866/43818
欠费说明：https://cloud.tencent.com/document/product/866/30576

结论

1. 当前接口不适合作为两类差旅票据的统一入口

当前代码调用 VatInvoiceOCR。官方说明明确覆盖增值税专票、普票、电子专票、电子普票和数电普通/专用发票，适合住宿电子普通发票；但官方用于统一识别火车票、电子发票（铁路电子客票）和增值税发票的是 RecognizeGeneralInvoice。

RecognizeGeneralInvoice 明确返回 ElectronicTrainTicketFull，同时覆盖 VatElectronicCommonInvoice、VatElectronicInvoiceFull 等住宿发票常见子类型。因此本轮应在现有腾讯 provider 内改用该接口，而不是直接给当前 VatInvoiceOCR 配密钥。

2. 请求合同

API 版本仍为 2018-11-19，请求域名为 ocr.tencentcloudapi.com。
当前锁定的 Node SDK 已包含 RecognizeGeneralInvoice；无需为了该方法先升级依赖。
PDF 通过 Base64 传输，不需要公开文件 URL。
Base64 编码后不得超过 10M；为避免 OA 的 10MiB 原文件上限在编码后超限，正式发票应增加不高于 7MiB 的 OCR 输入门禁。
本系统一份 PDF 对应一张发票，只识别第一页：EnablePdf=true、PdfPageNumber=1、EnableMultiplePage=false。
不请求切图、字段坐标、二维码或印章返回，避免无用数据和额外敏感内容。
默认接口频率为 5 次/秒；当前 job 串行处理，远低于该上限。

3. 返回结构和业务字段

住宿增值税/电子普通发票：从对应 VAT 子类型归一化发票代码（存在时）、号码、日期、不含税金额、税额、价税合计、销售方和购买方。
电子发票（铁路电子客票）：从 ElectronicTrainTicketFull 归一化发票号码、开票日期、价税合计、税额和购买方；该票种可以没有发票代码和销售方，不能继续套用现有 VAT 五字段必填规则。
归一化结果需要保留安全的 documentSubtype，用它选择必填字段和脱敏处理；不得把乘车人姓名、证件号、完整票面字段或腾讯原始响应写入 OcrResult.result_json。
电子票据没有发票代码时，不再把发票号码复制到代码字段。文件 SHA-256 查重继续生效；号码级查重需要按已知无代码子类型做显式规则，不能依赖伪造代码绕过现有复合键。

4. CAM 最小权限

腾讯官方确认 OCR 支持接口级自定义授权，接口级授权的 resource 必须为 *。运行身份只需：

{
  "version": "2.0",
  "statement": [
    {
      "effect": "allow",
      "action": ["ocr:RecognizeGeneralInvoice"],
      "resource": ["*"]
    }
  ]
}

运行子用户不需要 QcloudOCRFullAccess，也不需要开通/关闭服务或控制台管理权限。OCR 服务开通、计费设置和告警由管理员在控制台完成。

5. 免费接口选择、计费和错误

官方免费额度表明确列出：通用票据识别（高级版） 使用同名专用资源包，免费额度为每月 1,000 次，当月有效、每月发放。它不是与其他票据接口共用的模糊额度。
增值税发票识别 也有每月 1,000 次专用免费额度，但只能解决住宿常见 VAT/电子普通发票，不能统一覆盖电子发票（铁路电子客票）。
独立的 火车票识别 位于官方“仅老客户续费相关接口”区域，且增加第二套 API、权限、归一化和错误处理，不适合作为当前新接入方案。
因此最省钱且最简单的方案是只接 RecognizeGeneralInvoice：一个接口同时覆盖住宿和铁路电子客票，并消耗通用票据识别（高级版）的每月 1,000 次专用免费额度。按当前 8 人规模通常足够，但免费政策不是永久合同，上线前仍必须在实际账号控制台确认免费包已到账。
高级版免费额度耗尽后，如已购买预付费包则继续扣包；如开通后付费则可能继续计费。官方当前后付费起价为 0.15 元/次。
为确保零费用，生产应使用中国大陆地域，在 OCR 控制台设置页确认后付费关闭；免费额度耗尽后允许 OCR 不可用并进入可解释失败，不为保持识别可用而自动付费。境外地域按国际站后付费计费，不能抵扣国内账号资源包，因此不在本轮方案内。
官方 FAQ 说明，2021 年 12 月 14 日前开通 OCR 的客户在资源包耗尽后可能自动开通后付费；无论账号何时开通，都以实际控制台开关状态为准，不能只凭开通日期推断不会收费。
通用票据识别高级版按实际识别出的发票张数计费；增值税发票进入大票计费项，铁路电子客票/全电发票进入小票计费项。
每份 PDF 必须只含一张票据，使一次正常识别对应一次额度扣减；混贴或多票文件可能按实际识别张数扣减，应用继续拒绝多票结果。
免费/付费资源包耗尽且未开后付费时会不可用；应用需把它分类为额度/计费门禁失败，而不是票据质量失败。腾讯云侧同时设置费用或余额告警作为兜底。
高级版接口官方错误码已核对：ResourceUnavailable.ResourcePackageRunOut 表示资源包耗尽，ResourceUnavailable.InArrears 表示欠费，ResourcesSoldOut.ChargeStatusException 表示计费状态异常，FailedOperation.UnOpenError 表示服务未开通，LimitExceeded.TooLargeFileError 表示文件过大。这些状态对同一输入重试没有收益，应用应一次终止并给出配置/额度类提示。
大部分失败不计费，但官方明确有少量失败错误也可能计费。应用必须保留有限重试和可解释终态，不能无限重试。
需要区别处理未开通、欠费/资源包耗尽、文件过大、图片解码/模糊和一般 OCR 失败；不得把配置或额度错误伪装成票据质量问题。

当前实现差距

server/src/services/ocr/tencent.js 调用 VatInvoiceOCR，没有铁路电子客票结构解析。
server/src/services/ocr/index.js 对所有 vat 强制要求代码、号码、日期、金额、销售方；铁路电子客票和部分数电票会被误判失败。
现有归一化会在代码/号码缺失时互相回填，掩盖无代码电子票据并污染复合查重语义。
现有归一化把腾讯完整响应放进 raw，随后持久化到 OcrResult.result_json；改用高级版后可能保存乘车人证件信息。
OA 发票上传使用通用 10MiB 上限，可能产生“上传成功、腾讯因 Base64 超限失败”的死路。
旧版腾讯 OcrResult.result_json 可能仍带 raw；新 adapter 不再生成还不够，命中历史缓存时也必须先按安全白名单压缩，避免旧格式绕过新隐私边界。

8.0 KiB 原始文件 Blame 文件历史