发票查验
两种入口,最终都到同一次查验:
- A. 用户给发票文件(PDF / PNG / JPG 路径)→ 视觉识别要素 → 用户确认 → 查验
- B. 用户给文字要素(号码/日期/金额/票种)→ 补齐规则化后直接查验
1. 认证与连接器定位(先做,别急着说"没有工具")
唯一依赖连接器 wpe-general-connector(中文名「腾讯数电发票」),通过它的 call_internal_api 工具调用。
| 项 | 值 |
|---|---|
| 连接器 | wpe-general-connector(中文名「腾讯数电发票」) |
| 税号传递 | 连接器请求头 X-Subject-Id(不是接口参数) |
| 令牌 | Authorization: Bearer <token>,由连接器管理 |
定位与授权流程:
- 会话中找不到该连接器工具 → 用名称
wpe-general-connector(或「腾讯数电发票」)在连接器列表查找并加载 MCP。 - 加载后首次调用不带 token(探活)。返回 HTTP 401 → 未授权,停下提示用户完成 MCP 授权,通过后再继续。
- 税号未接入(
access_status ≠ 00)→403 / JSON-RPC -32007,表现是 WorkBuddy 把整个连接器下线(工具从列表消失,易误判成"MCP 挂了")。
⚠️ 禁止用脚本、curl 或其它连接器直连服务端点——查验只能通过该连接器实现。
2. 工具说明
| 工具 | 用途 | 何时用 |
|---|---|---|
call_internal_api |
调用内部 HTTP 接口 | 本技能唯一入口,api="invoice_check" |
list_internal_apis |
列出可调用接口 | 排障 |
health_check |
服务/DB 就绪 + 税号接入状态 | 排障 |
2.1 call_internal_api(查验唯一方式)
call_internal_api(api="invoice_check", params={...})
请求参数(严格大驼峰,后端 @JsonProperty 强制大写):
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
InvoiceType |
string | ✅ | 票种代码,不同代码走不同渠道,不可臆造(枚举见 references/invoice-types.md) |
InvoiceNo |
string | ✅ | 发票号码(数电票 20 位) |
InvoiceDate |
string | ✅ | 开票日期,必须 yyyyMMdd 紧凑格式(20260916) |
Amount |
number | ✅ | 金额,单位 分(整数);口径随票种变化(见 §2.2) |
InvoiceCode |
string | 视票种 | 数电票(31/32/61/83)可空;其余必填(纸质票 10-12 位代码) |
CheckCode |
string | 视票种 | 见 §2.3 |
调用示例(数电普票 9.00 元):
{"api":"invoice_check","params":{
"InvoiceType":"32","InvoiceNo":"26507200000011978330",
"InvoiceDate":"20260916","Amount":900}}
响应信封(腾讯云风格,没有 code 字段):
{"Response":{"RequestId":"xxx","Error":null,"Data":{...票面...}}}
| 判定 | 含义 |
|---|---|
Error == null 且 Data 有值 |
查验通过 |
HTTP 200 + Error.Code="InvoiceCheckError" |
业务查验失败,Error.Message 是中文 |
HTTP 400 + Error.Code="InvalidParameter" |
参数校验失败 |
2.2 Amount 口径(最容易错,务必先确认)
单位一律分:Amount = int(round(元 × 100))。口径随票种变化:
| 票种 | 取票面哪一栏 | 示例 |
|---|---|---|
| 01 / 09 / 23 | 不含税金额(票面「金额」栏) | 8.26 → 826 |
| 04 / 10 / 24 | 不含税金额(可空,置 0) |
8.26 → 826;拿不到 → 0 |
| 11 / 14 | 不含税金额 | 8.26 → 826 |
| 31 / 32 / 61 / 83 | 价税合计 | 9.00 → 900 |
| 03 / 15 | 车价合计 | 120000.00 → 12000000 |
- 用户口头说的"开票金额 X 元"通常是价税合计;用在不含税口径的票种时必须问到「金额」栏或税率,不要拿价税合计直接填。
- 换算辅助脚本:
node scripts/calc-amount.mjs <票种> <元>(如node scripts/calc-amount.mjs 31 9.00→ 900)。 - 单位或口径错,税局只回「发票信息不一致」,看不出是金额问题还是票不存在,极易误判成假票。
2.3 CheckCode / InvoiceCode 规则
| 情形 | CheckCode 取值 |
|---|---|
| 01/02/03/08/15/23/31/32/61/83 | 可省略,传 "" |
| 24 | 全电号码(数电号码)后六位 |
| 04/09/10/11/14 | 票面右下角「校验码」后六位 |
InvoiceCode:31/32/61/83 数电票可空;其余票种必填。
3. 执行流程
步骤 1:获取要素
入口 A(文件):用视觉能力直接读 PDF/图片提取要素;PDF 读不清先用
node scripts/prepare-image.mjs <文件> [输出目录] 转 PNG。
⚠️ Python 解释器:
scripts/decode-qr.py/pdf_to_png.py依赖 PyMuPDF + OpenCV, 系统 python3 通常没装。请使用当前环境中已装好pymupdf+opencv-python-headless的 Python 解释器:python3 scripts/decode-qr.py <文件>报No module named 'pymupdf'时先安装依赖(pip install pymupdf opencv-python-headless)再重试, 不要改用其它方式绕过二维码校验。 Node 脚本用当前环境可用的 Node 运行:node scripts/xxx.mjs
待提取字段与位置:发票类型(标题区)/ 发票代码、发票号码、开票日期(右上角,输出 yyyyMMdd)/
金额(按 §2.2 票种口径取对应栏)/ 校验码(右下角,取后六位,部分票种无)。
识别后:
- 二维码交叉校验(强制):
python3 scripts/decode-qr.py <发票文件>。 数电票 20 位号码视觉识别极易多读/漏读 0,票面二维码是权威数据源 (格式01,<票种>,<代码>,<号码>,<金额>,<日期>,<校验码>,...)。号码/票种/日期/金额以二维码为准。 - 按
templates/ocr-fields.md输出识别结果表(每字段标「清晰/存疑」)。 - 存疑字段先让用户确认再查验——错一位号码或选错口径就白烧当日配额。
入口 B(文字):直接进步骤 2。
步骤 2:票种反查(票种未确认时)
必须把全部支持票种列出让用户选,不要只问"专票还是普票"。先读 references/invoice-types.md。
常见票面标题 → 枚举:增值税专用发票 01、增值税普通发票 04、增值税电子普通发票 10、
电子发票(普通发票)/数电普票 32、电子发票(增值税专用发票)/数电专票 31 等。
步骤 3:调用查验
{"api":"invoice_check","params":{
"InvoiceType":"<票种>","InvoiceNo":"<号码>","InvoiceDate":"<yyyyMMdd>","Amount":<分>}}
步骤 4:判读(中文 Message 原样转达,不要自行解读)
| 返回 | 含义 | 处置 |
|---|---|---|
Error==null 且 Data 有值 |
查验通过 | 输出票面,与用户信息逐项比对 |
| 所查发票不存在 | 税局无此记录 | 核对号码/日期;≠ 假票 |
| 发票信息不一致 | 要素组合未命中(金额单位/票种/日期任一不对,或票未同步) | 先查 Amount 单位与口径(最高频),再查票种 |
| 查询发票不规范 | 多为入参问题(尤其日期格式) | 改 yyyyMMdd |
| 超过该张票当天查验次数 | 当日 5 次配额用尽 | 次日再查,勿重试 |
| 二维码参数不合法 | 票种走二维码渠道缺校验码/代码 | 补全或换票种 |
| 处理业务异常 / 查验异常 | 下游渠道异常 | 记 RequestId,稍后重试 |
4. 超时与重试
- 仅瞬时故障重试(超时/网络异常/响应无
Data):重试最多 2 次(合计 3 次),退避 2s → 4s。 - 业务错误一律不重试(不存在/不一致/不规范/超限/二维码不合法)——重试只会白烧配额。
- 重试耗尽仍无票面 → 记录每次
RequestId,如实反馈"连续 3 次未取到票面",不要臆造票面、不要下真伪结论。
5. 错误场景与边界
| 场景 | 现象 | 处置 |
|---|---|---|
| 日期格式错 | 全表「查询发票不规范」 | 改 yyyyMMdd(2026-09-16 → 20260916) |
| 金额单位错(元) | 「发票信息不一致」 | 改成「分」 |
| 小写驼峰字段 | 「参数不能为空」 | 用大驼峰 InvoiceType/InvoiceCode/... |
| 配额耗尽 | 「超过该张票当天查验次数」 | 次日再查;换票种不获得新配额(配额按票号跨票种共享) |
| 二维码不合法 | 号码多读/漏读 0 | 解码票面二维码拿权威号码 |
配额铁律:同一张票每天限查 5 次,未命中也计数(成功票面 CheckCount=当日累计次数)。
票种不确定就问用户,一次只查一个票种;不要批量扫票种、不要把"换几个代码试试"当排查手段。
排查技巧(号码 +1 对照实验):保持其余参数不变,号码末位 +1 查对照票——若返回「所查发票不存在」说明链路正常;
⚠️ 但票种 32 对未命中统一报「发票信息不一致」,此时对照实验失效,改做渠道自检(用已知有记录的票同票种再查一次)。
6. 输出
按 templates/report-template.md:识别要素表(入口 A)+ 票面要素表 + 与用户信息逐项比对(一致/不一致)+
未通过时给税局原文 Message 与 RequestId + 下一步建议。查验通过必补「F. 销方企业画像」。
7. 销方企业画像(查验通过后必出)
用本地脚本把票面销方翻译成结构化描述:
node scripts/seller-profile.mjs \
--name "销方名称" --taxno <税号> \
--tax-class-code <税收分类编码> --tax-rate <税率> --total <价税合计元> \
--net <不含税元> --tax <税额元> --date <yyyyMMdd> --invoice-type <票种> \
--goods "<商品简称>"
输出 8 板块:主体标识(含 GB 32100-2015 校验位核验)/ 名称结构 / 登记画像 / 行业画像 / 纳税人身份(13/9/6%→一般纳税人高置信;1%→小规模减按;3%/5%→小规模或简易计税不可区分)/ 开票特征 / 提示 / 数据边界。
硬规则:18 位代码按 GB 32100-2015 计算校验位,不通过直接提示「税号可能有误」; 不编造工商要素(注册资本/法人/成立日期/股东/经营状态/参保人数票面没有,需外部工商查询并标注来源); 3%/5% 不区分小规模与简易计税;票面简称与编码归类两套口径并列展示。
参考
- 接口规范、参数、错误码与重试语义:
references/api_protocol.md - 票种枚举全表(唯一数据源):
references/invoice-types.md - 实测记录(含踩坑):
references/examples.md - 识别字段表与确认话术:
templates/ocr-fields.md;工作流清单:templates/workflow.md - 画像素材:
references/region-codes.md、references/tax-class-industry.md、references/industry-keywords.md