主题
平台概览
版本基线
本文档适配平台 1.5.3，客户接口基线仍为 R4.4。接口路径和签名算法未变化； 1.5.3 主要收紧了采集质量披露、TAX ALL 映射快照和 HTML 报告统计口径。
税务发票数据开放平台把「企业授权 → 税局采集 → 数据交付」封装成一组 HTTP 接口。 客户系统不接触企业的税局账号密码，也不需要维护采集脚本， 只需要在自己的服务端完成三件事：发起授权、接收结果、获取数据。
角色与边界
| 角色 | 职责 | 是否接触税局凭据 |
|---|---|---|
| 客户服务端 | 创建授权、接收回调、取数落库 | 否 |
| 客户前端 | 把用户跳转到平台返回的 authorization_url | 否 |
| 企业用户 | 在平台授权页登录税局、确认授权协议 | 是 |
| 平台 | 调度采集、质量校验、结构化加工、交付 | 是 |
凭据边界
API Key 与 Callback Secret 必须只存在于客户服务端。写入前端代码、移动端包体、 公开日志或第三方分析参数都视为泄露。测试环境与生产环境使用各自独立的凭据。
一次授权能产出什么
创建授权时的选择决定了后续能取到哪些数据。授权阶段没有选择的输出类型， 取数阶段不能临时扩大范围。
| 产出 | 由什么控制 | 取数接口 |
|---|---|---|
| 税务 ALL（税局原始/映射，37 节点） | tax_data_types 含 ALL | /api/channel/data/tax/all |
| 税务 STANDARD（标准化，24 模块） | tax_data_types 含 STANDARD | /api/channel/data/tax/standardTable |
| 发票 ALL（源列透传，分页） | invoice_data_types 含 ALL | /api/channel/data/invoice/all 或 V2 交付 |
| 发票 STANDARD（标准化，13 模块） | invoice_data_types 含 STANDARD | /api/channel/data/invoice/standard |
| Worker 原始表格文件 | 对应类型数组含 WORKER_RAW | 制品下载接口 |
| PDF 报告 | pdf_report_types | 报告状态接口 + 签名链接 |
| HTML 在线报告 | generate_html_reports | 结果中的 accessUrl |
ALL 与 STANDARD 的取舍
这是接入时最重要的一个决定。
| ALL | STANDARD | |
|---|---|---|
| 语义 | 税局原始/映射数据，尽量保真 | 平台加工后的分析结构 |
| 结构稳定性 | 固定 37 个顶层节点，节点内允许新增字段；同一任务快照固化映射修订 | 固定模块与字段字典 |
| 空值含义 | 源表没有该列 | 模块状态明确区分「已证明为空」与「来源不足」 |
| 适合 | 自建风控模型、需要原始凭证 | 直接消费经营/销售/采购分析结论 |
建议
不确定时两者都选。同一次采集同时产出 ALL 与 STANDARD 不会增加采集次数， 只是多一份加工输出；后续任何一方口径存疑，都能立刻回到另一方交叉验证。
两套返回结构
平台有两代接口共存，返回结构不同，必须分别处理。
| 结构 | 使用接口 | 成功判定 |
|---|---|---|
| 业务码信封 | /api/channel/data/* | success === true |
| 标准 REST | /api/v1/channel/*、/api/v2/channel/* | HTTP 2xx |
业务码信封的 HTTP 状态码始终是 200，真正的结果在 code / success 里：
json
{ "code": 200, "msg": "操作成功", "message": "操作成功", "success": true, "data": {} }不要硬编码 code
税务与报告接口成功码是 200，发票 ALL 成功码是 0，组合接口又统一为 200。 一律使用 success === true 判定成功，把 code 只用于失败分支的细分。