授权、分享与资料期限

本文对应 各环境字段契约，授权提交有效期上限为 15 天。各环境部署信息见环境范围。

新订单有三项独立期限。创建授权时可按订单设置，省略时继承渠道默认值；订单创建后修改渠道配置不会改变原订单期限。

设置	创建授权参数	渠道初始默认值	范围与作用
授权提交有效期	expires_in_seconds	1800 秒	60–1296000 秒（最长 15 天），仅限制首次提交授权；已提交的采集继续执行
结果页及报告分享有效期	public_result_access_days	7 天	1–30 天，控制公共结果页、在线报告和二维码；不能超过资料保留期
业务资料保留期	data_retention_days	30 天	7–365 天，控制原始文件、采集资料、PDF、HTML 的读取和清理

单位与 15 天设置

接口参数 expires_in_seconds 仍以秒为单位，必须传整数；15 天填写 1296000（15 × 24 × 60 × 60）。后台表单以分钟填写，15 天对应 21600 分钟。不要把 15 或 21600 当作 15 天传给接口。

初始默认仍为 1800 秒（30 分钟）。已有链接不会因文档或平台升级自动延长。超过 1296000 秒返回 HTTP 422（VALIDATION_ERROR）。过期重发支持保留原授权时长，上限同为 15 天。

创建与重复请求

{
  "external_order_id": "CUSTOMER-20260908-001",
  "enterprise_name": "示例企业",
  "taxpayer_id": "91420100XXXXXXXXXX",
  "expires_in_seconds": 1296000,
  "public_result_access_days": 7,
  "data_retention_days": 30
}

同时接受 expiresInSeconds、publicResultAccessDays、dataRetentionDays 的驼峰写法。显式提交不合法组合返回 422 INVALID_ACCESS_LIFETIME。

旧客户端只设置较短资料保留期而省略分享天数时，平台自动取渠道默认分享天数与资料保留天数的较小值。

同一订单号重放原请求会保留原订单期限，不因渠道默认值改变而延期。显式修改已有订单的分享或保留策略返回 409 EXTERNAL_ORDER_CONFLICT。查询、刷新、下载和重新签发下载地址均不延长订单期限。

截止时间与订单查询

成功订单在所需交付内容就绪、履约完成后开始计算资料保留期。分享期限在报告处理结束后确定，且不超过资料截止时间。失败订单依据任务完成时间和已有报告完成时间确定期限。复用原始数据的订单拥有自己的期限。

GET /api/v1/channel/orders/{external_order_id} 返回以下字段：

字段	含义
authorizationExpiresAt	首次提交授权的截止时间
publicResultAccessDays	本订单采用的分享有效天数
publicAccessExpiresAt	公共结果页、在线报告、二维码的访问截止时间
dataRetentionDays	本订单采用的资料保留天数
dataAccessExpiresAt	业务资料读取、下载截止时间

这些截止时间统一使用北京时间（UTC+8），格式为 YYYY-MM-DD HH:mm:ss，例如 2026-09-08 18:30:00，不带 T、Z 或小数秒。授权创建响应的 expires_at、报告分享的 expiresAt、文件的 downloadExpiresAt 和 dataExpiresAt 同样按此格式返回。客户端必须明确按 UTC+8 解析；URL 的 expires 和请求签名时间戳仍为 Unix 秒。其他时间字段按各自契约解析。

尚未交付或报告尚未就绪时，publicAccessExpiresAt、dataAccessExpiresAt 可为 null；历史订单未设置统一截止时间时也为 null，不代表永久可访问。

资料到期后返回 410 ORDER_DATA_ACCESS_EXPIRED，错误响应的 details 仍包含上述五个字段。启用 SM4 的成功订单响应继续在原有密文信封中提供期限信息。

分享地址与下载地址

使用场景	使用的返回值	到期处理
在线 HTML 和二维码	htmlReports.reports[].accessUrl，分享截止为 expiresAt	分享到期返回 410，查询不会续期
PDF 及同源 HTML 文件	pdfReports.reports[].downloadUrl / pdfDownloadUrl / htmlDownloadUrl	短期签名到期后，鉴权查询订单获取新地址
独立在线报告的 HTML 文件	htmlReports.reports[].downloadUrl	分享已到期但资料仍在保留期内时，仍可通过鉴权订单查询获取下载地址
Worker 原始文件	artifacts[].downloadUrl	短期签名到期后，鉴权查询订单获取新地址

以上文件签名地址最长有效 15 分钟，且不超过资料截止时间；部分文件类型可由平台配置缩短。客户不能设置单次下载地址的有效期。文件项返回 downloadExpiresAt（本次地址截止）和 dataExpiresAt（资料截止）。

直接使用完整的下载地址，无需渠道请求头。原始文件地址中的 authorization_id、expires、signature 必须完整保留。旧的不带签名原始文件地址仍需 X-Channel-Key；存在无效或不完整签名参数时返回 403，不回退到 Key 鉴权。

独立 HTML 文件通过 GET /api/v1/public/html-reports/downloads/{report_id} 下载，地址带 expires 和 signature。订单查询须先通过渠道鉴权才返回该地址，公共结果页仅提供分享地址。

单次签名过期返回 403；资料到期或权限撤销返回 410。公共结果页分享到期返回 410 PUBLIC_RESULT_ACCESS_EXPIRED，在线 HTML 分享到期返回 410 HTML_REPORT_EXPIRED。分享到期不提前删除仍在资料保留期内的 HTML 文件。

历史订单与资料清理

升级前订单保留旧策略，不回填新截止时间。历史 HTML 保留原有七天规则，已有二维码不重签；历史 PDF 不因升级突然纳入删除。旧订单的原始文件仍适用原有保留和访问规则。

新策略订单到达资料截止时间立即停止读取，文件清理按后台任务周期执行；不能因为文件尚未删除就继续访问。共用原始文件的多个订单分别校验自己的期限，等所有有效引用到期后才清理物理文件。

如需长期留存，应在资料保留期内下载、校验并保存到自己的存储。已下载的副本不受平台链接期限控制。