主题
创建授权
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_4、 保留期 30 天、链接有效期 1800 秒、不加密、不生成报告。
必填字段
| 字段 | 说明 |
|---|---|
external_order_id | 客户业务订单号，同时是本接口的幂等键，同一渠道内唯一，最长 128 字符 |
enterprise_name | 企业名称，最长 256 字符 |
taxpayer_id | 统一社会信用代码 / 纳税人识别号，3–64 字符 |
采集范围
| 字段 | 默认 | 说明 |
|---|---|---|
collect_tax | true | 是否采集税务 |
collect_invoice | true | 是否采集发票 |
invoice_period | CURRENT_YEAR_PLUS_4 | 发票采集期间 |
collect_tax 与 collect_invoice 至少一项为 true。
发票期间
| 代码 | 范围 |
|---|---|
CURRENT_YEAR_PLUS_4 | 本年度及往前 4 个完整年度 |
CURRENT_YEAR_PLUS_3 | 本年度及往前 3 个完整年度 |
CURRENT_YEAR_PLUS_2 | 本年度及往前 2 个完整年度 |
LAST_36_MONTHS | 近 36 个月 |
LAST_24_MONTHS | 近 24 个月 |
响应会回显解析后的 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 后，税务固定返回完整 24 个模块，发票固定返回完整 13 个模块。 历史的模块筛选字段（tax_standard_modules、invoice_standard_modules 等） 仍会被接收但直接忽略，新接入不应继续发送。
发票交付方式
invoice_delivery_mode 只影响发票 ALL，不影响 Worker 原始文件与 STANDARD。
| 取值 | 适用 | 取数方式 |
|---|---|---|
LEGACY（默认） | 小批量 | /api/channel/data/invoice/all 分页 |
CURSOR | 边拉边处理 | V2 游标接口续拉 |
PACKAGE | 大批量离线 | V2 分片包状态 → 清单 → 逐片下载 |
详见大批量发票交付。需要 collect_invoice=true。
报告
| 字段 | 说明 |
|---|---|
pdf_report_types | 唯一的 PDF 选择参数；可下载 PDF |
generate_html_reports | 是否生成两份 HTML 在线版报告，默认 false |
两者相互独立：只开 HTML 不会隐式生成 PDF，只申请 PDF 也不会隐式生成 HTML。 两者都要求同时采集税务和发票。
pdf_report_types 可选值：
| 编码 | 含义 | 是否需要后台授权 |
|---|---|---|
TAX_INVOICE_DETAIL | 税票 PDF（详版） | 否 |
TAX_INVOICE_SUMMARY | 税票 PDF（简版） | 否 |
LEASING_CREDIT_CUSTOM | 定制版统一开关 | 是 |
定制报告为什么只有一个编码
PDF 报告采用「后台配置 + 订单选择」两层控制。平台可为渠道配置一个或多个具体定制报告， 客户无需知道这些内部名称和版本，只需在本单传入统一编码 LEASING_CREDIT_CUSTOM， 平台就会生成为当前渠道配置的全部有效定制报告。
后台已配置但本单未传入时不会生成；当前渠道没有任何有效定制报告却传入该编码时， 接口返回 403 REPORT_NOT_ENTITLED。
回调与返回地址
| 字段 | 说明 |
|---|---|
callback_url | 平台向客户服务端推送结果的地址 |
callback_mode | AGGREGATE（默认，整单一次）或 PER_PRODUCT（按产品分别通知） |
success_url | 用户授权完成后返回的浏览器页面 |
exit_url | 用户取消、主动结束或授权失败后返回的浏览器页面 |
三个地址均须为通过平台安全校验的完整公网 HTTPS 地址；省略时使用渠道默认配置。 详见回调通知。
其他常用字段
| 字段 | 默认 | 说明 |
|---|---|---|
output_encryption | NONE | SM4 时成功 JSON 报文替换为 SM4-GCM 信封，见输出加密 |
data_retention_days | 30 | 本订单数据保留期，7–365 天，推荐 7 / 30 / 90 / 180 / 365 |
expires_in_seconds | 1800 | 授权链接有效期，60–86400 秒 |
extras_data | {} | 客户扩展信息，回调时原样返回 |
tax_url | 自动解析 | 一般不传；平台按纳税人识别号解析归属地区 |
已废弃与兼容字段
| 字段 | 现状 |
|---|---|
data_delivery_mode | 旧客户端兼容。新接入请在输出类型数组中选择 WORKER_RAW |
support_long_auth | 仅兼容旧客户端，始终归一化为 false |
need_verify_code | 已废弃，直接丢弃 |
tax_standard_modules / invoice_standard_modules | 被接收但忽略，不参与幂等比较 |
所有字段同时接受下划线与驼峰两种写法（如 output_encryption / outputEncryption）。
成功响应
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-12T10:30:00Z",
"dataDeliveryMode": "STRUCTURED",
"generateHtmlReports": true,
"outputEncryption": "SM4"
}必须直接跳转
客户前端必须直接打开 authorization_url，不得自行拼接授权页面地址。
幂等规则
同一渠道内 external_order_id 唯一。
- 完全相同的活动请求可以安全重试，返回同一个授权。
- 企业、税号、
extras_data、回调/返回地址、回调模式、采集范围、输出类型、output_encryption、generate_html_reports、PDF 报告选择、数据保留期、 发票交付模式或发票期间任一发生变化 →409 EXTERNAL_ORDER_CONFLICT。 - 链接未提交且已过期后，可用同一
external_order_id创建新的授权代次。
旧版模块筛选字段被忽略，不参与幂等比较。
近期成功结果复用
平台可按渠道配置 1–365 天的成功落库复用窗口。新授权链接打开时， 如果同一渠道、同一纳税人识别号在窗口内存在已成功完成且以下要素完全一致的任务， 授权页面会提示用户是否直接使用已有结果：
采集范围、发票期间、WORKER_RAW/ALL/STANDARD 选择、PDF 报告、 HTML 在线报告开关、数据保留期、发票交付模式。
旧版模块筛选字段不参与复用指纹。
常见错误
| HTTP | code | 处理 |
|---|---|---|
| 401 | CHANNEL_AUTH_REQUIRED / INVALID_CHANNEL_KEY | 核对 X-Channel-Key 与环境 |
| 403 | REPORT_NOT_ENTITLED | 渠道未配置任何有效定制报告，去掉 LEASING_CREDIT_CUSTOM |
| 409 | EXTERNAL_ORDER_CONFLICT | 换新订单号，或改回与首次完全一致的请求体 |
| 409 | TAX_URL_MISSING | 该纳税人所在地区尚未配置税局入口，联系平台 |
| 422 | VALIDATION_ERROR | 读 details.errors 定位字段 |
| 422 | INVALID_CALLBACK_URL | 地址未通过安全校验 |