xiangyun-invoice-ocr — 翔云发票识别与查验 Skill#

本 Skill 调用翔云平台 API，实现发票图片/PDF 识别 → 查验 全流程。 导出功能仅在用户 明确提出 时才执行。

---

能力概览#

功能说明发票识别支持全票种（增值税专票/普票/数电票/电子票等），JPG/PNG/PDF/OFD发票查验识别后自动提取查验入参，联网核验真伪，返回完整票面信息Excel 导出5 种标准模版按发票类型自动匹配（仅用户明确要求时）批量处理支持单张和文件夹批量模式，批量前验证 key/secret

---

凭据配置#

首次使用必须配置凭据。凭据存储于本 Skill 目录下的 config.json。

获取方式：登录 netocr.com → 个人中心 → 查看 key / secret

配置文件格式（ config.json）：

json

{
  "key": "你的 ocrKey",
  "secret": "你的 ocrSecret"
}

---

脚本使用#

识别单张发票（仅识别）#

bash

python scripts/invoice.py --image <发票路径>

识别 + 查验（默认行为）#

bash

python scripts/invoice.py --image <发票路径> --verify

批量识别 + 查验（默认行为，批量前自动验证 key/secret）#

bash

python scripts/invoice.py --dir <目录路径> --verify

交互选择导出Excel模版（仅用户明确要求时才加 --export，并鼠标点选）#

bash

python scripts/invoice.py --image <发票路径> --verify --export --select-template
python scripts/invoice.py --dir <目录路径> --verify --export --select-template

脚本检测到 --select-template 时输出结构化标记并退出，由 Agent 调用 ask_followup_question 弹出多选窗口，用户点选后 Agent 将结果通过 --template 重新调用脚本。

指定导出模版（仅配合 --export 使用）#

bash

# 单选
python scripts/invoice.py --image <发票路径> --verify --export --template ledger
# 多选（逗号分隔）
python scripts/invoice.py --dir <目录> --verify --export --template goods,booking

模版名称及说明：

编号参数值说明1deduction增值税发票勾选抵扣表（抵扣进项税额）2transport国内旅客运输服务抵扣表（航空/铁路/客车/旅客运输服务/通行费）3goods增值税发票货物明细表（商品明细记录）4ledger增值税发票台账表（最全字段，覆盖广）5booking发票入账表（财务记账用）

严格票种过滤：每个模板只导出其适用票种的数据，票种不匹配时自动跳过并提示 [SKIP] {模版} 不适用于票种 {类型}，跳过。 空文件生成：批量模式下，即使用户选择的模板没有任何匹配发票，也会生成空表头文件（仅标题+列头，无数据行）。

Agent 使用说明：当用户需要导出但未指定 --template 时，Agent 应主动调用 ask_followup_question（multiSelect=true）展示 5 个模板选项供用户点选，再将结果通过 --template 参数传给脚本。

---

发票类型映射#

本 Skill 支持 46 种 发票类型的识别，区分 可查验 与 仅识别 两大类。

可查验（识别后可联网核验真伪）#

查验入参 totalAmount 按类型分两类取值：

票种名称票种代码totalAmount 取值增值税专用发票01totalAmount（不含税）机动车销售统一发票03totalAmount（不含税）增值税普通发票04totalAmount（不含税）增值税专用发票(电子)08totalAmount（不含税）电子发票(增值税专用发票)09amountTax（价税合计）增值税电子普通发票10totalAmount（不含税）增值税普通发票(卷票)11totalAmount（不含税）通行费增值税电子普通发票14totalAmount（不含税）二手车销售统一发票15totalAmount（不含税）电子发票(航空运输电子客票行程单)61amountTax（价税合计）电子发票(铁路电子客票)62amountTax（价税合计）电子发票(机动车销售统一发票)63totalAmount（不含税）电子发票(二手车销售统一发票)64totalAmount（不含税）电子发票（普通发票）通行费72amountTax（价税合计）电子发票(普通发票)83amountTax（价税合计）数电纸质发票(增值税专用发票)91totalAmount（不含税）数电纸票发票(普通发票)92totalAmount（不含税）数电纸质发票(机动车销售统一发票)93totalAmount（不含税）数电纸票发票(二手车销售统一发票)94totalAmount（不含税）

仅识别（不支持查验）#

票种名称票种代码火车票20区块链发票21船票22定额发票23机打发票24出租车发票25客运汽车26航空运输电子客票行程单27过路费28打车行程单31货物清单33财政电子票据34海关缴款书35通用电子发票36完税证明37医疗票据38退票费报销凭证39非税收入一般缴款书(电子)40车辆通行费通用(电子)发票41银行回单42

---

5 种 Excel 模版及适用票种#

模版参数值适用票种代码增值税发票勾选抵扣表deduction01,03,08,09,14,91,93,61,62,72国内旅客运输服务抵扣表transport10,14,20,22,26,27,61,62,83,92,72增值税发票货物明细表goods01,03,04,08,09,10,11,14,15,21,63,64,83,91,92,72增值税发票台账表ledger01,03,04,08,09,10,11,14,15,21,61,62,63,64,83,91,92,72发票入账表booking01,03,04,08,09,10,15,61,62,63,64,83,91,92,14,72

---

Agent 执行规范#

默认行为（识别 + 查验）#

当用户说"识别"、"OCR"、"扫描发票"等意图时：

• 单张： --image <路径> --verify
• 目录： --dir <目录> --verify
• 不加 --export

仅识别（不查验）#

当用户明确说"仅识别"、"不查验"时：

• 去掉 --verify 参数

导出 Excel#

当用户明确提到"导出"、"台账"、"抵扣表"、"明细表"等时：

• 在识别查验基础上加上 --export
• 配合 --template 指定模板（可多选，逗号分隔）

批量前验证#

批量处理（ --dir）时会自动先用空请求验证 key/secret 是否可用，若认证失败会提前报错并提示。

---

执行逻辑#

text

用户输入（图片/目录）
  │
  ├─ 检查 config.json → 若无 key/secret，要求用户配置后退出
  │
  ├─ 发票识别（recogInvoiveBase64.do，typeId=20090）
  │    └─ 解析返回：invoiceCode, invoiceNumber, billingDate,
  │                  totalAmount, checkCode, salesTaxNo 等
  │
  ├─ [--verify] 发票查验（verInvoice.do，typeId=3007）
  │    └─ 用识别结果自动填充查验入参
  │    └─ 返回完整票面 + 真伪状态
  │
  └─ [--export] 导出 Excel（仅用户明确要求）
       └─ 按 invoiceType 匹配模版
       └─ 写入对应字段，保存到 <原文件名>_<模版名>.xlsx

---

API 参考#

• 发票识别： https://netocr.com/api/v2/recogInvoiveBase64.do（typeId=20090）
• 发票查验： https://netocr.com/verapi/v2/verInvoice.do（typeId=3007）

---

认证错误检测#

识别和查验接口返回时，会自动检测 key/secret 错误：

• 检测关键词：key、secret、密钥、认证、auth、unauthorized、401 等
• 检测到后打印友好提示，引导用户检查凭据或前往 netocr.com 重新获取

---

⚠️ 安全说明#

• 用户图片及 API 凭据通过 HTTPS 发送至翔云（netocr.com）进行处理
• 凭据仅存储于本地 config.json，不上传至任何其他平台