主题
平台概览
税务发票数据开放平台把「企业授权 → 税局采集 → 数据交付」封装成一组 HTTP 接口。 客户系统不接触企业的税局账号密码，也不需要维护采集脚本， 只需要在自己的服务端完成三件事：发起授权、接收结果、获取数据。
角色与边界
| 角色 | 职责 | 是否接触税局凭据 |
|---|---|---|
| 客户服务端 | 创建授权、接收回调、取数并保存 | 否 |
| 客户前端 | 把用户跳转到平台返回的 authorization_url | 否 |
| 企业用户 | 在平台授权页登录税局、确认授权协议 | 是 |
| 平台 | 调度采集、质量校验、结构化加工、交付 | 是 |
凭据边界
API Key 与 Callback Secret 必须只存在于客户服务端。写入前端代码、移动端包体、 公开日志或第三方分析参数都视为泄露。测试环境与生产环境使用各自独立的凭据。
一次授权能产出什么
创建授权时的选择决定了后续能取到哪些数据。授权阶段没有选择的输出类型， 取数阶段不能临时扩大范围。
| 产出 | 由什么控制 | 取数接口 |
|---|---|---|
| 税务 ALL（完整业务对象，按选择交付） | tax_data_types 含 ALL | /api/channel/data/tax/all |
| 税务 STANDARD（标准化业务模块） | 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 | 订单查询的 pdfReports + 签名链接 |
| HTML 在线报告 | generate_html_reports 请求详版、简版；pdf_report_types 中的 TAX_RISK 请求财税风险报告 | 订单查询的 htmlReports.reports[].accessUrl |
ALL 与 STANDARD 的取舍
这是接入时最重要的一个决定。
| ALL | STANDARD | |
|---|---|---|
| 语义 | 税局原始/映射数据，尽量保真 | 平台加工后的分析结构 |
| 结构 | 税务为完整对象；发票为统一字段记录，按授权范围交付 | 模块范围见税务与发票说明 |
| 空值含义 | 保留缺失字段、null、空串及零；通用表单另有 presence | 缺少可靠原值时留空，不把缺失填零 |
| 适合 | 自建风控模型、需要原始凭证 | 直接消费经营/销售/采购分析结论 |
建议
不确定时两者都选。同一次采集同时产出 ALL 与 STANDARD 不会增加采集次数， 只是多一份加工输出；后续任何一方的数字有疑问，都能立刻拿另一方交叉验证。
返回结构
JSON 查询与文件下载分别处理。
| 结构 | 使用接口 | 成功判定 |
|---|---|---|
| 业务码信封 | 税务、发票数据查询及报告状态查询 | HTTP 2xx 且 success === true |
| 状态 JSON | 授权、订单、产品和 V2 发票交付查询 | HTTP 2xx 表示查询成功；仍须检查产品可用状态或交付状态 |
| 文件或 HTML | 原始文件、报告、分片与大记录下载 | 检查 HTTP 状态，按对应下载协议校验内容 |
业务码信封在 HTTP 200 中仍可能表示业务失败；先处理 HTTP 鉴权、权限与限流错误，再看响应的 code / success：
json
{ "code": 200, "msg": "操作成功", "message": "操作成功", "success": true, "data": {} }不要硬编码 code
税务与报告接口成功码是 200，发票 ALL 成功码是 0，组合接口又统一为 200。 一律使用 success === true 判定成功，把 code 只用于失败分支的细分。