企享云票据查验和发票验真 Skill

通过发票四要素进行验真，返回全票面数据信息及当日最新发票状态。与国家税务总局全国增值税查验平台保持一致。

支持的查验类型

• 数电票查验（电子发票普通/专票、铁路客票、航空客票、机动车销售发票、二手车统一发票、通行费发票）
• 增值税发票四要素查验（增值税专用/普通发票、机动车销售统一发票等）
• 全电纸质发票查验
• 财政票据查验
• 批量查验（每次最多50张）

前置条件：凭证配置

本 skill 依赖企享云开放平台凭证：

• client_appkey
• client_secret

API 密钥申请：https://open.qixiangyun.com

凭证读取优先级：

1. Skill 根目录的 .env
2. Skills 公共父目录的 .env（/Users/xueds/Python/skills/qixiangyun-skill/.env）
3. 系统环境变量 QXY_CLIENT_APPKEY / QXY_CLIENT_SECRET

首次使用时，如果凭证不存在：

1. 询问用户的 client_appkey 和 client_secret
2. 如果用户没有凭证，提示：

appKey和appSecret请注册企享云开放平台申请 https://open.qixiangyun.com

1. 在 skill 根目录或公共父目录创建 .env：

```env

QXY_CLIENT_APPKEY=用户提供的appkey

QXY_CLIENT_SECRET=用户提供的secret

```

1. 后续调用由脚本自动读取，无需再次询问

强制规则

1. 代理模型在执行查验前，可先调用 validate-invoice-info 在本地验证发票信息格式是否正确。
2. 查验结果中 code=2000 表示查验成功，code!=2000 表示失败。
3. 批量查验时，每次最多支持50张发票。
4. 代理模型不得自行编造发票四要素信息。
5. 本 skill 不得把 je、jym、jshj 统一视为硬必填，需按票种走条件必填规则。

可用命令

1. validate-invoice-info - 验证发票信息格式

在正式查验前进行预检查，验证发票信息的格式是否正确。

python3 scripts/cli.py validate-invoice-info \
  --invoice-type-code '发票代码' \
  --invoice-number '发票号码' \
  --billing-date '开票日期' \
  --amount '金额，可选' \
  --check-code '校验码后6位，可选'

2. verify-tax-control - 税控发票查验

支持增值税专用/普通发票、机动车销售统一发票等类型。cyList 支持多张。

python3 scripts/cli.py verify-tax-control \
  --cy-list '[{"fpdm":"发票代码","fphm":"发票号码","kprq":"开票日期","je":"不含税金额","jym":"校验码后6位"}]'

3. verify-digital - 数电票查验

数电票查验（全电发票），cyList 支持多张。

python3 scripts/cli.py verify-digital \
  --cy-list '[{"fphm":"发票号码","kprq":"开票日期","jshj":"价税合计"}]'

4. verify-digital-paper - 数电纸质发票查验

数电纸质发票查验（全电纸质），cyList 支持多张。

python3 scripts/cli.py verify-digital-paper \
  --cy-list '[{"fpdm":"发票代码","fphm":"发票号码","kprq":"开票日期","je":"不含税金额","jym":"校验码后6位"}]'

5. verify-invoice - 单张税控发票查验

单张税控发票查验，内部会转为 verify_tax_control_invoice 的 cyList 调用。

python3 scripts/cli.py verify-invoice \
  --invoice-type-code '发票代码' \
  --invoice-number '发票号码' \
  --billing-date '开票日期' \
  --amount '金额，可选' \
  --check-code '校验码后6位，可选'

6. batch-verify - 批量查验

批量查验税控发票，提高查验效率，每次最多50张，内部会转为 verify_tax_control_invoice 的 cyList 调用。

python3 scripts/cli.py batch-verify \
  --cy-list '[{"fpdm":"发票代码","fphm":"发票号码","kprq":"开票日期","je":"不含税金额","jym":"校验码后6位"}]'

cyList 参数说明

条件必填说明

• fpdm、fphm、kprq 为基础必填字段。
• 税控发票查验 与 数电纸质发票查验 中，je 和 jym 不是同时硬必填，而是按票种二选一或条件必填。
• 增值税专用发票、机动车销售统一发票、二手车统一销售发票、部分数电纸质专票场景，通常需要 je。
• 增值税普通发票、电子普通发票、卷票、通行费发票、部分数电纸质普票场景，通常需要 jym。
• 数电票查验 走的是 jshj 规则，核心入参为 fphm + kprq + jshj。
• 单张 verify-invoice 命令至少应提供 --amount 或 --check-code 之一。
• Apifox 文档中的 required 数组会把 je、jym 一并列出，但字段说明本身写的是“按票种条件必填”，本 skill 以字段说明为准，不做统一硬拦截。

MCP 调用说明

本 skill 通过 MCP HTTP Streamable 协议调用企享云发票查验服务，端点地址：

https://mcp.qixiangyun.com/mcp/invoice_verification-http

使用的 MCP 工具：

• verify_tax_control_invoice - 税控发票查验
• verify_digital_invoice - 数电票查验
• verify_digital_paper_invoice - 数电纸质发票查验

verify-invoice 和 batch-verify 是本 skill 提供的兼容命令，实际调用 verify_tax_control_invoice。validate-invoice-info 是本地参数格式预校验，不调用 MCP 工具。服务端未注册的 verify_invoice、batch_verify_invoices、validate_invoice_info 不应再作为 MCP 工具调用。

每次调用需携带 client_appkey 和 client_secret 参数进行身份验证。