等待结果

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

轮询间隔

查询间隔不得低于 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`	授权、采集、结果生成或订单核验失败，或已取消、未提交授权已过期	是；恢复方式需按原因判断

SUCCESS 可能带质量警告

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

授权端的进度提示

“授权成功”表示身份验证完成，采集和结果准备可能仍在进行。页面显示部分完成或待核验时，应查看质量说明；报告生成中则等待报告自身状态结束。

“取消处理中”表示取消请求已提交，仍须等待执行节点确认。只有返回最终取消或失败状态，才表示本轮已经结束；终态不能继续解释为等待授权或普通采集进度。恢复或重新授权按页面的具体操作提示执行。

客户提示

从 API 1.5.169 起，订单查询统一补齐以下提示。

订单查询复用现有三个展示字段，覆盖授权、排队、验证、采集、核验、报告、取消和过期。三个字段只用于展示；程序继续根据原有 state、processCode、errorCode、recoveryAction 和报告状态判断业务结果。

字段	含义
`customerTitle`	当前最需要关注的情况，例如“收入交叉核验未通过”“报告生成中”“订单已取消”
`customerMessage`	具体原因或进度；收入核验保留实际比较期间、金额和差异率
`customerGuidance`	下一步操作；无需客户操作时为 `null`

提示按当前授权代次及执行批次生成。多个问题由主提示概括，完整明细继续读取 qualityIssues、dataQuality、collectionPresentation、revenueCheck、pdfReports 和 htmlReports。采集完成、核验结果和报告就绪分别判断；未生成完全部所选报告时不提示“数据和报告已就绪”。内部诊断文字不复制到这三个展示字段，客户页面不应直接展示原始 reason。

未提交授权的取消、过期仍按原规则返回订单状态；已经撤销资料权限或超过资料保留期时，继续返回 HTTP 410，原 code、message 和期限字段不变，在 details 内补充同名三个提示字段，不返回资料或下载地址。例如：

json

{
  "code": "ORDER_DATA_ACCESS_REVOKED",
  "message": "Order data access was revoked",
  "details": {
    "customerTitle": "订单已取消",
    "customerMessage": "本次订单已终止，不会继续采集。",
    "customerGuidance": null
  }
}

示例省略了原有期限字段。HTTP 200 时从响应顶层读取提示；SM4 订单先按原协议解密，再读取提示。HTTP 410 时从 details 读取提示。401、403、404 保持原有处理规则，不提供其他渠道订单的信息。

兼容范围：请求参数、HTTP 状态、原有业务字段与数据结构、加密信封均不变。老客户可继续使用原有接口逻辑；已经展示这三个字段的页面会获得补齐后的提示，尚未读取这些字段的页面需要增加展示代码。此次统一提示仅作用于订单查询，不改变产品查询和回调的既有返回。

四个编号

响应里有四个标识，作用各不相同，建议在自己的数据库里全部存一份：

字段	作用
`external_order_id`	客户业务订单号
`authorization_code`	当前这轮授权的编号。只有平台创建新一轮授权时才变化；通过原授权页重新录入凭据会沿用它
`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": [],
  "authorizationExpiresAt": "2026-08-12 18:30:00",
  "publicResultAccessDays": 7,
  "publicAccessExpiresAt": "2026-08-19 18:41:07",
  "dataRetentionDays": 30,
  "dataAccessExpiresAt": "2026-09-11 18:41:07",
  "updated_at": "2026-08-12T10:41:07"
}

访问期限

订单同时返回 authorizationExpiresAt、publicAccessExpiresAt、dataAccessExpiresAt 以及实际采用的分享和资料保留天数。截止时间按北京时间 YYYY-MM-DD HH:mm:ss 解析；后两项在尚未就绪或历史订单上可为 null，不代表永久可访问。

资料到期后查询返回 410 ORDER_DATA_ACCESS_EXPIRED，details 中保留这五项期限信息。完整规则见期限说明。

质量字段

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

非阻断缺口会保留已取得的数据；必需主表缺失、分页或完成清单不一致仍会阻止成功交付。税局账号锁定、会话失效和浏览器启动失败的处理不同，应按授权页与产品错误提示恢复，不要对所有失败循环提交账号密码。

授权过期与结果准备

新建且未提交的授权到期后，查询仍使用 state=ERROR，增量包含：

字段	返回值
`processCode`	`AUTHORIZATION_EXPIRED`
`errorCode`	`AUTHORIZATION_EXPIRED`
`reason`	客户可见的授权过期说明

这三个字段不保证出现在其他状态中，也没有新增过期回调。重新生成规则见未提交授权到期。采集完成后，如果本单输出仍在准备，订单继续为 PROCESS；不能仅凭 Worker 已结束就取数。

开启详版、简版在线报告，或申请 TAX_RISK 时，响应会增量包含 htmlReports；通过 pdf_report_types 申请报告时，响应会同时增量包含 pdfReports，未申请则省略该字段。选择 WORKER_RAW 时，artifacts 会列出原始文件及其 downloadUrl。

订单不存在时返回 404 CHANNEL_ORDER_NOT_FOUND。

收入交叉核验与交付失败

订单响应的 revenueCheck 是本单当前批次已保存的收入核验结果，尚无结果时为 null。渠道可由平台开启此项核验，不需要客户在授权请求中增加参数。

`revenueCheck.status`	含义
`DISABLED`	本次核验未开启
`PASSED`	已有可比较期间，差异率绝对值均低于 40%
`UNVERIFIED`	采集范围、覆盖或金额不足，无法形成可靠比较，不表示通过
`FAILED`	至少一个可比较期间的差异率绝对值达到 40%
`ERROR`	核验执行异常

比较只采用税务和发票共同覆盖的完整申报期间，按实际采集的增值税申报收入与销项发票未税净额计算；不把缺失金额填零，也不因缺少导出查询总数直接判为收入差异。rows 保留各期金额和差异，failedPeriods 列出未通过期间，jobId、attemptId 标识核验批次。

核验未通过时，订单 state=ERROR，并返回 errorCode=VAT_INVOICE_REVENUE_MISMATCH、recoveryAction=REAUTHORIZE，须按平台入口重新授权采集；核验异常为 REVENUE_CHECK_ERROR、CONTACT_SUPPORT。这两种情况不会改写已取得的采集证据，不能因单个产品仍有可用数据就把整单判为成功。

采集成功而本单必需产物最终生成失败时，订单也会为 ERROR。请保留 pdfReports 等实际结果并联系平台处理，不能对所有此类错误重新授权。processCode、errorCode、recoveryAction 仅在契约声明的具体情形返回，不是所有失败都保证带齐。

PDF 报告状态与下载

在支持 pdfReports 的部署中，一次订单查询即可同时获取在线 HTML 与可下载 PDF 报告信息：

字段	含义
`pdfReports.status`	`PENDING`、`SUCCEEDED`、`PARTIAL`、`FAILED`
`pdfReports.reports[]`	本单申请的每份报告；未生成时也会返回 `PENDING` 项
`pdfReports.reports[].status`	单份状态：`PENDING`、`QUEUED`、`RUNNING`、`SUCCEEDED`、`FAILED`
`pdfReports.reports[].downloadUrl` / `pdfDownloadUrl`	同一个 PDF 签名下载地址，生成成功后返回
`pdfReports.reports[].htmlDownloadUrl`	同源 HTML 文件的签名下载地址
`pdfReports.reports[].errorCode` / `errorMessage`	最终失败的错误信息

每份报告还包含文件名、大小、SHA-256 和 PDF 页数，完整示例见 PDF 与 HTML 报告。报告异步生成，需独立检查 pdfReports，不能仅凭订单 state 判断 PDF 已可下载。尚未完成时继续按 15–30 秒间隔查询订单；下载链接过期后也通过订单查询刷新。

旧报告状态接口计划弃用

POST /api/channel/data/reports/status 当前保留兼容，具体下线时间另行通知。目标环境支持 pdfReports 后，新接入方统一使用订单查询，已有客户端将旧响应的 data 改为读取 pdfReports。 PDF 与 HTML 文件下载接口继续保留，详见迁移说明。

产品查询

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",
  "dataDeliveryMode": "STRUCTURED",
  "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 报告状态不通过产品接口查询，应读取订单查询响应的 pdfReports，见 PDF 与 HTML 报告。

等待结果 ​

订单查询 ​

订单状态一览 ​

授权端的进度提示 ​

客户提示 ​

四个编号 ​

响应示例 ​

访问期限 ​

质量字段 ​

授权过期与结果准备 ​

收入交叉核验与交付失败 ​

PDF 报告状态与下载 ​

产品查询 ​

取数前提 ​

响应示例 ​

常见错误 ​

推荐的等待策略 ​

等待结果

订单查询

订单状态一览

授权端的进度提示

客户提示

四个编号

响应示例

访问期限

质量字段

授权过期与结果准备

收入交叉核验与交付失败

PDF 报告状态与下载

产品查询

取数前提

响应示例

常见错误

推荐的等待策略