税务发票数据开放平台

环境与访问边界

测试与生产的域名、Key、Secret、订单和数据完全隔离。

测试环境https://rpa-test-api.xiaowu005.xyz

生产环境https://rpa-api.xiaowu005.xyz

凭据边界：API Key 和 Callback Secret 只保存在客户服务端；不要写入前端、日志、邮件或工单。切换环境时，域名与凭据必须同时切换。

正确的接入流程

不要把“授权完成”误判为“数据可取”。

1
创建授权链接
客户服务端调用 A1，保存 external_order_id 和 authorization_code。
2
企业完成授权
前端直接打开 authorization_url，由企业用户完成税局验证。
3
接收回调或轮询
回调先验签、再按 event_id 去重；未收到时每 15–30 秒查询。
4
确认产品可取
调用 A3，只有 state=SUCCEEDED 且 available=true 才进入取数。
5
按交付形态取数
选择 ALL、STANDARD、WORKER_RAW、PDF、HTML，或发票 CURSOR / PACKAGE。

!

唯一可靠的取数门禁

整单 SUCCESS 只表示作业终结。读取税务或发票前，必须检查对应产品 state=SUCCEEDED 且 available=true。

17 条客户接口

管理、计费、Worker 和授权页内部接口不在本清单中。

鉴权、请求签名与回调验签

三种签名场景不能混用。

A1–A4

Key 鉴权

X-Channel-Key: <API_KEY>

创建授权、查询订单/产品、下载 Worker 原始文件。

B1–B3

强制请求签名

Key + Timestamp + Nonce + Signature

时间误差不超过 300 秒，Nonce 不可重放，Body 哈希必须基于实际原始字节。

CALLBACK

回调验签

X-RPA-Signature

用 Callback Secret 对收到的原始 HTTP Body 做 HMAC-SHA256，先验签再解析 JSON。

H1 / D5 / B4

签名下载链接

GET accessUrl / downloadUrl

直接访问返回的链接，不自行拼接，不附加渠道请求头。

查看请求签名原文

timestamp
nonce
METHOD
request_path
raw_query_string
sha256(raw_request_body)

signature = "sha256=" + HMAC_SHA256_HEX(Callback Secret, canonical)

上线前必查

这些规则决定能否稳定联调。

新接入不要传 data_delivery_mode、tax_url、support_long_auth 或 need_verify_code。
税务 ALL 固定返回 V2 的 37 个顶层数组；发票 ALL 必须允许后续新增源列。
STANDARD 必须按 schemaVersion 解析；税务 24 模块，发票 13 模块。
回调可能重复或乱序；按 event_id 去重，数据保存提交后再返回 2xx。
HTML 的 accessUrl 是访问凭证，固定 7 天且不续期；不要写入公开日志。
CURSOR / PACKAGE 仅影响发票 ALL；保存游标、datasetId/exportId、分片号和 SHA-256 检查点。