tencentcloud-ocr-vatinvoice（腾讯云 OCR vatinvoice）

腾讯云通用票据识别高级版 (VatInvoiceOCR)

用途

调用腾讯云OCR通用票据识别高级版接口，支持增值税专用发票、增值税普通发票、增值税电子专票、增值税电子普票、电子发票（普通发票）、电子发票（增值税专用发票）全字段的内容检测和识别。

核心能力：

• 发票头信息识别：发票代码、发票号码、打印发票代码、打印发票号码、开票日期、机器编号、校验码、密码区等
• 买卖方信息识别：购买方/销售方名称、识别号（税号）、地址/电话、开户行及账号
• 金额信息识别：合计金额、合计税额、价税合计(大写)、小写金额、税率
• 明细条目识别：货物/服务名称、规格型号、单位、数量、单价、不含税金额、税率、税额、税收分类编码等
• 人员信息识别：开票人、收款人、复核
• 其他信息识别：备注、联次名称、发票名称、发票类型、车牌号、通行费标志等
• PDF发票支持：支持PDF格式发票识别（需开启IsPdf参数）
• 全电发票支持：自动分类识别全电发票，并统一输出格式

官方文档：https://cloud.tencent.com/document/api/866/36210

使用时机

当用户提出以下需求时触发此技能：

• 需要从发票图片中提取全部字段信息
• 需要从PDF格式发票中识别内容
• 需要提取发票中的明细条目（货物/服务列表）
• 需要识别增值税专用/普通发票、电子发票
• 涉及发票OCR识别的任何场景
• 需要批量处理发票并结构化提取信息

环境要求

• Python 3.6+
• 依赖：tencentcloud-sdk-python（通过 pip install tencentcloud-sdk-python 安装）
• 环境变量：

- TENCENTCLOUD_SECRET_ID：腾讯云API密钥ID - TENCENTCLOUD_SECRET_KEY：腾讯云API密钥Key

使用方式

运行 scripts/main.py 脚本完成通用票据识别。

请求参数

输出格式

识别成功后返回 JSON 格式结果：

格式化输出模式（默认）：

{
  "发票基本信息": {
    "发票代码": "012002100311",
    "发票号码": "48026588",
    "开票日期": "2021年09月15日",
    "发票名称": "增值税电子普通发票",
    "发票类型": "10",
    "校验码": "12345678901234567890",
    "机器编号": "661234567890"
  },
  "购买方信息": {
    "购买方名称": "XX科技有限公司",
    "购买方识别号": "91440300MA5XXXXXX"
  },
  "销售方信息": {
    "销售方名称": "YY有限公司",
    "销售方识别号": "91110108MA0XXXXXX"
  },
  "金额信息": {
    "合计金额": "¥1000.00",
    "合计税额": "¥60.00",
    "价税合计(大写)": "壹仟零陆拾圆整",
    "小写金额": "¥1060.00"
  },
  "人员信息": {
    "开票人": "张三",
    "收款人": "李四",
    "复核": "王五"
  },
  "明细条目": [
    {
      "行号": "1",
      "名称": "*信息技术服务*软件开发服务",
      "规格型号": "",
      "单位": "次",
      "数量": "1",
      "单价": "1000.00",
      "不含税金额": "1000.00",
      "税率": "6%",
      "税额": "60.00"
    }
  ],
  "其他信息": {
    "备注": "",
    "旋转角度": 0.0
  },
  "RequestId": "xxx"
}

原始输出模式（--raw）：

{
  "VatInvoiceInfos": [
    {
      "Name": "发票代码",
      "Value": "012002100311",
      "Polygon": {"LeftTop": {"X": 50, "Y": 100}, ...}
    },
    {
      "Name": "发票号码",
      "Value": "48026588",
      "Polygon": {...}
    }
  ],
  "Items": [
    {
      "LineNo": "1",
      "Name": "*信息技术服务*软件开发服务",
      "Spec": "",
      "Unit": "次",
      "Quantity": "1",
      "UnitPrice": "1000.00",
      "AmountWithoutTax": "1000.00",
      "TaxRate": "6%",
      "TaxAmount": "60.00",
      "TaxClassifyCode": "3040201"
    }
  ],
  "PdfPageSize": 0,
  "Angle": 0.0,
  "RequestId": "xxx"
}

响应数据结构说明

TextVatInvoice 结构（KV形式）：

Name 字段可识别的完整列表：发票代码、发票号码、打印发票代码、打印发票号码、开票日期、购买方识别号、小写金额、价税合计(大写)、销售方识别号、校验码、购买方名称、销售方名称、税额、复核、联次名称、备注、联次、密码区、开票人、收款人、货物或应税劳务/服务名称、省、市、服务类型、通行费标志、是否代开、是否收购、合计金额、是否有公司印章、发票消费类型、车船税、机器编号、成品油标志、税率、合计税额、购买方地址/电话、销售方地址/电话、单价、金额、销售方开户行及账号、购买方开户行及账号、规格型号、发票名称、单位、数量、校验码备选、校验码后六位备选、发票号码备选、车牌号、类型、通行日期起、通行日期止、发票类型

VatInvoiceItem 结构（明细条目）：

错误码说明

重要业务逻辑

1. ImageBase64和ImageUrl必须提供其一，都提供时只使用ImageUrl
2. 图片/PDF编码后不超过10M，像素需介于20-10000px
3. 支持格式：PNG、JPG、JPEG、PDF（不支持GIF）
4. IsPdf默认为false，识别PDF格式发票需显式设置为true
5. PdfPageNumber仅当IsPdf=true时有效，默认值为1，必须>=1
6. 默认接口请求频率限制：10次/秒
7. 复杂的内部分流逻辑：接口会先调用InvoiceMixedClassify对票据分类

- 分类Type==16（全电发票）→ 走全电发票识别引擎 - 其他类型 → 走传统增值税发票识别引擎

1. 全电发票会进行字段映射转换，将ElectricInvoiceItem统一转换为TextVatInvoice+VatInvoiceItem格式输出
2. 建议图片存储于腾讯云COS以获得更高的下载速度和稳定性

调用示例

# 通过URL识别发票
python scripts/main.py --image-url "https://example.com/invoice.jpg"

# 通过文件路径(自动Base64编码)识别
python scripts/main.py --image-base64 ./invoice.jpg

# 识别PDF格式发票
python scripts/main.py --image-base64 ./invoice.pdf --is-pdf

# 识别PDF发票的指定页码
python scripts/main.py --image-base64 ./invoice.pdf --is-pdf --pdf-page-number 2

# 输出原始JSON响应
python scripts/main.py --image-url "https://example.com/invoice.jpg" --raw

# 指定地域
python scripts/main.py --image-url "https://example.com/invoice.jpg" --region ap-beijing```