税务发票数据开放平台

主题

生产环境文档契约 1.5.169
正在核对线上版本…
下载接口契约环境与版本

获取数据 ​

常规数据接口位于 /api/channel/data/*。先判断 HTTP 状态，再读取业务码： 鉴权、权限、限流和交付冲突可能返回 401、403、409、413、429 等； HTTP 200 内仍可能有业务失败。开启 SM4 后，成功 JSON 先解密，再判断业务码。

前提 ​

取数前必须确认

对应产品 state == "SUCCEEDED" 且 available == true。 取数范围不得超过创建授权时已选择的输出类型。

公共请求体 ​

普通税务、发票和旧报告状态查询使用下面三个字段。税务表单目录只需鉴权及空 JSON {}，无需企业订单；V2 发票接口不传 channelCode，两个订单字段按各自接口定义发送。

json
{
  "channelCode": "BANK",
  "channelOrderNo": "BANK-20260812-0001",
  "orderNo": "1e3f2f55-8da4-4ba9-b941-84860eb1d243"
}
字段取值
channelCode渠道编码，必须与 X-Channel-Key 所属渠道一致，否则 403
channelOrderNo创建授权时的 external_order_id
orderNo订单查询返回的 job_id（也接受 authorization_code）

业务码信封 ​

「信封」的意思：HTTP 层的 200 只是一层外壳，先看 success 与 code 才知道这次调用到底成没成功，data 里才是真正的内容。

json
{
  "code": 200,
  "msg": "操作成功",
  "message": "操作成功",
  "success": true,
  "data": {}
}

只用 success 判定成功

接口成功码
/tax/all、/tax/standardTable、/tax/results200
/invoice/all0
/invoice/standard、/invoice/results200
/reports/status（计划弃用，迁移至订单查询的 pdfReports）200

这些接口沿用不同的成功业务码，使用 success === true 判定， code 只用于失败分支细分。

失败业务码 ​

code含义处理
60003采集、加工或交付准备中15–30 秒后重试当前查询
60002失败或无可交付数据查询订单/产品的错误信息
10000任务不存在核对渠道编码与两类订单号
10001参数、输出范围或发票汇总处理状态data.errorCode=INVOICE_RESULT_NOT_READY 时等待重查；其他汇总处理错误按 errorCode、msg 联系平台处理来源或后台任务；参数和授权范围错误则修正请求

接口一览 ​

税务 ​

接口返回
POST /api/channel/data/tax/alltax-all-business.v3 完整对象，按默认范围与所选附表交付
POST /api/channel/data/tax/standardTable企业名称与业务对象；30 个业务模块、391 个模块内字段及 2 个查询日期字段；只返回有记录的业务模块
POST /api/channel/data/tax/results按授权范围一次返回 ALL / STANDARD / WORKER_RAW

字段含义与模块状态见税务数据说明。

保存结果及其来源版本

已生成的快照保留。转换规则、原始内容或来源身份变化时可能生成新快照。 客户端不传映射版本参数，应连同订单、采集批次、响应中实际提供的来源标识和质量摘要保存每次结果。非分页明细支持 HTTP gzip；启用 pagination=true 后按交付快照逐页读取， 需重组路径记录并确认接收，见税务分页交付。

完整对象、原值语义和下载附件见完整业务对象；同一真实订单的脱敏完整响应见样例下载。

发票 ​

接口返回
POST /api/channel/data/invoice/allinvoice.flat-fields.v4 记录分页，默认 100、上限 1,000 条/页
POST /api/channel/data/invoice/standardinvoice-standard.v2，固定完整 13 个模块
POST /api/channel/data/invoice/results按授权范围一次返回多种输出

字段含义与记录角色见发票数据说明。

组合接口 ​

/tax/results 与 /invoice/results 用一次调用取回多种输出，减少往返：

json
{
  "channelCode": "BANK",
  "channelOrderNo": "BANK-20260812-0001",
  "orderNo": "1e3f2f55-8da4-4ba9-b941-84860eb1d243",
  "taxDataTypes": ["ALL", "STANDARD"]
}
  • 省略 taxDataTypes / invoiceDataTypes 时，默认取本次授权已选择的全部类型。
  • 显式传入时必须是授权范围的子集，否则 10001。
  • WORKER_RAW 返回原始制品清单（含 downloadUrl）。
  • 税务组合接口启用 pagination=true 时只接受 taxDataTypes=["ALL"]；STANDARD 和 WORKER_RAW 单独查询。
  • 任一子结果未就绪时，整体返回该子结果的业务码（如 60003），不会返回部分数据。

响应的 data.ALL 使用对应单接口的业务结构；STANDARD 和 WORKER_RAW 各自按专用合同读取。 下载仅请求 ALL 的税务组合完整响应和发票组合完整响应。样例未拼入其他订单的 STANDARD 或原始制品结果。

组合接口的成功码统一是 200

即使其中包含发票 ALL 子结果，/invoice/results 的成功码仍是 200， 而不是单接口的 0。

发票分页 ​

json
{
  "channelCode": "BANK",
  "channelOrderNo": "BANK-20260812-0001",
  "orderNo": "1e3f2f55-8da4-4ba9-b941-84860eb1d243",
  "pageNum": 1,
  "pageSize": 500
}

新建含发票订单默认采用分片包（同时支持游标）；已有订单保持原交付方式，普通接口分页能力保留。

普通接口默认返回 FLAT 平铺记录，数据在 data.records 中。第二页保留鉴权和订单身份，将 pageNum 改为 2，pageSize 按所需大小填写；无需 snapshotId、cursor 或 invoiceFormat。

同一轮读取保持 pageSize 不变，避免页面边界变化造成漏读或重复。采集批次或字段版本变化后，从第一页重建该轮结果。

total 是记录行数，invoiceCount 是经核验的发票张数，无法核实时为 null。游标与分片包使用各自的专用接口，见发票完整数据交付。

取数决策 ​

mermaid
flowchart TD
  A[产品 SUCCEEDED 且 available] --> B{要哪种数据}
  B -->|税务| C[tax/all 或 tax/standardTable 或 tax/results]
  B -->|发票 STANDARD| D[invoice/standard]
  B -->|发票 ALL| E{数据量}
  E -->|小| F[invoice/all 分页]
  E -->|边拉边处理| G[V2 cursor]
  E -->|大批量离线| H[V2 package]
  B -->|原始表格文件| I[artifacts downloadUrl]
  B -->|PDF / HTML 报告| J[订单查询 pdfReports / htmlReports]

鉴权 ​

本页的 POST 数据查询以及税务分页读取始终要求 X-Channel-Key；PDF、同源 HTML 等签名文件下载直接使用完整链接。目标环境可被平台配置为 「仅校验 Key」或「强制校验 Key + Timestamp + Nonce + Signature」。

若提交了任一签名头，三项签名头必须齐全，否则 401 CHANNEL_SIGNATURE_REQUIRED。 签名算法见鉴权与签名。

文档契约 API 1.5.169

税务发票数据开放平台