shield_lock
JinDaGe
← Back to skills
extension
Category: OtherAPI key required

发票识别-发票查验-发票OCR（翔云开放平台）

翔云发票识别与查验 Skill。当用户请求以下操作时触发： - 发票识别、发票 OCR、识别发票 - 发票查验、发票验真、发票核验、核查发票真伪 - 扫描发票、读取发票信息、提取发票数据 - 增值税发票识别、电子发票识别、数电票识别 - 发票导出、发票台账、发票入账表、发票勾选抵扣 - 旅客运输抵扣表、货物明细表 - 批量发票处理、发票文件夹识别 - netocr 发票、翔云发票

personAuthor: user_6b190ef3hubcommunity
downloadDownload package

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

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

能力概览

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

凭据配置

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

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

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

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

脚本使用

识别单张发票（仅识别）

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

识别 + 查验（默认行为）

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

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

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

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

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 使用）

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

模版名称及说明：

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

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

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

发票类型映射

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

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

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

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

仅识别（不支持查验）

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

5 种 Excel 模版及适用票种

| 模版 | 参数值 | 适用票种代码 | |:---|:---:|:---| | 增值税发票勾选抵扣表 | deduction | 01,03,08,09,14,91,93,61,62,72 | | 国内旅客运输服务抵扣表 | transport | 10,14,20,22,26,27,61,62,83,92,72 | | 增值税发票货物明细表 | goods | 01,03,04,08,09,10,11,14,15,21,63,64,83,91,92,72 | | 增值税发票台账表 | ledger | 01,03,04,08,09,10,11,14,15,21,61,62,63,64,83,91,92,72 | | 发票入账表 | booking | 01,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 是否可用，若认证失败会提前报错并提示。

执行逻辑

用户输入（图片/目录）
  │
  ├─ 检查 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，不上传至任何其他平台