信封签署 (eSign)接口列表批量查询文件转换任务

批量查询文件转换任务

POST/openapi/v1/files/convert-tasks/query

批量查询转换任务的当前状态，用于轮询直到终态（success / failed / timeout）。

轮询建议：每 1~2 秒查询一次，绝大多数任务在 10 秒内进入终态。

权限：仅返回属于当前空间的任务；不属于本空间的 TaskId 会被静默过滤，不会出现在 Tasks 数组中，也不会因此报错。

TaskStatus 枚举：

值含义是否终态
pending任务已提交，等待处理否，继续轮询
processing转换进行中否，继续轮询
success转换成功，ConvertedFileId 可用是
failed转换失败，TaskMessage 含失败原因是
timeout转换超时是

请求参数

Header 参数
Authorization必填string
Bearer <access_token>
X-Operator-User-Id选填string
操作用户 ID。授权码模式下无需传（自动使用授权用户）；客户端凭据模式下可选，不填时使用系统用户 ID。
Body 请求体
application/json
TaskIds必填array<string>
任务 ID 列表（必填），单次最多 50 个

请求示例

{
  "TaskIds": [
    "20260709175117139808",
    "20260709175117139809"
  ]
}

响应参数

Response.Data
Tasks选填array<object>
任务结果列表；越权 TaskId 静默过滤，不出现在此数组内
⌃子属性
TaskId选填string
任务 ID
TaskStatus选填string
任务状态：pending=已提交等待处理；processing=转换中；success=转换成功；failed=转换失败；timeout=转换超时
pendingprocessingsuccessfailedtimeout
ConvertedFileId选填string
转换后 PDF 的 FileId，仅 TaskStatus=success 时非空。可直接用于 QuickCreateEnvelope 的 Documents[].FileId
TaskMessage选填string
任务描述文本（成功 / 失败的简要说明），可能为空

响应示例

{
  "Response": {
    "RequestId": "req-abc123",
    "Error": null,
    "Data": {
      "Tasks": [
        {
          "TaskId": "20260709175117139808",
          "TaskStatus": "success",
          "ConvertedFileId": "SGf1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6",
          "TaskMessage": ""
        },
        {
          "TaskId": "20260709175117139809",
          "TaskStatus": "processing",
          "ConvertedFileId": "",
          "TaskMessage": ""
        }
      ]
    }
  }
}

错误码

错误码说明
INVALID_REQUEST请求参数错误（TaskIds 为空、数量超过 50 等）
OPENAPI.OPERATOR_USER_NOT_FOUND传入的 X-Operator-User-Id 不是该空间的成员
INTERNAL_ERROR服务内部错误
创建文件转换任务快速发起信封