湖北航信服务发票错配校验
下载地址
https://www.zhengdianxue.com/wp-content/uploads/skills/org-wl7ywliy--invoice-validation.zip将提示词发送给你的 AI 安装该 skills
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-wl7ywliy/invoice-validation。基于税收分类编码库,对生产生活服务类发票进行逐行税收分类编码错配校验,解析XML发票明细行,精准识别编码错配并生成校验报告。
阅读全文 (展开查看完整说明)
概述
生产生活服务发票错配校验(Hbhtxx Invoice Validation)
功能概述
基于税收分类编码库,对生产生活服务类发票进行逐行税收分类编码错配校验,自动解析XML发票明细行,精准识别编码错配并生成校验报告。
使用场景
- 接收生产生活服务类发票时,验证开票方选择的税收分类编码是否正确
- 发票合规性审核,识别编码错配风险
- 批量发票校验,快速排查多张发票的编码问题
- 对接财务系统,实现发票入库前的自动校验
核心规则与约束
- 仅支持 XML 格式发票:生产生活服务发票错配校验只校验 XML 格式发票(.xml)
- 编码补齐规则:比较前统一补齐至 19 位(右侧补 0),确保比较准确性
- 生产生活服务过滤:通过 ItemName 中"商品简称"是否含"生产生活服务"字样判断,非生产生活服务发票直接跳过,避免误报
- 向量语义匹配:编码库精确匹配不到时,服务端自动执行语义匹配兜底,返回
confidence/match_method/remark标识判定来源 - 单用户 5 QPS,超出返回 HTTP 429
- 30 秒超时
核心参数
接口规范
请求方式
POST
请求地址
https://skillhub.hbhtxx.com/v1/tools/call
API Key 凭证获取方法(推荐)
API Key 是静态凭证,无需刷新,适合服务端集成。API Key 格式为 sk- 开头 + 32 位十六进制字符,示例:sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
- 访问 湖北航信开发者门户 https://skillhub.hbhtxx.com ** → **凭证管理 页面
- 使用微信扫码登录(首次登录自动注册)
- 在 API Key 标签页点击 "生成 API Key" 按钮
- 输入 Key 名称(便于识别用途,如 "生产环境"、"测试环境")
- 系统将生成 API Key,请立即复制保存,关闭后无法再次查看明文
API Key 有效期:在本版本中长期有效,如有变化会在开发者门户通知
API Key 配置方法
方式一:环境变量(推荐)
export YOUR_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"方式二:代码中直接配置
API_KEY = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"JWT Token 获取方法
- 访问 湖北航信开发者门户 https://skillhub.hbhtxx.com ** → **凭证管理 页面
- 使用微信扫码登录(首次登录自动注册)
- 在 JWT Token 标签页点击 "生成 JWT Token" 按钮
- 系统将生成 Access Token 和 Refresh Token(长期有效),请妥善保管
认证方式
以湖北航信开发者门户 https://skillhub.hbhtxx.com 展现的认证方式为准:
方式一:API Key(推荐)在请求 Header 中携带 API Key:
X-API-Key: YOUR_API_KEY方式二:JWT Token在请求 Header 中携带 JWT Token:
Authorization: Bearer YOUR_JWT_TOKEN请求参数说明
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 是 | 固定值 invoice-validation |
| arguments | object | 是 | 技能参数 |
| arguments.invoices | array | 是 | 发票列表,每项含 filename 和 xml_content |
invoices 数组元素:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| filename | string | 是 | 发票文件名 |
| xml_content | string | 是 | XML 发票内容的 base64 编码 |
三种使用场景
| 场景 | 传入方式 | 返回粒度 | 说明 |
|---|---|---|---|
| 单张 XML 发票 | invoices 数组含 1 项 | 逐商品行返回错配风险提示 | 校验整张发票所有商品行,每行标注 match/mismatch/skip |
| 多张 XML 发票 | invoices 数组含 N 项(N≥2) | 逐票汇总 + 逐商品行明细 | 每张发票独立返回 summary 和 items |
| XML 发票 ZIP 包 | AI Agent 先解压 ZIP,提取各 XML 文件后按多张发票传参 | 按多张发票返回 | Skill 不处理 ZIP 解压,由 AI Agent 负责 |
统一传参:三种场景均为
{"invoices": [{ "filename": "...", "xml_content": "..." }]},invoices数组长度为 1 则自动走单票模式,长度≥2 则走多票汇总模式。
请求报文示例
单张发票校验:
{
"name": "invoice-validation",
"arguments": {
"invoices": [
{
"filename": "生产生活服务发票001.xml",
"xml_content": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz..."
}
]
}
}多张发票批量校验:
{
"name": "invoice-validation",
"arguments": {
"invoices": [
{
"filename": "发票001.xml",
"xml_content": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNv..."
},
{
"filename": "发票002.xml",
"xml_content": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNv..."
}
]
}
}响应报文示例
单张发票校验成功:
{
"success": true,
"data": {
"invoice_code": "1234567890",
"invoice_number": "87654321",
"invoice_date": "2026-07-01",
"seller_name": "某信息技术有限公司",
"buyer_name": "某企业",
"total_items": 3,
"mismatch_count": 1,
"items": [
{
"item_name": "*信息技术服务*软件开发服务",
"item_short": "信息技术服务",
"goods_name": "软件开发服务",
"tax_code_in_xml": "1090601010000000000",
"expected_code": "1090601010000000000",
"expected_name": "软件开发服务",
"result": "match",
"message": "编码正确",
"confidence": "高",
"match_method": "精确匹配",
"remark": "精确命中编码库"
},
{
"item_name": "*生产生活服务*餐饮服务",
"item_short": "生产生活服务",
"goods_name": "餐饮服务",
"tax_code_in_xml": "1090601010000000000",
"expected_code": "3070401000000000000",
"expected_name": "餐饮服务",
"result": "mismatch",
"message": "商品行'餐饮服务'应使用的编码是3070401000000000000-餐饮服务,但开票方选择了1090601010000000000-软件开发服务,请收票方注意甄别",
"confidence": "高",
"match_method": "精确匹配",
"remark": "精确命中编码库,但编码不匹配"
},
{
"item_name": "*信息技术服务*技术咨询费",
"item_short": "信息技术服务",
"goods_name": "技术咨询费",
"tax_code_in_xml": "1090601990000000000",
"expected_code": "1090601990000000000",
"expected_name": "其他信息技术服务",
"result": "match",
"message": "编码正确",
"confidence": "高",
"match_method": "精确匹配",
"remark": "精确命中编码库"
}
]
}
}失败响应:
{
"success": false,
"error": "请提供XML发票数据"
}使用示例
示例 1:单张发票校验
使用 API Key(推荐):
curl -X POST https://skillhub.hbhtxx.com/v1/tools/call
-H "Content-Type: application/json"
-H "X-API-Key: YOUR_API_KEY"
-d '{
"name": "invoice-validation",
"arguments": {
"invoices": [{"filename": "invoice.xml", "xml_content": "PD94bWw..."}]
}
}'使用 JWT Token:
curl -X POST https://skillhub.hbhtxx.com/v1/tools/call -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_JWT_TOKEN" -d '{
"name": "invoice-validation",
"arguments": {
"invoices": [{"filename": "invoice.xml", "xml_content": "PD94bWw..."}]
}
}'Python(API Key):
import requests, base64
with open("invoice.xml", "rb") as f:
xml_b64 = base64.b64encode(f.read()).decode()
resp = requests.post(
"https://skillhub.hbhtxx.com/v1/tools/call",
headers={"X-API-Key": "YOUR_API_KEY"},
json={
"name": "invoice-validation",
"arguments": {
"invoices": [{"filename": "invoice.xml", "xml_content": xml_b64}]
}
}
)
result = resp.json()
for item in result["data"]["items"]:
if item["result"] == "mismatch":
print(f"错配: {item['message']}")Python(JWT Token):
import requests, base64
with open("invoice.xml", "rb") as f:
xml_b64 = base64.b64encode(f.read()).decode()
resp = requests.post(
"https://skillhub.hbhtxx.com/v1/tools/call",
headers={"Authorization": "Bearer YOUR_JWT_TOKEN"},
json={
"name": "invoice-validation",
"arguments": {
"invoices": [{"filename": "invoice.xml", "xml_content": xml_b64}]
}
}
)
result = resp.json()
for item in result["data"]["items"]:
if item["result"] == "mismatch":
print(f"错配: {item['message']}")示例 2:批量校验多张发票
使用 API Key(推荐):
import requests, base64, os
invoices = []
for f in ["invoice1.xml", "invoice2.xml", "invoice3.xml"]:
with open(f, "rb") as fh:
invoices.append({
"filename": f,
"xml_content": base64.b64encode(fh.read()).decode()
})
resp = requests.post(
"https://skillhub.hbhtxx.com/v1/tools/call",
headers={"X-API-Key": "YOUR_API_KEY"},
json={"name": "invoice-validation", "arguments": {"invoices": invoices}}
)
for inv in resp.json()["data"]:
print(f"{inv['filename']}: 错配 {inv.get('mismatch_count', 0)} 项")使用 JWT Token:
import requests, base64, os
invoices = []
for f in ["invoice1.xml", "invoice2.xml", "invoice3.xml"]:
with open(f, "rb") as fh:
invoices.append({
"filename": f,
"xml_content": base64.b64encode(fh.read()).decode()
})
resp = requests.post(
"https://skillhub.hbhtxx.com/v1/tools/call",
headers={"Authorization": "Bearer YOUR_JWT_TOKEN"},
json={"name": "invoice-validation", "arguments": {"invoices": invoices}}
)
for inv in resp.json()["data"]:
print(f"{inv['filename']}: 错配 {inv.get('mismatch_count', 0)} 项")约束项
| 约束项 | 说明 |
|---|---|
| 支持格式 | 仅 XML 格式发票 |
| 并发限制 | 单用户 5 QPS,超出返回 HTTP 429 |
| 超时时间 | 30 秒 |
| 编码库来源 | 税务局发布的税收分类编码表 |
| 校验范围 | 仅校验商品简称含"生产生活服务"的发票明细行 |
返回字段说明
顶层字段:
| 字段 | 类型 | 说明 |
|---|---|---|
| success | boolean | true 成功,false 失败 |
| data | object / array | 单张发票返回 object,多张发票返回 array |
| error | string | 失败时返回错误描述 |
data 字段(单张发票校验结果):
| 字段 | 类型 | 说明 |
|---|---|---|
| invoice_code | string | 发票代码 |
| invoice_number | string | 发票号码 |
| invoice_date | string | 开票日期 |
| seller_name | string | 销方名称 |
| buyer_name | string | 购方名称 |
| total_items | integer | 商品行总数 |
| mismatch_count | integer | 错配商品行数 |
| items | array | 逐行校验结果 |
items 逐行校验结果:
| 字段 | 类型 | 说明 |
|---|---|---|
| item_name | string | 原始 ItemName(如 *生产生活服务*餐饮服务) |
| item_short | string | 商品简称 |
| goods_name | string | 商品/服务名称 |
| tax_code_in_xml | string | XML 中开票方选择的编码 |
| expected_code | string | 标准编码库匹配的正确编码 |
| expected_name | string | 标准编码对应的分类名称 |
| result | string | match 正确 / mismatch 错配 / uncertain 存疑 / skip 跳过 |
| message | string | 风险提示信息 |
| confidence | string | (match/mismatch/uncertain 时)判定置信度:高 / 中 / 低 |
| match_method | string | (match/mismatch/uncertain 时)判定方式:精确匹配 / 规则归一 / 向量匹配 / 人工判断 |
| remark | string | (match/mismatch/uncertain 时)说明文字 |
| candidates | array | (向量匹配时)候选编码列表,每项含 code/name/score |
常见错误码:
| 错误信息 | 原因 | 解决方法 |
|---|---|---|
请提供XML发票数据 | invoices 数组为空 | 传入有效的 XML 发票数据 |
XML内容为空 | xml_content 为空 | 确保 base64 编码正确 |
XML解析失败 | 发票 XML 格式不正确 | 检查 XML 文件完整性 |
报告输出规范(Report)
校验完成后,智能体应输出 《生产生活服务发票 · 税收分类编码错配校验报告》,交付报告风格:统计卡片 + 明细表格 + 关键发现 + 建议。报告支持 Markdown / HTML 两种形态,HTML 版建议以单文件网页交付(内联 CSS,浅色主题)。
报告结构
① 标题区
生产生活服务发票 · 税收分类编码错配校验报告
副标题:校验技能 / 校验时间 / 数据来源(批次说明)
② 统计卡片(横向排列)
校验发票总数 | 编码正确(match) | 编码错配(mismatch) | 需人工核实(uncertain) | 非生产生活服务(skip)
—— 卡片样式:白底圆角、大号数字 + 灰色标签;match 绿色、mismatch 红色、uncertain 橙色、skip 灰色
③ 明细表格(逐票一行)
发票号码 | 开票日期 | 销方 | 购方 | 价税合计 | 商品行(ItemName) | 结论(状态标签)
④ 关键发现
—— 以要点列表说明:错配情况、uncertain 原因、同销方/同类商品的一致性差异等
⑤ 建议
—— 按 收票侧 / 开票侧 / 编码库侧 分类给出可执行建议
⑥ 页脚
校验接口、技能版本、原始结果文件引用状态标签规范
| 状态 | 标签文案 | 颜色 |
|---|---|---|
| match | 编码正确 | 绿色 #27ae60 |
| mismatch | 编码错配 | 红色 #e74c3c |
| uncertain | 需人工核实 | 橙色 #f39c12 |
| skip | 非生产生活服务 | 灰色 #95a5a6 |
报告示例(HTML 骨架)
<div class="cards">
<div class="card total"><div class="num">9</div><div class="lbl">校验发票总数</div></div>
<div class="card match"><div class="num">0</div><div class="lbl">编码正确(match)</div></div>
<div class="card mismatch"><div class="num">0</div><div class="lbl">编码错配(mismatch)</div></div>
<div class="card uncertain"><div class="num">4</div><div class="lbl">需人工核实(uncertain)</div></div>
<div class="card skip"><div class="num">5</div><div class="lbl">非生产生活服务(skip)</div></div>
</div>
<!-- 明细表格:发票号码/开票日期/销方/购方/价税合计/商品行/结论 -->
<!-- 关键发现:要点列表 -->
<!-- 建议:收票侧 / 开票侧 / 编码库侧 -->报告中的 uncertain 项须在"关键发现"中说明原因(如"编码库未收录该商品名称,服务端已通过向量匹配判定,置信度见各发票明细行"),
match_method为向量匹配或规则归一的项应标注判定方式、置信度及候选编码。
版本变更说明
| 版本 | 日期 | 变更内容 |
|---|---|---|
| v1.0.2 | 2026-09-04 | 新增 API Key 凭证获取与使用方法;更新认证方式支持双模鉴权(API Key + JWT Token);更新使用示例增加 API Key 调用方式 |
| v1.0.1 | 2026-08-31 | 服务端内置向量匹配:uncertain 发票明细行继续进行向量匹配校验,一次调用返回最终结果;响应新增 confidence/match_method/remark/candidates 字段 |
| v1.0.0 | 2026-07-13 | 初始版本:基于 编码库进行生产生活服务发票错配校验;支持单张/多张/批量校验;逐行正向/反向双重比对 |
版权声明
本技能为湖北航天信息技术有限公司(简称"湖北航信")旗下财税 AI 产品。
版权所有 © 2026 湖北航天信息技术有限公司。保留所有权利。
**欢迎访问湖北航信财税AI skills市场 https://skillhub.hbhtxx.com **
官网:https://www.hbhtxx.com
官微:湖北航天信息