税务发票数据开放平台

主题

发票数据说明 ​

ALLSTANDARD
接口POST /api/channel/data/invoice/allPOST /api/channel/data/invoice/standard
schemaVersioninvoice.v1invoice-standard.v2
结构税局源表各列原样保留的动态对象，分页返回13 个模块的分析结构
成功业务码0200

两者规则不可混用

原始发票记录是动态对象，必须允许新增字段。STANDARD 是独立加工结构， 字段必填/可空规则以专用字典为准，不能套用原始发票规则。

发票 ALL ​

记录角色 ​

同一张发票的多个商品行可能对应多条记录。每条记录带 __recordRole 说明它是什么：

__recordRole含义
INVOICE_HEADER「发票基础信息」中的整票记录
INVOICE_LINE「信息汇总表」中的真实商品或服务明细
INVOICE_LINE_SUMMARY「详见销货清单」等整票汇总占位，不应与真实商品明细重复累计
WORKBOOK_TOTAL原工作簿合计/总计行，不代表一张发票
SPECIALTY_DETAIL不动产、旅客、货运、通行费、铁路客票等专项伴随明细
SOURCE_RECORD其他历史或未知来源记录

不要把所有记录直接相加

发票 ALL 保持原数组、原分页和全部税局源字段，不删除合计行， 也不把整票与商品明细自动相加。需要发票张数或金额分析时， 必须按记录角色选对统计层级；不想自行处理的客户应使用发票 STANDARD。

来源元数据 ​

结构化入库后的记录增量返回四个双下划线前缀字段：

字段含义
__sourceDatasetName原始工作表名称
__sourceArtifactNameWorker 原始制品文件名
__sourceRecordOrdinal一基表内行序（从 1 开始）
__recordRole记录角色

数据库中的税局原始 payload 不写入或覆盖这些字段； LEGACY 分页、CURSOR 和 PACKAGE 在交付时使用同一规则动态附加。 旧任务尚未结构化入库、走历史制品兼容路径时可能没有这些可选字段。

兼容键 ​

新版 Worker 的 XLSX 原样保留税局中文列；交付层同时对能够确定一一对应的列 增量附加旧接口兼容键，且绝不覆盖制品已经提供的同名键。

中文源列兼容键中文源列兼容键
数电发票号码qdfphm数量spsl
货物或应税劳务名称spmc单价bwSpdj
规格型号ggxh金额je
单位jldw发票来源invoiceOrigin
发票票种invoiceTypeName发票风险等级riskLevel

两个易混淆的键

dw 始终表示吨位，不能代替 jldw（计量单位）。 hjje 也不能代替商品行原始 je。

商品规格、单位、数量和单价只在源工作表具有相应列的记录中出现， 通常是 INVOICE_LINE。基础表或专项表没有来源时不制造空值或猜测值。

派生仅限确定性规则：

  • 原始来源「增值税发票管理系统 / 电子发票服务平台」→ invoiceSource = 0 / 1
  • 制品文件名明确含「进项 / 销项」→ 补 sign
  • 发票状态明确包含「作废 / 红冲」→ 补 zfbz / hc

历史 JSON 在生成时已经缺失的规格、单位、数量、单价等业务值不会反推或伪造， 必须从原始任务表、原始 XLSX 或重新采集恢复。

纯增量变更

已有字段的名称、类型、值、数组顺序、分页总数和记录顺序均不改变。 按 additionalProperties: true 约定实现的现有客户无需修改解析逻辑。

行数与张数摘要 ​

「多少行记录」和「多少张发票」是两个数。发票 ALL 分页、CURSOR 和 PACKAGE 状态/清单都会返回统一的摘要，把两者分开说明：

字段含义
total / recordCount / totalRecords全部原始行数
invoiceCount按可靠票号去重后的真实发票张数；无法证明时为 null
invoiceCountStatusVERIFIED 或 UNVERIFIED
invoiceCountMethod张数判定来源：信息汇总表、发票基础信息、多 Sheet 身份联合或明确空结果
recordRoleCounts六类角色在完整数据集中的总行数，各分页保持一致

invoiceCount 为 null 时不要用行数替代

invoiceCount 为 null 表示平台无法证明真实张数。 此时不得用 total（原始行数）冒充发票张数。

该摘要在发票数据快照生成时一次算好、存下来，翻页时不会反复扫描全部发票。

分页 ​

见获取数据 · 发票分页。 数据量大时改用 CURSOR 或 PACKAGE。

发票 STANDARD ​

响应外层 ​

结构与税务 STANDARD 不同

13 个模块直接挂在响应 data 的顶层，没有额外的 data 包装， 也没有 moduleStatus。

json
{
  "schemaVersion": "invoice-standard.v2",
  "generatedAt": "2026-08-12T10:41:07+00:00",
  "taxpayerId": "91420100XXXXXXXXXX",
  "companyName": "示例企业有限公司",
  "selectedModules": ["UPSTREAM_ANNUAL", "…共 13 项"],
  "sourceRecordCount": 2841,
  "effectiveRecordCount": 2790,
  "duplicateRecordCount": 0,
  "invoiceCount": 1204,
  "SJZL": {},
  "JYGL": {},
  "XSFX": {}
}

13 个模块 ​

selectedModules 列出的是英文键名，实际数据节点使用拼音码，一一对应：

selectedModules 中的键数据节点模块
UPSTREAM_ANNUALSXYNDXX上下游年度信息
TRANSACTION_OVERVIEWJYGL交易概览
SALES_ANALYSISXSFX销售分析
PURCHASE_ANALYSISCGFX采购分析
EXPENSE_ANALYSISFYFX费用分析
MONTHLY_TOP_DOWNSTREAM_DEALERSYDQSXYJXSXX月度前十下游经销商信息
MONTHLY_TOP_DOWNSTREAM_PRODUCTSYDQSXYCPXX月度前十下游产品信息
MONTHLY_INVOICE_SUMMARYYDFPHZ月度发票汇总
DOWNSTREAM_INFOXYXX下游信息
PRODUCT_INFOSPXX商品信息
TOP_SUPPLIERSQSGYSLB前十供应商列表
MONTHLY_INPUT_INVOICE_SUMMARYAYHZJXPHZ按月汇总进项票汇总
MONTHLY_OUTPUT_INVOICE_STATISTICSXXKPAYFLTJ销项开票按月分类统计

SJZL · 加工质量 ​

固定返回，披露本次加工的所有边界：可靠票数、无法判断进销方向的记录、 被抑制的重复金额、缺年度 / 交易对方名称 / 税号的发票、同名多税号冲突、 被忽略的整票清单占位数等。

先看 SJZL 再用结论

SJZL 里的每个计数都对应一类「平台选择不猜测」的情况。 先看这些计数、再决定多信任聚合金额，比直接拿数就用更稳妥。

三条通用规则 ​

带符号净额

多数模块的金额是带符号净额。负数有效发票会让占比小于 0 或超过 100， 不能当作强制 0–100 的集中度指标。分母为 0 时返回 null， 而不是用 0 表示「无法计算」。

同名多税号按名称合并

同一客户/供应商名称出现多个税号写法时，按名称合并金额（同名视为同一家）， 并在 SJZL 中通过 *NameTaxIdVariantCount 系列字段披露差异数量。

整票清单占位不重复累计

存在真实商品明细时，「详见销货清单」等整票占位会被排除， 并在 SJZL.ignoredProductSummaryRecordCount 中披露。

各模块要点 ​

JYGL · 交易概览

销售、采购和税额合计只统计方向、开票月份及票面金额可靠的有效票； 冲红、作废票单独进入 CHZFHZ。

  • 顶层 FPZS 是全部状态可确认发票数；年度/月度数组中的票数是有效票数。 有效票数加上冲红、作废票数，正好等于 FPZS，不多不少。
  • 历史字段 MLL 实际是按发票算的进销差额率，不是会计毛利率 —— 全部进项采购净额不等于营业成本。销项净额 ≤ 0 时返回 null。
  • CHZFHZ.ZB 的全部状态价税净额分母为 0 时返回 null。
XSFX · 销售分析

起止日期只来自有效销项发票，不受进项、冲红或作废日期影响。

  • 月度变化率只比较连续上月非零净额；首月、缺月或上月为 0 时为 null。
  • 前十客户按名称和税号的带符号净额排名。
  • 客户有多个地区时显示「多地区」；地区分布按每张发票地址逐笔汇总。
  • 全部商品金额加起来必须与销售净额一致，不允许出现对不上的差额。
CGFX · 采购分析

与销售分析用同一套严格规则，但只读取有效进项。

  • 采购起止日期不受销项或异常票影响；月度环比只比较连续上月非零净额。
  • 前十供应商按名称和税号的带符号净额排名；地区按每张进项发票地址逐笔汇总。
  • 全部采购商品净额加起来必须与 JYGL.CGJEHJ 一致。
  • 没有有效进项时日期为空字符串、各分析数组为空。
FYFX · 费用分析

不是全部会计费用。只统计可从有效进项商品/服务名称可靠识别的 水、电、物业、燃气、取暖、运输六类净额。

分类要求费用或服务语义 —— 不会因为设备、元器件或实物商品名称中 出现「运输、物流、电力」就归入费用。

FYHZ、YDFY 和 FYHJ 三层金额必须相互对得上。无可识别费用时日期为空、合计为 0、数组为空。

SXYNDXX · 上下游年度信息

按「自然年度 + 方向 + 交易对方名称 + 税号」汇总有效发票净额。 基础表存在时票面金额和状态以基础表为准，明细及专项表不重复累计。

JYJEZB 是带符号的年度净额贡献率。

YDQSXYJXSXX / YDQSXYCPXX · 月度前十
  • YDQSXYJXSXX 按「月份 + 下游客户名称」汇总有效销项含税净额取前十。
  • YDQSXYCPXX 按「月份 + 商品名称」汇总有效销项不含税净额取前十。

三项合计字段只代表前十客户/商品，并在同月每行重复返回。 月度净额分母为 0 时占比及前十占比合计为 null。

JYCSHJ 是前十商品–发票关联次数之和：同一发票含多个商品会重复计次， 也可能因商品未进前十而小于月票数。它不是去重发票总数。

YDFPHZ · 月度发票汇总

每个至少有一张有效进项或销项的月份输出一条；冲红、作废专属月份不进入。

  • 客户数和供应商数均按名称去重，同名多税号合并计数并通过 SJZL 分方向披露。
  • 销项、进项金额均为不含税净额 —— 进项金额不是含税金额，也不是会计成本。
  • 月度金额、税额和票数加总后，与 JYGL 的年度及顶层合计一致。
XYXX / SPXX · 全量清单

这两个模块返回全部客户 / 商品，不是前十列表。

  • XYXX 按「自然年度 + 下游客户名称」；
  • SPXX 按「自然年度 + 商品名称」，存在真实明细时排除整票商品清单占位。

每年全部客户金额、全部商品金额加起来，分别与 JYGL.NDTJ.XSJE 一致。 年度净额为 0 时占比为 null。

QSGYSLB · 前十供应商

按供应商名称合并全部可靠期间的有效进项并取前十。 同名多税号不会显示成重复名称，差异通过 SJZL.lifetimeSupplierNameTaxIdVariantCount 披露。

历史字段名有歧义：XSJE 在本表实际表示进项不含税净额，不是销项销售额。

金额或票数分母为 0 时对应占比为 null。

AYHZJXPHZ · 按月进项汇总

每个存在有效、冲红或作废进项的月份输出一条。

  • 有效金额使用带符号价税净额，冲红作废金额使用价税绝对额。
  • JXJE / JXZS 固定等于有效票价税净额 / 票数。
  • 历史字段 YSXSSRHJ 实际为有效进项不含税净额，不是销售收入。
  • 冲红作废占比分母为 0 时返回 null；无任何进项状态的月份不生成记录。
XXKPAYFLTJ · 销项按月分类统计

每个存在有效、冲红或作废销项的月份输出一条。

  • 有效票保留带符号不含税、税额和价税净额；冲红作废使用价税绝对额。
  • HSKPJEHJ 固定等于有效价税净额。
  • 冲红作废占比、整数金额占比、整数票数占比的各自分母为 0 时返回 null， 不能用 0 表示无法计算。

完整字段字典 ​

本页说明的是统计规则与数据边界。逐字段的类型、必填性与取值范围以交付包内的 发票 ALL / STANDARD 字段附件（JSON / CSV）为准， 请求/响应 Schema 以接口参考为准。

适配平台 1.5.3 · 接入指南、接口参考、字段字典与税局状态统一入口。

税务发票数据开放平台