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

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

支持的查验类型

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

前置条件：凭证配置

统一使用完整访问凭证 QXY_API_KEY=<appkey>.<secret>。按“进程环境 → 当前 Skill 的 .env → qixiangyun-skill/.env”读取；只在内部 MCP 调用边界拆分为 client_appkey/client_secret。遇到旧版 QXY_CLIENT_APPKEY/QXY_CLIENT_SECRET 时停止，不得拼接、猜测或继续调用。

本地单用户 Agent 首次使用或当前 Skill 本地配置错误时：

1. 运行 python3 scripts/cli.py check-config --allow-agent-credential-configuration。只有本地单用户 Agent 才能使用此 opt-in；托管、多租户或共享环境仅允许平台 Secret 注入。
2. 若返回 configuration_required，只向用户展示 user_interaction.message。不得向用户展示变量名、格式、文件路径、内部命令、参数数组或原始错误。
3. 用户发送开放平台复制出的完整访问凭证后，不回显、不记录，使用响应中的固定 agent_configuration.argv、shell=False 和单字段敏感 JSON stdin 启动配置器。
4. 配置成功后立即运行 python3 scripts/cli.py check-config 复检，并在同一任务中自动重跑原业务命令；不得要求用户再次回复“重试”。

产品授权终态

当接口返回 code=505069 且消息精确属于以下四种授权终态时，立即停止当前操作，不重试、不重新登录、不索取凭证，也不把原始响应展示给用户：

• “当前产品已超测试使用期，请联系服务提供商！”或“当前产品已超测试使用次数，请联系服务提供商！”：只返回“您当前使用的是免费版，该产品的测试使用期已结束。为了不影响您的业务正常开展，建议您前往企享云开放平台选购付费版或进行续费，感谢您的支持！”
• “当前产品已超生产使用次数，请联系服务提供商”或“当前产品已超税号数量限制，请联系服务提供商”：只返回“抱歉，您的产品生产授权已到期，当前服务已暂停。为确保您的业务持续稳定运行，请尽快前往企享云开放平台完成续费或购买，感谢您的配合！”

其他错误码、未知 505069 消息及相似文案保持原有处理，不得扩大匹配。

强制规则

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 工具调用。

客户端只在 MCP 传输边界携带服务端既有的内部身份验证字段；Agent 与用户侧始终使用完整 APIKEY 契约。