兼容字段协议

Compatible_V1 是独立的客户字段协议，直接读取本次订单保留的 Worker 原始 Excel，与原生 ALL、STANDARD 分开解析。当前契约按环境分别发布。

请求方式

在 /api/channel/data/tax/all 或 /api/channel/data/invoice/all 的每次查询中传 resultFormat: "Compatible_V1"，大小写固定。
省略或传 NATIVE 使用原生结构。税务 STANDARD、组合查询、V2 游标及分片包不支持兼容格式。
创建授权链接统一读取 authorization_code（平台订单号）和 authorization_url（授权链接）。创建接口不接受 resultFormat；兼容格式在每次税务、发票 ALL 查询时指定。取数请求的 orderNo 使用平台订单号，channelOrderNo 使用客户业务订单号。
兼容查询不能同时传 invoiceFormat、invoice_format、additionalTables、pagination、deliveryId、cursor、section、snapshotId、taxDataTypes 或 invoiceDataTypes。
channelOrderNo 是客户业务订单号；orderNo 使用授权返回或订单查询确认的平台标识，不能互换。完整请求见接口参考。

税务与发票的区别

项目	税务兼容	发票兼容
成功业务码	`200`	`0`
数据结构	`data` 下固定 30 个数组	`data.records` 中的 44 字段记录
交付方式	整包，不接受分页参数	`pageNum` 从 1 开始，`pageSize` 为 1–1000
空值规则	按各字段定义；2 个协议保留数组固定为空	按各字段定义；不补造缺失的商品明细

发票首次省略 pageSize 时使用 100。首次准备交付即冻结页大小；后续省略时沿用冻结值，传入不同值会返回 PAGE_SIZE_LOCKED。冻结内容包括原始批次与转换规则；历史冻结交付不会因平台升级自动重算。

total 是兼容记录条数，不是去重发票张数。原始票头和商品明细不能再次重复累加；金额、标识与空值须按字段字典解析，不应把缺失值统一填零，也不能通过金额猜测商品明细或购销方向。

内容核验提示

发票成功响应可能包含可选的 data.contentWarnings，每项含 code、message、verified: false。它随冻结交付的每一页返回，包括越界页的空 records，应与数据一并保存。

提示代码	含义与处理
`INVOICE_DETAIL_UNAVAILABLE`	部分发票缺少可关联商品明细，已保留可读取的原始票头。不能据此认定明细完整。
`INVOICE_HEADER_UNVERIFIED`	票头缺失、身份不完整或存在冲突，无法完整核对票头与明细覆盖。不能用记录数代替税局查询票数。
`INVOICE_OWNER_UNVERIFIED`	原始购销主体无法唯一确认，保留原值；不推断进销项方向。

以下是提示结构；兼容发票契约示例用于说明协议，不是原生 invoice.flat-fields.v4 响应，也不是本次真实订单的接口抓取：

json

{
  "contentWarnings": [
    {
      "code": "INVOICE_DETAIL_UNAVAILABLE",
      "message": "部分发票缺少可关联明细，已按原始票头保留，请勿视为完整商品明细",
      "verified": false
    }
  ]
}

成功表示该份交付可以读取，不表示所有原件均已核验通过。没有票头与明细、原件缺失或无法可靠识别的版式会返回失败，不能当作“企业没有发票”。

准备与失败

业务码 60003 表示仍在准备，按 15–30 秒间隔重试同一请求，并设置业务超时上限。60002 表示失败，读取具体错误信息后处理，不能无限轮询或把失败改写为空成功结果。资料访问权限及 SM4 加密规则继续生效。

协议或分页参数错误仍可能返回 HTTP 200：code=10001、success=false、data=null，具体原因位于顶层 errorCode。例如 RESULT_FORMAT_NOT_SUPPORTED 表示本接口不接受兼容格式，PAGE_SIZE_LOCKED 表示应沿用首次准备时冻结的页大小。错误保持明文，不按成功数据解密。

在字段字典选择税务或发票 → 完整数据 → 兼容协议，可按中文含义、字段路径检索。下载完整兼容字段及空值规则。

字段口径与下载

生产版本兼容字典覆盖税务 445 个字段及嵌套节点、发票 44 个字段，另有 2 个保留空数组。页面按业务名称解释字段，已有代码对照可直接查看；页面与下载字典保持一致。

金额按原表列与单位读取，不统一换算成元。年初、期末、本期、本年累计和上年比较列分别解释；日期字符串并非全部规范为同一格式。数值单元格按储存值读取，Excel 百分比显示格式不代表自动乘以 100。

社保申报表按已采集原表返回明细。银税互动提供申请银行名称和申请时间。缺少来源的字段保留空值，不通过其他业务字段推算。

发票金额取当前来源行：优先保留明细，并追加未被明细覆盖的票头。票头行和明细行的金额范围不同，不能把所有记录都当作整票金额重复汇总。普通字符串、金额字符串、状态转换字段的空值处理不同，以逐字段规则为准。

兼容字段协议 ​

请求方式 ​

税务与发票的区别 ​

内容核验提示 ​

准备与失败 ​

字段口径与下载 ​