税务发票数据开放平台

主题

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

五分钟快速开始 ​

本页说明从创建授权到读取税务 STANDARD 的流程。示例统一使用测试环境及其独立凭据，通过后切换生产。示例企业和订单号须替换为本次获授权的真实信息。

页顶版本条默认展示生产契约；本教程的命令实际发往测试 API。使用测试环境在线调用时，页面会同时切换到测试契约和测试地址。上线前切回生产环境并更换凭据。

准备 ​

向平台索取测试环境的凭据与渠道编码，并放进服务端环境变量。上线时将 RPA_BASE_URL 改为 https://rpa-api.xiaowu005.xyz，同时切换为生产凭据：

bash
export RPA_BASE_URL="https://rpa-test-api.xiaowu005.xyz"
export RPA_CHANNEL_KEY="rpa_channel_xxx"      # X-Channel-Key
export RPA_CALLBACK_SECRET="xxx"              # 请求签名和回调验签使用
export RPA_CHANNEL_CODE="BANK"                # 渠道编码

确认网络连通：

bash
curl -s "$RPA_BASE_URL/health"

第 1 步 · 创建授权链接 ​

bash
curl -sS -X POST "$RPA_BASE_URL/api/v1/channel/authorization-links" \
  -H "X-Channel-Key: $RPA_CHANNEL_KEY" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "external_order_id": "DEMO-20261016-0001",
    "enterprise_name": "示例企业",
    "taxpayer_id": "91420100XXXXXXXXXX",
    "collect_tax": true,
    "collect_invoice": true,
    "tax_data_types": ["ALL", "STANDARD"],
    "invoice_data_types": ["ALL", "STANDARD"],
    "invoice_period": "LAST_24_MONTHS",
    "output_encryption": "NONE"
  }'

本例省略 invoice_delivery_mode，新建订单默认准备分片包，并支持游标和普通接口分页。需要指定其他方式时，可传 CURSOR 或 LEGACY；历史订单保持原方式。

如需先核对默认行为，可在接口页选择“最小请求”，只传三个必需业务字段，并查看配对的“最小请求的默认响应”。下载授权和状态响应示例；其中日期为隔离演示当日的实际计算结果，后续调用以服务端返回为准。

创建成功返回 HTTP 200。下面只展示需保存的响应字段，完整结构见创建授权接口（测试环境）：

json
{
  "authorization_code": "550e8400-e29b-41d4-a716-446655440000",
  "authorization_url": "https://rpa-test-auth.xiaowu005.xyz/user/authorization/taxXyd?...",
  "external_order_id": "DEMO-20261016-0001",
  "expires_at": "2026-10-16 18:30:00"
}

expires_at 固定按北京时间（UTC+8）返回，格式为 YYYY-MM-DD HH:mm:ss。

直接跳转，不要拼接

authorization_url 由平台按本次申请动态生成。客户前端必须原样打开它， 自行拼接授权页地址会导致授权失败。

第 2 步 · 完成授权 ​

在浏览器打开 authorization_url，按页面提示完成税局登录与授权确认。 授权首次提交有效期继承渠道配置，初始默认 30 分钟（expires_in_seconds 按秒传入）；最长 15 天，传 1296000；已提交的采集不受该期限中断。其他期限见期限说明。

第 3 步 · 等待采集完成 ​

隔一段时间查一次订单状态（即「轮询」），间隔不低于 15 秒：

bash
curl -sS "$RPA_BASE_URL/api/v1/channel/orders/DEMO-20261016-0001" \
  -H "X-Channel-Key: $RPA_CHANNEL_KEY"

看两个字段：

  • state —— SUCCESS 或 ERROR 表示当前轮次结束；CONNECT / PROCESS 继续等，INTERACTION 需用户按授权页完成验证码或身份确认。
  • job_id —— 下一步取数要用，它就是数据接口里的 orderNo。

生产环境应以回调通知为主，轮询只在没收到回调时兜底。

第 4 步 · 确认产品可取数 ​

bash
curl -sS "$RPA_BASE_URL/api/v1/channel/orders/DEMO-20261016-0001/products/TAX" \
  -H "X-Channel-Key: $RPA_CHANNEL_KEY"

取数前提

必须 state == "SUCCEEDED" 且 available == true。 不要用页面进度百分比或整单 state 代替这个判断。

整单可能因收入核验未通过而为 ERROR，同时税务产品仍可取数。保存可用资料时也要保存订单状态、revenueCheck 和质量信息；下载成功不表示整单业务校验通过。整单仍为 PROCESS 时，继续通过订单查询或回调跟踪整单结果。

第 5 步 · 取数 ​

把产品查询的 job_id 填进 orderNo。以下 curl 展示仅 Key 模式；目标环境要求签名时，用下方客户端或签名示例，每次使用新的 Nonce：

bash
curl -sS -X POST "$RPA_BASE_URL/api/channel/data/tax/standardTable" \
  -H "X-Channel-Key: $RPA_CHANNEL_KEY" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "channelCode": "'"$RPA_CHANNEL_CODE"'",
    "channelOrderNo": "DEMO-20261016-0001",
    "orderNo": "1e3f2f55-8da4-4ba9-b941-84860eb1d243"
  }'

成功时 success 为 true：

json
{
  "code": 200,
  "msg": "操作成功",
  "success": true,
  "data": {
    "companyName": "示例企业",
    "data": { "taxCollQryStartDate": null, "taxCollQryEndDate": null }
  }
}

上例只展示响应外壳和必需查询日期字段；实际有记录的业务模块位于内层 data。查询日期无法确认时为 null，不表示采集为空或完整。

下载同一批次的税务标准完整响应及来源说明。这份历史原件重建响应保留完整记录，字段字典中的逐字段样例则可能来自不同企业或期间。

取发票前同样查询 /products/INVOICE，确认 SUCCEEDED 且 available=true，再用普通接口 /api/channel/data/invoice/all 按页码读取发票数据， 注意它成功码是 0：

bash
curl -sS -X POST "$RPA_BASE_URL/api/channel/data/invoice/all" \
  -H "X-Channel-Key: $RPA_CHANNEL_KEY" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "channelCode": "'"$RPA_CHANNEL_CODE"'",
    "channelOrderNo": "DEMO-20261016-0001",
    "orderNo": "1e3f2f55-8da4-4ba9-b941-84860eb1d243",
    "pageNum": 1,
    "pageSize": 500
  }'

默认分片包的状态、清单与下载流程见发票完整数据交付。

可下载的最小客户端 ​

下载 Python 最小客户端。仅使用 Python 标准库；数据请求自动签名，检查 HTTP 和业务错误，按产品就绪条件取数，并在最多 2 小时后停止等待。它保存完整响应、订单身份和质量信息到本机 tax-standard.json。

填写本次环境、凭据及业务订单号：

bash
export RPA_BASE_URL="https://rpa-test-api.xiaowu005.xyz"
export RPA_CHANNEL_KEY="本环境的 API Key"
export RPA_CALLBACK_SECRET="本环境的 Callback Secret"
export RPA_CHANNEL_CODE="本环境的渠道编码"
export RPA_ORDER_ID="本环境已有且选择税务 STANDARD 的订单号"
python3 rpa_quickstart.py

需要新建授权时，再设置企业信息并显式加 --create：

bash
export RPA_ORDER_ID="本次新的业务订单号"
export RPA_ENTERPRISE_NAME="本次获授权的企业名称"
export RPA_TAXPAYER_ID="本次企业的纳税人识别号"
python3 rpa_quickstart.py --create

该示例创建 output_encryption=NONE 订单，同时选择税务、发票 ALL 和 STANDARD，最后读取税务 STANDARD。已有订单必须与请求的输出范围匹配；SM4 订单按加密指南解密后读取。不要用 --create 更改已有订单的参数。

脚本中的轮询用于联调和回调补偿；正式服务优先接收回调。60003 只重试同一查询，HTTP 鉴权或权限错误直接停止，未将失败当作空数据。

接下来 ​

你要做的事去哪一篇
用回调代替轮询回调通知
发票量很大大批量发票交付
需要 PDF / HTML 报告PDF 与 HTML 报告
渠道被要求强制签名鉴权与签名
准备上生产上线检查清单

文档契约 API 1.5.169

税务发票数据开放平台