环境与凭据

环境地址

环境	API	授权页	用途
生产	`https://rpa-api.xiaowu005.xyz`	`https://rpa-auth.xiaowu005.xyz`	正式业务调用
测试	`https://rpa-test-api.xiaowu005.xyz`	`https://rpa-test-auth.xiaowu005.xyz`	使用测试凭据和订单联调

健康检查：

bash

curl -s https://rpa-api.xiaowu005.xyz/health

当前字段契约

环境	文档契约	源码提交	契约下载	线上核对
生产环境	1.5.169	`07e96bed`	字段目录接口契约	正在核对线上版本…
测试环境	1.5.169	`07e96bed`	字段目录接口契约	正在核对线上版本…

在线字段字典和接口参考默认展示生产契约。上表从本次发布的契约清单读取版本与提交；运行版本分别通过两环境 /health 核对。门户自身版本及所绑定契约见发布清单。

各环境的文档契约版本、源码提交和线上核对状态以上表为准。凭据、订单和业务数据各自隔离。测试接入可下载测试 OpenAPI及测试字段目录，不能只换域名后继续使用生产订单或凭据。

税务 ALL 使用 tax-all-business.v3 完整独立对象。STANDARD 包含企业名称、两个查询日期及有记录的业务模块：30 个模块、391 个模块内字段，另含 taxCollQryStartDate 和 taxCollQryEndDate，合计 393 个公开字段。缺少可信查询范围时两个日期保留 null。发票完整数据默认使用 FLAT v4；普通接口按 pageNum、pageSize 翻页，发票 STANDARD 为 13 个业务模块。

当前版本的取数与期限规则

当前版本与提交以上表为准。API 1.5.144 起原生税务 ALL 使用完整业务对象；STANDARD 与 Compatible_V1 保持各自合同。下列既有规则继续适用。

项目	当前规则
申报更正 `SBGZ`	更正前原值可来自明确标记为被更正申报表的历史主表；历史主表不混入当前申报
更正次数 `GZCS`	仅接受税局明确次数；候选序号、主附表数量和历史版本数均不能替代次数
客户和供应商地区 `DQ`	补充二手车购买方、销方地址；缺净额的原票可补已有交易对手地区，不补计金额
发票采集期限	渠道固定期限优先；跟随客户传参时省略默认 `CURRENT_YEAR_PLUS_2`。创建时冻结，已有订单、续期与重试不随渠道变更

授权链接有效期省略时继承渠道配置，初始为 1800 秒、上限为 1296000 秒；接入时核对目标环境的健康检查版本。查询兼容数据时，每次请求指定 Compatible_V1，详见兼容格式。

订单查询的 pdfReports 从 API 1.5.21 起提供，详见 PDF 与 HTML 报告。三类访问期限从 1.5.27 起提供，北京时间截止格式从 1.5.28 起统一，原始文件签名下载从 1.5.29 起提供；授权链接上限从 1.5.32 起提高至 15 天。当前生产与测试均已覆盖这些能力，详见授权、分享与资料期限。

凭据

凭据	用途	存放位置
API Key	`X-Channel-Key` 请求头	客户服务端环境变量 / 密钥管理服务
Callback Secret	计算请求签名、验证回调签名、派生 SM4 密钥都靠它	同上
渠道编码	数据接口请求体的 `channelCode`	可作为普通配置

Callback Secret 承担三重职责，泄露后果比 API Key 更严重：

计算 X-Channel-Signature（V2 接口与开启强制签名的数据接口）；
校验平台回调的 X-RPA-Signature；
当订单启用 output_encryption=SM4 时，派生 SM4 密钥。

隔离要求

测试与生产使用各自独立的 API Key 和 Callback Secret，不得混用。
两个环境的订单与数据相互隔离；正式上线后需在生产环境重新创建业务订单。
凭据不得出现在前端代码、移动端包体、日志、监控标签或工单附件中。

请求约定

项目	要求
POST 请求体	JSON，`Content-Type: application/json; charset=utf-8`
V1 授权、订单、产品查询	携带 `X-Channel-Key`；签名文件下载直接使用完整链接
V1 数据接口	至少 `X-Channel-Key`；目标环境启用强制签名时还需时间戳、Nonce、签名
V2 发票接口	必须同时携带 Key、时间戳、Nonce、HMAC 签名
状态查询	优先接收回调；轮询间隔 15–30 秒
访问截止时间	北京时间（UTC+8），`YYYY-MM-DD HH:mm:ss`，具体字段见期限说明
其他时间字段	按各字段契约解析；签名时间戳与 URL 的 `expires` 保持 Unix 秒

回调与返回地址的配置

callback_url、success_url、exit_url 三个地址会经过平台安全校验：

success_url、exit_url 默认使用完整公网 HTTPS 地址；渠道已开启「非 HTTPS 跳转」时，还可使用公网 HTTP 或安全 App 自定义协议；
callback_url 默认必须是公网 HTTPS；只有平台超级管理员为所属客户机构开启安全例外后，才可使用公网 HTTP；
HTTP 例外仍禁止本机、内网和非公网 DNS 目标，建议同时启用 output_encryption=SM4；
返回地址应指向客户自己的业务页面，不能与平台管理/API 公开地址同源；
未在请求中传入时，使用渠道在平台后台配置的默认值。

联调前把测试回调地址与返回地址提供给平台配置；正式上线前再配置生产地址。

联调建议

在测试环境完成授权创建、页面跳转、结果通知、状态查询、数据获取的全流程。
覆盖成功、处理中、失败、重复回调、签名错误、链接过期六类场景。
当前公网测试环境关闭 simulator。真实采集须取得企业授权；ALL 下载中的业务样本来自真实订单脱敏后重建的响应，传输状态另标为结构示例。样本来源版本与当前测试部署版本分别记录。
生产上线前，在生产环境用一笔真实订单完成端到端验证。

环境与凭据 ​

环境地址 ​

当前字段契约 ​

当前版本的取数与期限规则 ​

凭据 ​

请求约定 ​

回调与返回地址的配置 ​

联调建议 ​