tencentcloud-ocr-vatinvoice

name	tencentcloud-ocr-vatinvoice
description	腾讯云通用票据识别高级版(VatInvoiceOCR)接口调用技能。当用户需要识别发票图片中增值税专用发票、增值税普通发票、增值税电子专票、增值税电子普票、电子发票（普通/增值税专用）的全字段信息时,应使用此技能。支持识别发票图片中的发票代码、发票号码、开票日期、合计金额、校验码、税率、合计税额、价税合计、购买方/销售方信息、明细条目等全部字段,同时支持PDF格式发票图片识别。

腾讯云通用票据识别高级版 (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 脚本完成通用票据识别。

请求参数

参数	类型	必填	说明
ImageBase64	str	否(二选一)	图片/PDF的Base64值，编码后不超过10M，像素需介于20-10000px，支持PNG/JPG/JPEG/PDF
ImageUrl	str	否(二选一)	图片/PDF的URL地址，都提供时只使用ImageUrl
IsPdf	bool	否	是否开启PDF识别，默认false，开启后可同时支持图片和PDF的识别
PdfPageNumber	int	否	PDF页码，仅当IsPdf=true时有效，默认1，必须>=1
UserAgent	str	否	请求来源标识(可选)，用于追踪调用来源，统一固定为Skills

输出格式

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

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

{
  "发票基本信息": {
    "发票代码": "012002100311",
    "发票号码": "48026588",
    "开票日期": "2021年09月15日",
    "发票名称": "增值税电子普通发票",
    "发票类型": "10",
    "校验码": "12345678901234567890",
    "机器编号": "661234567890"
  },
  "购买方信息": {
    "购买方名称": "XX科技有限公司",
    "购买方识别号": "91440300MA5XXXXXX"
  },
  "销售方信息": {
    "销售方名称": "YY有限公司",
    "销售方识别号": "91110108MA0XXXXXX"
  },
  "金额信息" 
     
     
     
     
  
   
     
     
     
  
   
    
       
       
       
       
       
       
       
       
       
    
  
   
     
     
  
   

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

{
  "VatInvoiceInfos": [
    {
      "Name": "发票代码",
      "Value": "012002100311",
      "Polygon": {"LeftTop": {"X": 50, "Y": 100}, ...}
    },
    {
      "Name": "发票号码",
      "Value": "48026588",
      "Polygon": {...}
    }
  ],
  "Items": [
    {
      "LineNo": "1",
      "Name": "*信息技术服务*软件开发服务",
       
       
       
       
       
       
       
       
    
  
   
   
   

响应数据结构说明

TextVatInvoice 结构（KV形式）：

字段	类型	说明
Name	str	字段名称，支持识别的完整字段列表见下方
Value	str	字段对应的值
Polygon	Polygon	字段在原图中的四点坐标（可能为null）

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

VatInvoiceItem 结构（明细条目）：

字段	类型	说明
LineNo	str	行号
Name	str	项目名称
Spec	str	规格型号
Unit	str	单位
Quantity	str	数量
UnitPrice	str	单价
AmountWithoutTax	str	不含税金额
TaxRate	str	税率
TaxAmount	str	税额
TaxClassifyCode	str	税收分类编码
VehicleType	str	运输工具类型
VehicleBrand	str	运输工具牌号
DeparturePlace	str	起始地
ArrivalPlace	str	到达地
TransportItemsName	str	运输货物名称
ConstructionPlace	str	建筑服务发生地
ConstructionName	str	建筑项目名称

错误码说明

错误码	含义
FailedOperation.DownLoadError	文件下载失败
FailedOperation.EmptyImageError	图片内容为空
FailedOperation.ImageBlur	图片模糊
FailedOperation.ImageDecodeFailed	图片解码失败
FailedOperation.ImageNoText	图片中未检测到文本
FailedOperation.ImageSizeTooLarge	图片尺寸过大，请确保编码后不超过10M，像素介于20-10000px
FailedOperation.OcrFailed	OCR识别失败
FailedOperation.UnKnowError	未知错误
FailedOperation.UnOpenError	服务未开通，请先在腾讯云控制台开通增值税发票识别服务
InvalidParameter.EngineImageDecodeFailed	引擎图片解码失败
InvalidParameterValue.InvalidParameterValueLimit	参数值错误
LimitExceeded.TooLargeFileError	文件内容太大
ResourceUnavailable.InArrears	账号已欠费
ResourceUnavailable.ResourcePackageRunOut	账号资源包耗尽
ResourcesSoldOut.ChargeStatusException	计费状态异常

重要业务逻辑

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（全电发票）→ 走全电发票识别引擎
   • 其他类型 → 走传统增值税发票识别引擎
8. 全电发票会进行字段映射转换，将ElectricInvoiceItem统一转换为TextVatInvoice+VatInvoiceItem格式输出
9. 建议图片存储于腾讯云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```