发票认证

发票认证技能。税局扫码登录、登录企业查询、发票勾选认证、抵扣统计。适用于进项发票勾选、认证、统计等税务操作场景。

发票认证技能

使用此技能进行税局扫码登录、登录企业查询、发票勾选认证、查询认证状态、申请抵扣统计等操作。

使用场景

满足以下需求时使用：

• 扫码登录税局系统（电子税务局）。
• 查询当前登录的企业信息（企业名称、纳税人识别号）。
• 查询发票的勾选认证状态。
• 提交或取消发票勾选认证。
• 申请或撤销抵扣统计。
• 查询抵扣统计数据。
• 查询当前属期已认证的发票集合。
• 查询当前税款所属期。
• 确认签名。

触发语句示例

以下用户输入应触发此技能：

• 帮我登录税局 / 税局登录 / 扫码登录 / 登录电子税务局
• 现在登录的是哪个企业 / 查询企业信息 / 当前企业
• 查一下这张发票的认证状态 / 发票认证状态
• 提交认证 / 勾选认证 / 取消认证
• 申请统计 / 撤销统计 / 抵扣统计
• 查看已认证发票 / 当前属期发票
• 确认签名
• 税款所属期 / 当前属期 / 查询税款所属期
• 发票勾选 / 认证发票

输入参数

执行前准备以下参数：

• apiKey（必填）：通过 https://skill.quandianfapiao.com/ 申请。

扫码登录 (login-qr)

无额外参数。获取税局登录二维码并在终端展示，用户使用微信扫码（或在浏览器中打开链接）完成登录。

查询当前登录企业 (org-info)

无额外参数。返回当前 apiKey 对应的企业名称与纳税人识别号。

确认签名 (sign)

无额外参数。

查询当前税款所属期 (current-period)

无额外参数。

申请或撤销统计 (statistics)

• 提交类型（必填）：1 申请统计，2 撤销统计
• bz（必填）：N 忽略未勾选发票直接统计，Y 取消未完成的统计状态

查询抵扣统计数据 (deduct-stats)

• 税款所属期（选填，不填默认当前属期）

查询当前属期认证发票集合 (checked-invoices)

• 税款所属期（选填，不填默认当前属期，传入可查询历史认证记录）

查询发票认证状态 (check-status)

• 发票号码（必填）
• 开票日期（必填，格式 YYYY-MM-DD）
• 发票代码（选填）

提交或取消认证 (commit-deduction)

• 提交类型（必填）：1 勾选认证，2 取消勾选认证
• 发票列表（必填）：每条包含发票代码、开票日期、发票号码
• 税款所属期（选填，不填默认当前属期）

批量处理规则：

• 提交前无需先查验认证状态，可直接提交或取消认证。
• 多张发票时自动按开票日期（kprq）升序排序后提交。
• 每批最多 50 张，超出自动分批。

执行流程

前置检查（最高优先级）：检查环境变量 ZXT_API_KEY 是否已设置。

注意：当前 shell 会话可能未继承 Windows 用户级环境变量，必须按以下方式检查，不能仅依赖 $ZXT_API_KEY：

• Windows：执行 powershell -Command "[System.Environment]::GetEnvironmentVariable('ZXT_API_KEY', 'User')" 获取用户级环境变量值，同时检查 $ZXT_API_KEY。
• macOS/Linux：检查 $ZXT_API_KEY 即可。

如果以上检查结果均为空，禁止执行任何后续操作，立即向用户输出以下提示并停止：

您需要完成以下三步，即可自动配置并执行技能：

1. 注册账号 访问中兴通简税Skill平台：https://skill.quandianfapiao.com/ 完成注册。

2. 申请 apiKey 登录后进入"技能中心"，复制您的 apiKey。

3. 提供 apiKey 将复制的 apiKey 发送给我，我将为您完成配置并立即执行技能。

严格限制：前置检查未通过时，禁止执行任何其他动作，包括但不限于：

• 禁止读取文件（Excel、PDF、图片等）
• 禁止调用任何 API
• 禁止执行任何脚本或命令
• 禁止进行参数解析或预处理

只允许输出提示信息，然后停止，等待用户提供 apiKey。

用户提供 apiKey 后，写入系统环境变量并使当前会话生效：

• Windows：setx ZXT_API_KEY <apiKey> 写入用户级环境变量，然后执行 export ZXT_API_KEY=<apiKey> 使当前会话生效。
• macOS/Linux：将 export ZXT_API_KEY=<apiKey> 追加到 ~/.bashrc 或 ~/.zshrc（根据用户使用的 shell），同时执行 export ZXT_API_KEY=<apiKey> 使当前会话生效。

环境变量就绪后，继续以下步骤：

1. 校验必填参数存在且非空。任何必填参数缺失时必须立即停止，禁止跳过或使用空值继续执行。
2. 通过 python 执行脚本调用远程 API（Windows 下使用 python，macOS/Linux 使用 python3），脚本优先使用 --api-key 参数，未传则回退读取环境变量 ZXT_API_KEY。
3. 检查返回的 status 字段：
   • 非 200 且非 309 时，停止并将错误信息展示给用户。
   • status 为 309 时（税局未登录），脚本自动调用 getLoginQrUrl 获取登录二维码地址，在系统临时目录生成二维码图片并输出图片路径与链接，然后退出。你必须把该图片展示给用户：优先用自身能力展示（如 present_files 或读取图片文件），其次用系统自带能力打开（Windows start、macOS open、Linux xdg-open）。随后引导用户使用微信扫码（或在浏览器中打开链接）；用户回复确认后，重新执行刚才的命令即可（此时税局已完成登录，原命令可直接成功）。
4. 解析返回结果并以可读格式输出。
5. 向用户明确说明操作对象企业。 业务命令（current-period / sign / statistics / deduct-stats / checked-invoices / check-status / commit-deduction）在操作成功后会自动标注企业名称与税号。回复用户时必须带上该企业标识，让用户清楚知道本次操作针对哪个企业；commit-deduction 完成时脚本会输出「发票已操作至企业: XXX」，务必原样转达，不得省略。若输出中没有企业行（说明企业信息未取到），需如实说明本次未能确认操作企业。

为何只在成功后标注： getLoginOrgInfo 不反映税局会话状态（会话失效时仍可能返回 200 和企业名）。若在操作前标注，一旦随后返回 309，用户会先看到企业名、再看到登录失效，误以为操作已执行。因此企业标识一律只在成功输出中出现。

税局扫码登录流程说明

本技能采用扫码登录，流程如下：

1. 任意业务命令返回 status=309（税局未登录）时，脚本自动调用 /api/jxplus/zxtSkill/login/getLoginQrUrl 获取二维码地址。
2. 脚本在系统临时目录生成二维码图片（图片下方已绘制来源技能与扫码用途文案），并输出图片路径与链接。脚本不会自动弹窗。
3. 按以下优先级把二维码展示给用户：
   1. 优先使用你自身的能力展示图片——例如 present_files，或读取文件的工具（直接读取该图片路径即可在对话中呈现）。用户在对话窗口里就能看到二维码并扫码，无需切换窗口。
   2. 其次使用系统自带的能力打开图片——Windows：start "" "<图片路径>"；macOS：open "<图片路径>"；Linux：xdg-open "<图片路径>"。
   • 不要跳过展示、直接把路径丢给用户。 只有在以上两种方式都不可用时，才退而告知图片路径。
4. 用户使用微信扫码，或在浏览器中打开链接完成登录。
5. 用户回复"扫好了"后，重新执行原命令，税局已完成登录，命令正常返回结果。

也可主动执行 login-qr 命令单独获取二维码。

为何使用扫码登录： 扫码可确保税局密码只在本机手机端输入，不经过 AI 对话窗口、不被模型采集、也不落盘存储。这是防止密码被 AI 模型采集的防御手段。

提示： 二维码链接为微信端页面，用微信扫码可直接打开；用浏览器扫码或在浏览器中打开链接同样可以完成登录。引导用户扫码时只说这两种方式，不要引导用户使用其它客户端。

依赖说明： 二维码生成依赖 qrcode 与 pillow（pip install qrcode pillow）。图片下方的说明文案需要系统中文字体（Windows 微软雅黑、macOS PingFang、Linux Noto CJK 等，脚本按平台自动探测）；探测不到时图片只含二维码，文案仅在终端输出，不影响登录。若图片生成失败，脚本会自动降级：先在终端渲染二维码图案，仍不行则只输出二维码链接（用户可自行转为二维码后扫描）。

请求参数说明

1. 获取税局登录二维码 — POST /api/jxplus/zxtSkill/login/getLoginQrUrl

参数	类型	必填	说明
apiKey	string	是	apiKey

返回 data.qrUrl 为税局登录二维码地址。

2. 查询当前登录企业 — POST /api/jxplus/zxtSkill/dzsj/getLoginOrgInfo

参数	类型	必填	说明
apiKey	string	是	apiKey

返回 data.orgName 为企业名称，data.nsrsbh 为纳税人识别号。

重要限制： 该接口返回的是 apiKey 在平台上绑定的企业，不反映税局会话是否有效。实测税局会话失效（其它接口返回 309）时，本接口仍会返回 200 和企业名称。因此它只能用于标注操作对象，不能用于判断登录状态——登录状态一律以业务接口的 309 为准。

3. 确认签名 — POST /api/jxplus/zxtSkill/check/doSignature

参数	类型	必填	说明
apiKey	string	是	apiKey

4. 查询当前税款所属期 — POST /api/jxplus/zxtSkill/check/getCurrSkssq

参数	类型	必填	说明
apiKey	string	是	apiKey

返回 data 为税款所属期字符串，如 "2026-05"。

5. 申请或撤销统计 — POST /api/jxplus/zxtSkill/check/commitStatistics

参数	类型	必填	说明
apiKey	string	是	apiKey
commitType	string	是	1 申请统计，2 撤销统计
bz	string	是	N 忽略未勾选发票直接统计，Y 取消未完成的统计状态

6. 查询抵扣统计数据 — POST /api/jxplus/zxtSkill/check/getDeductStatistList

参数	类型	必填	说明
apiKey	string	是	apiKey
skssq	string	否	税款所属期，不填默认当前属期

7. 查询当前属期认证发票集合 — POST /api/jxplus/zxtSkill/check/getCheckedInvoiceList

参数	类型	必填	说明
apiKey	string	是	apiKey
skssq	string	否	税款所属期，不填默认当前属期

8. 查询发票认证状态 — POST /api/jxplus/zxtSkill/check/getInvoiceCheckStatus

参数	类型	必填	说明
apiKey	string	是	apiKey
invoiceNumber	string	是	发票号码
invoiceDate	string	是	开票日期（YYYY-MM-DD）
invoiceCode	string	否	发票代码

9. 提交或取消认证 — POST /api/jxplus/zxtSkill/check/commitDeduction

参数	类型	必填	说明
apiKey	string	是	apiKey
commitType	string	是	1 勾选认证，2 取消勾选认证
skssq	string	否	税款所属期，不填默认当前属期
list	array	是	发票列表，每条含 invoiceCode、kprq、invoiceNumber

返回说明

登录企业返回 (org-info)

字段	说明
orgName	企业名称
nsrsbh	纳税人识别号

认证发票返回 (checked-invoices)

字段	说明
invoiceCode	发票代码
invoiceNumber	发票号码
qdfphm	全电发票号码
kprq	开票日期
hjje	合计金额
hjse	合计税额
jshj	价税合计
fplx	发票类型
fplxName	发票类型名称
xsfNsrsbh	销售方税号
xsfMc	销售方名称

认证状态返回 (check-status)

字段	说明
invoiceCode	发票代码
invoiceNumber	发票号码
kprq	开票日期
hjje	合计金额
hjse	合计税额
gxzt	勾选状态：0 未勾选，1 已勾选
skssq	认证属期

提交认证返回 (commit-deduction)

字段	说明
successCount	成功数量
failCount	失败数量
successList	成功集合
failLIst	失败集合
skssq	当前税款所属期

异常状态码

状态码	说明
400	请求参数错误
300	参数为空或格式错误
305	无权访问该接口
307	消费失败，授权余次不足
308	超出接口调用次数
309	税局未登录，脚本自动展示扫码登录二维码
500	系统异常

命令示例

获取税局扫码登录二维码：

bash

python .claude/skills/invoice-cert/invoice_cert.py login-qr

查询当前登录企业：

bash

python .claude/skills/invoice-cert/invoice_cert.py org-info

确认签名：

bash

python .claude/skills/invoice-cert/invoice_cert.py sign

查询当前税款所属期：

bash

python .claude/skills/invoice-cert/invoice_cert.py current-period

查询发票认证状态：

bash

python .claude/skills/invoice-cert/invoice_cert.py check-status --invoice-number "26127000000211930033" --invoice-date "2026-05-12"

查询当前属期认证发票：

bash

python .claude/skills/invoice-cert/invoice_cert.py checked-invoices

查询指定属期认证发票（历史记录）：

bash

python .claude/skills/invoice-cert/invoice_cert.py checked-invoices --skssq "202604"

提交勾选认证（单张）：

bash

python .claude/skills/invoice-cert/invoice_cert.py commit-deduction --commit-type "1" --invoices "011002000311,2026-05-12,26127000000211930033"

提交勾选认证（多张，自动按开票日期排序，每批最多 50 张）：

bash

python .claude/skills/invoice-cert/invoice_cert.py commit-deduction --commit-type "1" --invoices "011002000311,2026-05-10,26127000000211930033" "011002000311,2026-05-12,26127000000211930034" "011002000311,2026-05-08,26127000000211930035"

申请统计：

bash

python .claude/skills/invoice-cert/invoice_cert.py statistics --commit-type "1" --bz "N"

查询抵扣统计：

bash

python .claude/skills/invoice-cert/invoice_cert.py deduct-stats