主题
发票数据说明
发票 ALL 使用 invoice.flat-fields.v4 公共字段，按来源保留整票、商品明细、专项明细和合计行。普通分页、游标和分片包使用同一套记录字段，实际环境见字段契约。
| ALL | STANDARD | |
|---|---|---|
| 接口 | POST /api/channel/data/invoice/all | POST /api/channel/data/invoice/standard |
| 版本标识 | 字段 invoice.flat-fields.v4；游标与分片交付外壳 invoice.v1 | 业务字典 invoice-standard-business.v1 |
| 结构 | 统一公共英文字段，逐行返回 records | 13 个模块的分析结构 |
| 成功业务码 | 0 | 200 |
STANDARD 的业务版本用于字典和发布标识，成功响应的 data 不含 schemaVersion。ALL 的记录字段版本和游标／分片交付外壳版本分别读取，不能混用。
两者规则不可混用
原始发票记录按来源保留字段；未知列进入 extensions，客户需接受新增扩展项。STANDARD 是独立加工结构， 字段必填/可空规则以专用字典为准，不能套用原始发票规则。
发票 ALL
记录角色
同一张发票的多个商品行可能对应多条记录。使用逐行 __recordRole 说明记录角色：
__recordRole | 含义 |
|---|---|
INVOICE_HEADER | 「发票基础信息」中的整票记录 |
INVOICE_LINE | 「信息汇总表」中的真实商品或服务明细 |
INVOICE_LINE_SUMMARY | 「详见销货清单」等整票汇总占位，不应与真实商品明细重复累计 |
WORKBOOK_TOTAL | 原工作簿合计/总计行，不代表一张发票 |
SPECIALTY_DETAIL | 不动产、旅客、货运、通行费、铁路客票等专项伴随明细 |
SOURCE_RECORD | 其他历史或未知来源记录 |
不要把所有记录直接相加
发票 ALL 保留全部业务行与原值，不删除合计行， 也不把整票与商品明细自动相加。需要发票张数或金额分析时， 必须按记录角色选对统计层级；不想自行处理的客户应使用发票 STANDARD。
来源元数据
平铺记录保留以下来源字段：
| 字段 | 含义 |
|---|---|
__sourceDatasetName | 原始工作表名称 |
__sourceArtifactName | Worker 原始制品文件名 |
__sourceRecordOrdinal | 正常入库从 1 开始的来源记录顺序；过滤空行，历史已有序数保留，非 Excel 物理行号 |
__recordRole | 记录角色 |
LEGACY 分页、CURSOR 和 PACKAGE 使用同一规则保留来源元数据。 历史 payload 已提供的来源字段不被重新编号或覆盖；数据库原始 payload 不改写。 旧任务尚未结构化入库、走历史制品兼容路径时可能没有这些可选字段。
格式参数与字段命名
普通接口 POST /api/channel/data/invoice/all 默认返回 FLAT 平铺记录。保留订单身份和鉴权信息，使用 pageNum、pageSize 翻页，无需快照或游标。
invoiceFormat 可以省略；显式填写时仅接受 FLAT（也接受旧参数名 invoice_format）。如需 Compatible_V1 字段协议，使用独立的 resultFormat 参数，见兼容协议。
统一公共字段
__fieldSchema = invoice.flat-fields.v4。整票、商品、专项、合计和历史记录采用相同的公共字段；仍用 __recordRole 区分业务含义。游标与分片交付的 schemaVersion: "invoice.v1" 是交付外壳版本，与记录字段版本含义不同。
| 内容 | 公共字段 |
|---|---|
| 原表序号 | sequence |
| 传统票代码 / 号码 | invoiceCode / invoiceNumber |
| 数电票号码 | digitalInvoiceNumber |
| 销方税号 / 名称 | sellerTaxId / sellerName |
| 购方税号 / 名称 | buyerTaxId / buyerName |
| 开票日期与时间 | issueDate |
| 金额 / 税额 / 价税合计 | netAmount / taxAmount / grossAmount |
| 商品名称 / 税收分类编码 | description / taxClassificationCode |
| 规格 / 单位 / 数量 / 单价 | specification / unit / quantity / unitPrice |
| 税率文本 / 特定业务类型 | taxRateText / specificBusinessType |
| 来源代码 / 名称 | sourceSystemCode / sourceSystemName |
| 票种代码 / 名称 | invoiceTypeCode / invoiceTypeName |
| 状态 / 风险等级 / 正数标记 | status / riskLevel / positive |
| 开票人 / 备注 | issuerName / remarks |
| 方向 / 所属企业税号 | direction / enterpriseTaxId |
字段仅在来源存在时返回。缺失、null、空串、零和布尔值不合并；不补零，不推算金额，不截掉开票时间或单价精度。税率“免税”“不征税”“***”与 0% 分别保留，状态未知不自动变成未作废或未红冲。
代码和名称分别保存，只返回原始来源明确提供的代码。历史 fpzl 的整数或纯数字字符串对应票种代码，已定义的票种名称对应名称，不能确认语义的值进入扩展区。
未知中文或 ASCII 列进入 extensions[].fieldName/value；租赁表的“车牌号”和未确认含义的历史字段保留在此处，不机械映射。来源方向和企业税号优先，缺失才补充采集上下文。
同一字段有不同原值或不同 JSON 类型时，中文来源列优先；fieldConflicts[] 保留 targetField（公共目标字段）、fieldName（来源字段）、value（原值）。1、true、"1" 是不同的值。上下文证据可用 __context.direction 等标识。
渠道若已开启“使用旧版发票 ALL 字段”，原生 ALL 改为 invoice.flat-fields.v3.1，以记录的 __fieldSchema 为准；旧版字段表、记录 Schema和线上真实脱敏响应独立提供。当前 OpenAPI 同时包含新旧两种记录模型。该设置不改变 STANDARD 和 Compatible_V1。切换后从第一页或新快照开始，不混合两套字段。
旧平铺格式需要更新整票映射
v4 不再返回整票拼音缩写和机械生成的重复别名。显式 FLAT 不会恢复旧键；客户应更新字段映射，从第一页或分片包状态重新获取。旧快照和游标不续接新字段，历史下载文件不改写。Compatible_V1 保持独立合同。
查看平铺格式字典、平铺字段 CSV和真实脱敏完整响应。完整响应使用同一订单资料按来源版本重建，通过当前契约的结构校验；没有按最新代码重新回放原件，未把其他企业的字段样例拼入该订单。
行数与张数摘要
「多少行记录」和「多少张发票」是两个数。发票 ALL 分页、CURSOR 和 PACKAGE 状态/清单都会返回统一的摘要，把两者分开说明：
| 字段 | 含义 |
|---|---|
total / recordCount / totalRecords | 当前交付完整数据集的记录行数，包含票头、明细、专项和合计等角色 |
invoiceCount | 按可靠票号去重后的真实发票张数；无法证明时为 null |
invoiceCountStatus | VERIFIED 或 UNVERIFIED |
invoiceCountMethod | 张数判定来源：信息汇总表、发票基础信息、多 Sheet 身份联合或明确空结果 |
recordRoleCounts | 六类角色在完整数据集中的总行数，各分页保持一致 |
invoiceCount 为 null 时不要用行数替代
invoiceCount 为 null 表示平台无法证明真实张数。 此时不得用 total（原始行数）冒充发票张数。
摘要按完整数据集生成；同一份交付的每页摘要一致。单页实际返回条数读取 records.length，游标响应另有 count。历史制品兼容路径可能不含这些可选摘要字段，缺少摘要不能推定张数为零。
分页
见获取数据 · 发票分页。 新建订单默认使用 PACKAGE 分片包（同时支持游标），也可手动选择 CURSOR 或 LEGACY；已有订单保持原方式。普通接口分页能力保留，见发票完整数据交付。
发票 STANDARD
响应结构
当前两环境的成功响应 data 直接包含 companyName、taxpayerId 和下面 13 个加工汇总模块，共 175 个业务字段。来源原行、空值原因和质量审计单独保存在内部；不在公开对象中增加技术头、SJZL 或一层 data 包装。两环境目前采用相同业务结构，凭据和订单各自隔离；版本见环境与凭据。
生产标准 JSON与测试标准 JSON分别匹配各自接口结构。汇总准备中可能返回 HTTP 200、code=10001、success=false、data.errorCode=INVOICE_RESULT_NOT_READY；仅这个明确状态可等待后重查。其他 10001 也可能表示参数、授权或后台来源读取、构建、存储失败，需结合 errorCode、msg 处理，不能一律轮询；无法自行处理时联系平台。
| 数据节点 | 模块 |
|---|---|
SXYNDXX | 上下游年度信息 |
JYGL | 交易概览 |
XSFX | 销售分析 |
CGFX | 采购分析 |
FYFX | 费用分析 |
YDQSXYJXSXX | 月度前十下游经销商 |
YDQSXYCPXX | 月度前十下游产品 |
YDFPHZ | 月度发票汇总 |
XYXX | 下游信息 |
SPXX | 商品信息 |
QSGYSLB | 前十供应商 |
AYHZJXPHZ | 按月进项汇总 |
XXKPAYFLTJ | 销项按月分类统计 |
金额、空值与票数
- 不含税金额、税额、价税合计分别判断可靠性；只有一项已知时保留该项，其他项为空。仅在目标值确实缺失且另两项可靠时唯一推导，显式非法值不被覆盖。
- 全范围合计中某金额维度存在未知值，该维度合计为 null，其他可靠金额继续保留。不能把部分已知金额说成完整合计，也不把未知金额补为零。
- 非作废蓝票与红字负票按票面正负号进入经济净额；已红冲正数原票与对应负数红票自然抵销。作废金额仅进入作废统计，不进入有效交易金额。
- 有效票数不重复计实际红字票；同一票的基础表、明细表和专项表不会叠加票数。进项、销项和期间分别统计，不借用另一方向或月份补值。
- 金额占比使用百分数，经济净额可使结果小于 0 或大于 100；分母为零或所需金额无法确认时为空。整数票数占比也需要确认有效票的含税金额，不能把未确认票当作非整数票。
前十榜与完整业务对象
XSFX.QSKH、CGFX.QSGYS 和 QSGYSLB 按净额可确认的交易生成榜单，金额、票数、活跃月份和末次交易日期均对应这些交易。它们不是交易方的完整流水金额；占比仍以对应全范围净额为分母，分母不完整时为空。
月度经销商榜按客户当月可确认的含税经济净额排名；月度商品榜按商品当月可确认的不含税经济净额排名。无法确认该候选完整排名金额时不进入榜单。HSJYJEHJ/BHSJYJEHJ、ZBHJ 和 JYCSHJ 只表示本月入榜项合计，并平铺在每行，不增加 MX。商品与发票的关联次数可重复计同一张含多种商品的发票，不能当作去重票数。
SXYNDXX、XYXX 和 SPXX 保留全部可识别交易方或商品，金额未知的业务项仍保留，未知金额及其排名为空。已知金额项的排名只在金额可确认的候选中比较，不代表未知金额项已被证明更小。
原件明细与重复处理
只有重复票头、同一原件中整块明细的重复次数、各业务行的重复比例，以及约分后三项金额与票头全部吻合时，才消除重复整块对统计的影响。单张票内合法的相同行保留原次数；原始 ALL 不删除记录。
商品名称可靠但金额缺失时保留商品业务对象及可确认金额；多商品无法唯一分配时不按票头均分。航空行程单单列的民航发展基金必须经过票种、分类、征税标记和三金额核对后单独区分，不能仅凭名称扣除。
模块口径
JYGL汇总非作废进销经济净额。历史代码MLL表示发票进销差额率，不是会计毛利率；采购发票可能包含费用和资产。冲红作废金额使用价税合计绝对额。XSFX/CGFX的月份变化率只比较连续上月；缺上月、上月为零或任一必要净额未知时为空。地区读取可靠原地址，包括二手车专项表地址，不从缺失金额猜税率。FYFX只按真实商品和费用类别统计；月度、分类和总计分别保留未知值。来源明确零与缺失严格区分。YDFPHZ的进销金额均为不含税经济净额；客户、供应商按名称去重。票数与金额分别遵循各自统计资格。AYHZJXPHZ的JXYXPJEHJ/JXJE为非作废进项价税净额，JXYXPZSHJ/JXZS为有效进项票数；YSXSSRHJ是进项不含税净额。XXKPAYFLTJ的YXPJEHJ/HSKPJEHJ为非作废销项价税净额。冲红和作废票额分别按绝对额统计。
滚动销售指标要求连续销项采集证明覆盖到指标计算日；缺口、未来票或必要金额缺失时不发布完整窗口数值。首次开票距今年月还要求完整开票历史证明，有限采集窗口的首票不能代替企业首次开票。
完整字段字典
本页说明的是统计规则与数据边界。逐字段的类型、必填性与取值范围以交付包内的 发票 ALL / STANDARD 字段附件（JSON / CSV）为准， 请求/响应 Schema 以接口参考为准。