主题
创建授权
POST /api/v1/channel/authorization-links
这是一切业务的起点。客户服务端在请求体中声明采集范围、输出类型、交付方式与回调配置； 企业用户在授权页只负责登录税局和确认协议，不填写任何业务参数。
最小请求
http
POST /api/v1/channel/authorization-links
X-Channel-Key: rpa_channel_xxx
Content-Type: application/json; charset=utf-8json
{
"external_order_id": "BANK-20260812-0001",
"enterprise_name": "示例企业",
"taxpayer_id": "91420100XXXXXXXXXX"
}省略的字段全部走默认值：采集税务和发票、发票期间 CURRENT_YEAR_PLUS_2、 不加密、不生成报告；期限省略时继承渠道默认值，初始配置为资料保留 30 天、分享 7 天、授权提交 1800 秒。
必填字段
| 字段 | 说明 |
|---|---|
external_order_id | 客户业务订单号，同一渠道内唯一，最长 128 字符。平台用它识别重复请求：同一个订单号不会创建出第二笔授权，见重复提交的处理规则 |
enterprise_name | 企业名称，最长 256 字符 |
taxpayer_id | 统一社会信用代码 / 纳税人识别号，3–64 字符 |
采集范围
| 字段 | 默认 | 说明 |
|---|---|---|
collect_tax | true | 是否采集税务 |
collect_invoice | true | 是否采集发票 |
invoice_period | CURRENT_YEAR_PLUS_2 | 发票采集期间 |
collect_tax 与 collect_invoice 至少一项为 true。
税务 ALL 附表选择
创建授权时可传 additional_tables（也接受 additionalTables），确定本订单需要采集的税务附表，并作为 ALL 取数的默认选择；省略为 []，只采默认范围。启用税务采集且税务输出包含 ALL 时可选附表，响应以 additionalTables 返回选择。
表编码与支持状态从 POST /api/channel/data/tax/tableCatalog 查询，按接口参考提供鉴权和请求参数。仅选择 supported=true 的表；默认表由服务端固定包含。未启用选择功能的环境拒绝非空附表参数。
- 取数
/api/channel/data/tax/all或/tax/results省略additionalTables时，使用订单默认值。 - 显式传入数组可在本批次已采范围内选择；
[]表示仅默认主表和基础范围。未采附表不能在取数时补出，追加采集范围需要新一轮采集；不能按全部协议数组必定出现来解析。 - 已发出的
cursor/deliveryId保留原交付选择；不重新套用订单默认值。 - 同订单重复创建授权时选择必须一致，否则返回冲突；重新授权继承原选择。
本参数会影响 Worker 的税务采集计划。STANDARD 使用本批次实际取得的来源，不会因取数时选择附表而补采；本参数也不会触发报告生成或付费工商司法查询。接口返回成功表示所请求的加工已就绪，不代表税局数据采集完整；空数组需结合 selection.collection 等覆盖证据判断。
发票期间
| 代码 | 范围 |
|---|---|
CURRENT_YEAR_PLUS_4 | 本年度及往前 4 个完整年度 |
CURRENT_YEAR_PLUS_3 | 本年度及往前 3 个完整年度 |
CURRENT_YEAR_PLUS_2（默认） | 本年度及往前 2 个完整年度 |
LAST_36_MONTHS | 近 36 个月 |
LAST_24_MONTHS | 近 24 个月 |
API 1.5.128 的渠道期限规则： 后台「客户系统对接 → 对应渠道 → 业务设置 → 发票采集期限」可固定五种期限之一，固定设置优先于请求参数；默认跟随客户传参。修改设置只影响该渠道新创建的订单；同订单重复请求、链接续期及失败重试沿用原期限与日期。生产与测试均已覆盖该规则，版本见环境与凭据。
响应里会带上解析后的 invoice_start_date 与 invoice_end_date，便于核对实际区间。
输出类型
tax_data_types 与 invoice_data_types 各自接受 WORKER_RAW、ALL、STANDARD 的任意非空组合（最多三项）。平台只交付已选择的结果。
json
{
"tax_data_types": ["ALL", "STANDARD"],
"invoice_data_types": ["ALL", "STANDARD", "WORKER_RAW"]
}| 取值 | 产出 |
|---|---|
ALL | 税局原始/映射数据 |
STANDARD | 平台加工后的标准化结构 |
WORKER_RAW | Worker 采集到的原始表格文件（通常 XLSX） |
省略时的兼容行为：tax_data_types 省略 → 兼容 ALL 与 STANDARD； invoice_data_types 省略 → 仅允许 ALL。
范围不可后补
取数阶段不能扩大范围。未选择 ALL 或 STANDARD 时，对应数据接口直接返回 业务码 10001；未选择 WORKER_RAW 的产品不会给出原始文件下载地址。
STANDARD 没有模块筛选
选择 STANDARD 后，税务按当前环境字段字典返回业务模块；发票返回完整 13 个模块。 客户端无需新增模块选择参数，具体返回范围与空值规则见税务说明和发票说明。 历史的模块筛选字段（tax_standard_modules、invoice_standard_modules 等） 仍会被接收但直接忽略，新接入不应继续发送。
发票交付方式
新建授权或订单时，invoice_delivery_mode 省略即使用 PACKAGE 分片包，后台新建订单也默认选中分片包；仍可手动选择游标或普通接口。
| 取值 | 取数方式 |
|---|---|
PACKAGE（默认） | V2 分片包状态 → 清单 → 逐片下载，同时支持游标 |
CURSOR | V2 游标接口续拉 |
LEGACY | 普通接口 /api/channel/data/invoice/all，按页码读取 |
该参数只影响发票 ALL 的交付准备，不改变 Worker 原始文件与 STANDARD 的授权范围。collect_invoice=false 且省略交付方式时归一为 LEGACY；显式选择 CURSOR 或 PACKAGE 仍要求采集发票。只选择发票 STANDARD 时，仍按 STANDARD 接口取数，不会额外申请 ALL。
已有订单继续使用创建时保存的方式；省略交付方式重复创建同一业务订单、续期和重试不会改成新的默认值，显式传入的方式仍按订单参数一致性规则校验。普通接口按 pageNum、pageSize 取数的能力保留。
详见发票完整数据交付。
报告
| 字段 | 说明 |
|---|---|
pdf_report_types | 报告选择参数；订单查询的 pdfReports 提供同源 HTML 与 PDF 的状态和下载链接 |
generate_html_reports | 是否生成两份 HTML 在线版报告，默认 false |
generate_html_reports 只控制详版、简版在线 HTML，单独开启不会生成 PDF。申请详版、简版或租赁 PDF 会生成同源 HTML 文件，但不会开启对应在线分享页；TAX_RISK 例外，它同时申请财税风险报告的 PDF、HTML 在线页和完成页二维码。 两者都要求同时采集税务和发票。
pdf_report_types 可选值：
| 编码 | 含义 | 是否需要后台授权 |
|---|---|---|
TAX_INVOICE_DETAIL | 税票 PDF（详版） | 否 |
TAX_INVOICE_SUMMARY | 税票 PDF（简版） | 否 |
TAX_RISK | 财税风险报告（PDF、在线 HTML 与二维码） | 否 |
LEASING_CREDIT_CUSTOM | 唯一 R31 租赁机构信贷报告 | 是 |
租赁报告为什么只有一个编码
报告采用「后台授权 + 订单选择」两层控制。租赁报告只有唯一 R31 版本；渠道获授权后， 在本单传入 LEASING_CREDIT_CUSTOM，系统生成同源 HTML 与 PDF。
后台已授权但本单未传入时不会生成；当前渠道未获授权却传入该编码时， 接口返回 403 REPORT_NOT_ENTITLED。
回调与返回地址
| 字段 | 说明 |
|---|---|
callback_url | 平台向客户服务端推送结果的地址 |
callback_mode | AGGREGATE（默认，整单一次）或 PER_PRODUCT（按产品分别通知） |
success_url | 用户授权完成后返回的浏览器页面 |
exit_url | 用户取消、主动结束或授权失败后返回的浏览器页面 |
success_url、exit_url 默认须为通过平台安全校验的完整公网 HTTPS 地址；平台已为渠道开启「非 HTTPS 跳转」时，可使用公网 HTTP 或安全的 App 自定义协议。该渠道开关不改变回调规则：callback_url 默认须为公网 HTTPS，只有平台超级管理员为所属客户机构开启独立的 HTTP 回调例外后才可使用公网 HTTP。三个地址省略时均使用渠道默认配置。success_url、exit_url 支持前端路由片段（如 https://example.com/#/result）；服务端回调地址 callback_url 不支持 # 片段。
回调模式如何影响通知
无论选择哪种模式，授权阶段都会发送一次 authorization.completed 或 authorization.failed。两种模式的差异只在采集结果阶段：
callback_mode | 采集结果通知 | 适用场景 |
|---|---|---|
AGGREGATE（默认） | 整单终态时发送一次 order.completed 或 order.failed | 接收端只关心整单是否结束，或需要兼容既有接入 |
PER_PRODUCT | 按本单选择的税务、发票和 PDF 产品分别发送 collection.<product>.* | 接收端需要分产品保存结果或分别触发后续流程 |
创建授权接口只负责确定“回调发到哪里、按什么粒度发送”；请求头、完整报文、 数字字段含义、验签、重试和幂等规则属于回调接收协议。尤其需要注意： notifyType、status、dataType 是兼容数字枚举，不是通知序号，详见 回调通知的数字字段对照。
其他常用字段
| 字段 | 默认 | 说明 |
|---|---|---|
output_encryption | NONE | SM4 时成功 JSON 报文替换为 SM4-GCM 信封，见输出加密 |
data_retention_days | 渠道默认（初始 30） | 业务资料保留期，7–365 天 |
public_result_access_days | 渠道默认（初始 7） | 结果页及报告分享期，1–30 天，不得超过资料保留期 |
expires_in_seconds | 渠道默认（初始 1800） | 首次提交授权有效期，60–1296000 秒（最长 15 天，单位仍为秒）；已提交的采集继续执行 |
extras_data | {} | 客户扩展对象；回调以 extrasData JSON 字符串返回 |
tax_url | 自动解析 | 一般不传；平台按纳税人识别号解析归属地区 |
replace_authorization_code | 不替换 | 显式替换本渠道、同一纳税人的当前有效待授权链接；仅在确认替换后提交 |
期限的继承、截止时间、历史订单和短期下载地址见授权、分享与资料期限。
已废弃与兼容字段
| 字段 | 现状 |
|---|---|
data_delivery_mode | 旧客户端兼容。新接入请在输出类型数组中选择 WORKER_RAW |
support_long_auth | 仅兼容旧客户端，始终按 false 处理 |
need_verify_code | 已废弃，直接丢弃 |
tax_standard_modules / invoice_standard_modules | 被接收但忽略，也不参与重复请求的比对 |
请按接口参考中的字段名发送。只有明确声明别名的参数接受两种写法，如 output_encryption / outputEncryption、additional_tables / additionalTables；不要自行把 external_order_id、enterprise_name、taxpayer_id 等字段改为驼峰。
成功响应
以下展示显式选择近 36 个月、在线 HTML 和 SM4 的结构；具体期间、加密和报告开关以创建请求及渠道设置为准，不是上方最小请求的默认结果。
json
{
"authorization_code": "550e8400-e29b-41d4-a716-446655440000",
"authorization_url": "https://rpa-auth.xiaowu005.xyz/user/authorization/taxXyd?...",
"external_order_id": "BANK-20260812-0001",
"invoice_period": "LAST_36_MONTHS",
"invoice_start_date": "2023-08-12",
"invoice_end_date": "2026-08-12",
"expires_at": "2026-08-12 18:30:00",
"dataDeliveryMode": "STRUCTURED",
"generateHtmlReports": true,
"outputEncryption": "SM4"
}expires_at 固定按北京时间（UTC+8）返回，格式为 YYYY-MM-DD HH:mm:ss。
必须直接跳转
客户前端必须直接打开 authorization_url，不得自行拼接授权页面地址。
重复提交的处理规则
同一渠道内 external_order_id 唯一，平台靠它判断「这是不是同一笔业务」。 这种设计的术语叫幂等：同一笔请求不管发多少遍，效果都只算一次， 所以网络超时后放心重发即可，不会创建出重复的授权。具体规则：
- 请求体完全相同时，重发是安全的：平台不会重复创建，直接返回同一个授权。
- 订单号相同但规范化后的业务参数变了 —— 企业、税号、
extras_data、回调/返回地址、回调模式、 采集范围、输出类型、output_encryption、generate_html_reports、PDF 报告选择、 附表选择、分享有效期、数据保留期、发票交付模式或发票期间任一不同 —— 平台无法判断该以哪一版为准，返回409 EXTERNAL_ORDER_CONFLICT。 - 链接未提交且已过期后，可以用同一个
external_order_id重新创建一笔新授权。
旧版模块筛选字段被忽略，不参与上述比对。
expires_in_seconds 不参与已有授权的冲突比对，也不能靠重复创建延长当前链接；重新生成到期链接时沿用原授权时长。省略的返回地址仍按当前渠道默认值解析，渠道改过默认地址后重放旧请求，可能因地址不同而冲突。
同渠道、同企业使用不同的 external_order_id 创建订单时，各订单生成独立授权链接；同订单号重复请求仍保持幂等。 确需替换已有待授权链接时，在新请求中显式传入 replace_authorization_code。 新链接创建成功后旧链接失效，不能把该参数作为遇到冲突就自动重试的默认行为。
未提交授权到期
1.5.20 中，新授权到期且尚未创建或复用采集任务时，订单查询返回 state=ERROR， 并附 processCode=AUTHORIZATION_EXPIRED、errorCode=AUTHORIZATION_EXPIRED 和 reason。 未提交授权到期不创建采集任务，也不新增过期回调。
重新创建后沿用客户订单号，但返回新的授权码、链接和到期时间，客户端必须使用最新链接。 旧链接不可继续提交：过期链接返回 HTTP 410，已换代链接返回 AUTHORIZATION_SUPERSEDED。 已经成功提交、取消或被替代的授权不参与未提交授权的到期处理；升级前历史状态不批量回填。
近期成功结果复用
平台启用结果复用后，可按渠道配置 1–365 天的复用窗口。新授权链接打开时，如果同一渠道、同一纳税人在窗口内有仍处于保留期的成功快照，且覆盖本单需要的产品、发票起止日期、税务附表及地区要求，页面可以提示使用已有采集结果。
平台还会检查当前批次证据和质量。要求完整核验的渠道不能复用均衡核验采集的发票快照。输出类型、报告选择、分享及保留天数不要求与源订单逐项相同，本单仍按自己的授权选择加工和交付，并采用独立的访问期限。
是否可复用以授权页实际提示为准；正在采集的企业可能先进入等待，不能把窗口内存在历史订单等同于必定复用。收入核验不通过等明确要求重新采集的恢复流程不会复用原结果。
常见错误
| HTTP | code | 处理 |
|---|---|---|
| 401 | CHANNEL_AUTH_REQUIRED / INVALID_CHANNEL_KEY | 核对 X-Channel-Key 与环境 |
| 403 | REPORT_NOT_ENTITLED | 渠道未获 R31 租赁报告授权，去掉 LEASING_CREDIT_CUSTOM 或联系平台授权 |
| 409 | EXTERNAL_ORDER_CONFLICT | 换新订单号，或改回与首次完全一致的请求体 |
| 409 | AUTHORIZATION_CANCELLED | 当前授权已取消，不能用同一请求恢复 |
| 409 | TAX_ALL_SELECTION_DISABLED | 目标环境未开启税务 ALL 附表选择，联系平台确认或移除非空附表参数 |
| 409 | AUTHORIZATION_REPLACEMENT_INVALID | 待替换授权不属于本渠道、企业或当前订单，核对授权码 |
| 409 | AUTHORIZATION_REPLACEMENT_CONFLICT | 已发生替换，查询当前有效授权 |
| 409 | AUTHORIZATION_REPLACEMENT_NOT_PENDING | 原授权已过期或已提交，不再适用待授权替换 |
| 409 | TAX_URL_MISSING | 该纳税人所在地区尚未配置税局入口，联系平台 |
| 422 | VALIDATION_ERROR | 读 details.errors 定位字段 |
| 422 | INVALID_CALLBACK_URL | 地址未通过安全校验 |