等待结果

采集是异步的。平台会主动回调通知结果；本页的两个查询接口是兜底手段，用于回调丢失、客户端重启补偿或人工排查。

轮询间隔

查询间隔不得低于 15 秒，建议 15–30 秒。不要用页面进度百分比作为业务判断依据。

订单查询

GET /api/v1/channel/orders/{external_order_id}

返回该业务订单最新授权代次的整体状态。

bash

curl -sS "$RPA_BASE_URL/api/v1/channel/orders/BANK-20260812-0001" \
  -H "X-Channel-Key: $RPA_CHANNEL_KEY"

状态机

`state`	含义	是否结束
`CONNECT`	等待用户提交授权	否
`PROCESS`	排队、采集、校验或上传中	否
`INTERACTION`	等待短信或图形验证码	否
`SUCCESS`	采集完成	是
`ERROR`	最终失败	是

1.5.3 的 SUCCESS 可能带质量警告

税务某个非阻断子项目超时、来源不足或记录不完整时，平台会保留已取得的数据继续处理。订单仍可为 SUCCESS，同时返回 qualityStatus=WARNING、 collectionResult=COMPLETED_WITH_WARNINGS。因此还要读取 dataQuality 和 qualityIssues，不能把 SUCCESS 直接解释成“所有来源都完整”。

四个编号

响应里有四个标识，作用各不相同，落库时建议全部保存：

字段	作用
`external_order_id`	客户业务订单号
`authorization_code`	当前授权记录标识。只有创建新授权代次时才变化；1.5.3 的原链接重新录入凭据会沿用它
`job_id`	采集任务标识。这就是数据接口里的 `orderNo`
`attempt_id`	当前采集尝试。平台系统重试或原授权页重新录入凭据后会变化，`job_id` 不变

用 attempt_id 区分两类重试

job_id 不变、attempt_id 变化 = 同一任务进入新的执行尝试，客户端继续跟踪即可。 authorization_code 变化 = 平台创建了新的授权代次；不要仅凭是否需要用户重新录入凭据来推断它一定变化。

响应示例

json

{
  "external_order_id": "BANK-20260812-0001",
  "authorization_code": "550e8400-e29b-41d4-a716-446655440000",
  "job_id": "1e3f2f55-8da4-4ba9-b941-84860eb1d243",
  "attempt_id": "a2ad4ec4-b878-42c5-b623-4d962f350e72",
  "state": "SUCCESS",
  "dataDeliveryMode": "STRUCTURED",
  "invoice_period": "LAST_36_MONTHS",
  "invoice_period_label": "近36个月",
  "invoice_start_date": "2023-08-12",
  "invoice_end_date": "2026-08-12",
  "result": {},
  "qualityStatus": "PASSED",
  "qualityIssues": [],
  "collectionResult": "COMPLETED",
  "dataQuality": {},
  "artifacts": [],
  "updated_at": "2026-08-12T10:41:07+00:00"
}

质量字段

字段	常见值	处理方式
`qualityStatus`	`PASSED` / `WARNING` / `UNVERIFIED`	作为整体质量结论保存
`collectionResult`	`COMPLETED` / `COMPLETED_WITH_WARNINGS`	后者表示已有数据可用，但存在非阻断问题
`qualityIssues`	问题对象数组	保存问题代码、严重度及可重试提示
`dataQuality`	覆盖率、`partial`、`usable`、问题与隔离制品	用于判断具体缺失范围，不要只看顶层状态

1.5.3 取消税务子项目的本地硬超时和整轮重跑；单次税局请求超时会记录该项目未取得，继续处理其他项目。只有活动采集页真实跳回税局登录路由时，才会终止当前 attempt 并要求在原授权页重新录入凭据。

开启 HTML 报告时，响应会增量包含 htmlReports；选择 WORKER_RAW 时，artifacts 会列出原始文件及其 downloadUrl。

订单不存在时返回 404 CHANNEL_ORDER_NOT_FOUND。

产品查询

GET /api/v1/channel/orders/{external_order_id}/products/{product}

product 只允许 TAX 或 INVOICE。按产品粒度返回采集状态、数据集清单与质量信息。

bash

curl -sS "$RPA_BASE_URL/api/v1/channel/orders/BANK-20260812-0001/products/INVOICE" \
  -H "X-Channel-Key: $RPA_CHANNEL_KEY"

取数前提

两个条件缺一不可

state == "SUCCEEDED"  &&  available == true

只满足其一都不能取数。

这两个条件表示产品结果可以交付。若 qualityStatus=WARNING 或 collectionResult=COMPLETED_WITH_WARNINGS，仍需把质量明细与业务数据一起落库，由下游按可接受的覆盖范围决定是否继续。

`state`	含义	是否终态
`PENDING`	尚未产生终态（排队中或采集中）	否
`SUCCEEDED`	该产品采集完成	是
`FAILED`	该产品最终失败	是
`SKIPPED`	本单未执行该产品	是

retryable 说明该失败是否可由平台自动重试； error_code / error_message 给出失败原因。

响应示例

json

{
  "external_order_id": "BANK-20260812-0001",
  "authorization_code": "550e8400-e29b-41d4-a716-446655440000",
  "job_id": "1e3f2f55-8da4-4ba9-b941-84860eb1d243",
  "attempt_id": "a2ad4ec4-b878-42c5-b623-4d962f350e72",
  "product": "INVOICE",
  "state": "SUCCEEDED",
  "available": true,
  "dataset_count": 4,
  "record_count": 2841,
  "qualityStatus": "PASSED",
  "qualityIssues": [],
  "datasets": [
    { "id": "ds-0001", "name": "发票基础信息", "product": "invoice", "row_count": 1204 }
  ],
  "artifacts": [],
  "error_code": null,
  "error_message": null,
  "retryable": false,
  "available_at": "2026-08-12T10:41:07Z"
}

常见错误

HTTP	code	含义
404	`CHANNEL_ORDER_NOT_FOUND`	订单不存在
404	`PRODUCT_NOT_REQUESTED`	本单未申请该产品
422	`INVALID_PRODUCT`	`product` 不是 `TAX` / `INVOICE`

PDF 状态不在这里

PDF 报告状态不通过产品接口查询，应调用 POST /api/channel/data/reports/status，见 PDF 与 HTML 报告。

等待结果 ​

订单查询 ​

状态机 ​

四个编号 ​

响应示例 ​

质量字段 ​

产品查询 ​

取数前提 ​

响应示例 ​

常见错误 ​

推荐的等待策略 ​

等待结果

订单查询

状态机

四个编号

响应示例

质量字段

产品查询

取数前提

响应示例

常见错误

推荐的等待策略