税务发票数据开放平台

主题

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

用 Bruno 联调 ​

Bruno 是什么 ​

Bruno 是一个开源的 API 客户端，作用和 Postman、Insomnia 类似：管理请求、切换环境、 发请求看响应。区别在于两点，正好是我们把它选成联调工具的原因：

  • 请求以纯文本文件存盘（.bru），一个接口一个文件，可以直接进 Git、能 diff、能 review。
  • 集合可在本地管理，密钥在自己的客户端配置。发送请求时，参数会交给所选 API 环境；不要把带密钥的集合提交到仓库。

下面是装好我们的接口包之后的样子：左边是按业务分组的接口请求（22 个接口，部分接口提供多个请求示例）， 右边是集合自带的说明文档。

Bruno 装载「税务发票数据开放平台」接口包后的主界面
Bruno 装载「税务发票数据开放平台」接口包后的主界面

下载 Bruno ​

从 Bruno 官方下载页选择自己的系统与架构。Windows 免安装包在官网选择 Portable，解压后运行 Bruno.exe；不要把文档截图中的旧版本号当作必须安装的版本。

本站集合使用 Bruno 4.x 的环境、Secrets 与脚本格式生成，并通过官方序列化器和请求脚本测试。第三方软件由 Bruno 官方提供，平台只提供接口集合。界面名称随软件版本可能略有差异。

导入管理员提供的调试接口包 ​

平台管理员会为每个客户单独准备一份调试专用接口包，提前配置好该客户的接口编码、 已准备的业务订单、任务编号和企业信息。拿到管理员提供的 zip 后直接解压， 不需要先在文档站重新生成。

打开调试接口包 ​

解压后在左侧 Collections 面板点 ⋮ 选 Open collection， 选中解压出来的 税务发票数据开放平台 目录：

Collections → Open collection
Collections → Open collection

是 Open 不是 Import

Open collection 直接打开磁盘上的目录，改动落回文件、可以进版本库。 Import collection 是给 Postman 等外部格式用的，这里不要选。

右上角选择管理员指定的 测试环境 / 生产环境：

右上角环境切换
右上角环境切换

管理员提供的调试包已经预置日常联调所需的订单与接口信息，通常不需要修改。 如果管理员要求更换订单或单独交付密钥，可以点环境名进入变量表： Variables 放订单等普通信息，Secrets 放 API Key 与 Callback Secret。

如果订单启用了 SM4，集合会用当前环境的 Callback Secret 校验 GCM Tag，校验通过后 自动把响应解密成普通 JSON；任务号、下载地址和游标仍会照常自动传递。密钥错误或密文 被篡改时，请求会直接显示解密失败，不会把未认证的内容交给后续脚本。

Variables 与 Secrets 分开管理
Variables 与 Secrets 分开管理

典型顺序 ​

mermaid
flowchart LR
  A[打开管理员提供的调试包] --> B[选择指定环境]
  B --> C[查询已准备的订单]
  C --> D[查询产品状态]
  D --> E[取数 / 下载报告]
  1. 打开管理员提供的调试接口包，选择管理员指定的环境。
  2. 运行 查询订单。管理员准备的订单应处于可联调状态；响应里的 job_id、Worker 文件地址、 在线 HTML 地址和 pdfReports 中的 PDF/同源 HTML 下载地址会自动保存为运行时变量，无需手抄。
  3. 查询税务/发票产品状态，确认 state=SUCCEEDED 且 available=true。
  4. 按需调 税务数据 / 发票数据 / 报告 下的接口。报告尚未生成时继续查询订单； 查询报告状态 是计划弃用的兼容接口，新流程无需单独调用。分片包状态和分片清单继续自动传递所需地址或 ID。

集合里的每个请求都校验 HTTP 状态码；401、422 等响应会在 Runner 中标为失败，HTTP 200 内的 success=false 也会判为业务失败。不会因为“收到了响应”而显示成绿色。依赖上一条响应的下载或续拉请求在缺少 URL、 exportId 或 cursor 时会在 Runner 中显示为跳过；单独发送时仍会明确提示缺少哪个变量。

自定义结构包 ​

需要自行选择环境、填写订单信息或生成其他结构时，可以在下面配置后下载。 测试环境和生产环境默认都会放进包里；不需要哪个环境，取消对应的勾选即可。 两个环境分别填写接口编码、业务订单、任务编号、API Key 与 Callback Secret；生产凭据 不会复用到测试环境，测试凭据也不会写进生产环境文件。 每个环境还可以分别选择 NONE 或 SM4；选择 SM4 后，创建授权请求会带上加密开关， 后续成功 JSON 响应由集合自动解密，无需另装 SM4 依赖。 同一个业务订单号只允许用完全相同的授权参数重试；如果切换 NONE / SM4、采集范围 或交付方式，请换一个新的业务订单号，否则平台会返回 409 EXTERNAL_ORDER_CONFLICT。

环境
默认全部选中；每个环境使用各自的接口编码、订单和密钥，不会互相复用。
测试环境https://rpa-test-api.xiaowu005.xyz
生产环境https://rpa-api.xiaowu005.xyz

默认不写。两项会作为 Bruno 的 secret 变量留空，导入后在 Bruno 里填， 存本机不进文件 —— 这样生成的包可以安全地传给同事或提交进 Git。

正在载入集合模板…

生成过程全在本地

zip 是在你的浏览器里用集合模板拼出来的，参数和密钥不会上传到任何地方。 默认不会把 API Key 和 Callback Secret 写进包里；如需生成可直接调试的专用包， 可以勾选写入，但不要把带明文密钥的包转发或提交进 Git。

税务 ALL 附表请求 ​

下载包中的“获取税务 ALL（默认数据＋按需附表）”示例显式传入 additionalTables: []，表示仅默认范围；若需继承创建授权时保存的订单附表选择，请删除该字段。选择其他表前先调用表单目录接口，确认表编码与支持状态；表必须已经纳入本批次采集计划，取数参数不会补采缺失附表。

文档契约 API 1.5.169

税务发票数据开放平台