获取数据

数据接口都在 /api/channel/data/* 下，使用业务码信封返回。

前提

取数前必须确认

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

公共请求体

税务、发票和报告查询都使用同一个三元组：

{
  "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）

业务码信封

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

只用 success 判定成功

接口	成功码
/tax/all、/tax/standardTable、/tax/results	200
/invoice/all	0
/invoice/standard、/invoice/results	200
/reports/status	200

差异是历史客户端契约的一部分，不会改变。一律用 success === true 判定， code 只用于失败分支细分。

失败业务码

code	含义	处理
60003	正在采集	15–30 秒后重试当前查询
60002	失败或无可交付数据	查询订单/产品的错误信息
10000	任务不存在	核对渠道编码与两类订单号
10001	参数或输出范围错误	按授权范围修正请求

接口一览

税务

接口	返回
POST /api/channel/data/tax/all	税局原始/映射数据，固定 37 个顶层节点
POST /api/channel/data/tax/standardTable	tax-standard.v2，固定完整 24 个模块
POST /api/channel/data/tax/results	按授权范围一次返回 ALL / STANDARD / WORKER_RAW

字段口径与模块状态见税务数据契约。

1.5.3 的 TAX ALL 快照不会漂移

同一任务首次生成的 TAX ALL 会固化已发布映射修订与目录哈希；后台后续调整映射 不会改写已经生成的快照。客户端不传映射版本参数，但应连同 job_id、attempt_id 和质量摘要一起保存结果。

发票

接口	返回
POST /api/channel/data/invoice/all	原始发票明细分页，默认 100、上限 1,000 条/页
POST /api/channel/data/invoice/standard	invoice-standard.v2，固定完整 13 个模块
POST /api/channel/data/invoice/results	按授权范围一次返回多种输出

字段口径与记录角色见发票数据契约。

组合接口

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

{
  "channelCode": "BANK",
  "channelOrderNo": "BANK-20260812-0001",
  "orderNo": "1e3f2f55-8da4-4ba9-b941-84860eb1d243",
  "taxDataTypes": ["ALL", "STANDARD"]
}

• 省略 taxDataTypes / invoiceDataTypes 时，默认取本次授权已选择的全部类型。
• 显式传入时必须是授权范围的子集，否则 10001。
• WORKER_RAW 返回原始制品清单（含 downloadUrl）。
• 任一子结果未就绪时，整体返回该子结果的业务码（如 60003），不会返回部分数据。

响应结构：

{
  "code": 200,
  "success": true,
  "data": {
    "ALL": {},
    "STANDARD": { "schemaVersion": "tax-standard.v2" },
    "WORKER_RAW": { "artifacts": [] }
  }
}

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

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

发票分页

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

响应 data 是标准分页对象：

{
  "current": 1,
  "size": 500,
  "pages": 6,
  "total": 2841,
  "records": [],
  "searchCount": true,
  "optimizeCountSql": true,
  "countId": null,
  "maxLimit": null,
  "orders": []
}

total 不是发票张数

total 是原始行数总计。一张发票的多个商品行会产生多条记录。 需要发票张数时使用 invoiceCount，见发票数据契约。

落库建议：

• 逐页流式落库，不要先在内存里拼完整数组。
• 以 orderNo + pageNum 做幂等键，某页失败只重试该页。
• 分页参数格式错误返回 10001。

发票量大时改用 CURSOR 或 PACKAGE。

取数决策

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[reports/status 或 htmlReports]

鉴权

/api/channel/data/* 始终要求 X-Channel-Key。渠道可被平台配置为 「仅校验 Key」或「强制校验 Key + Timestamp + Nonce + Signature」。

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