创建预授权意愿

POST

/openapi/v3/esign/sign-grants

发起预授权签署（两步调用）的第一步：只授权、不签署具体文件。接口返回 confirmUrl，需转发给证书归属的终端用户打开，由其在云签意愿页完成核验并确认授权。确认成功后云签分配预授权额度并签发额度 Token（grantToken），第二步由调用方携该 Token 调用凭预授权 Token 签名同步取得签名值。

一步轨与两步轨并存，预授权不可用时可回落

一步轨：每次签署都通过发起签名意愿让终端用户逐次确认——既有流程保持不变。
两步轨：本接口先取得一次授权（覆盖同一签署任务后续 N 次 / T 时间内的签名），之后携 Token 免逐次确认地签名。

两条轨道长期并存。预授权不可用（未开通、已过期、次数用尽、已撤销等）时，随时可以回落一步轨逐次发起签名意愿，两者互不影响。

不兼容变更（2026-08-03）：orderNo 已更名为 signTaskId

预授权相关接口的签署任务号字段名由 orderNo 改为 signTaskId，旧字段名不再接受（缺少 signTaskId 将返回 400 esign_invalid_request）。同步影响凭预授权 Token 签名、查询预授权状态、查询意愿结果与预授权完成回调 esign:grant_ready。请在同一发布窗口完成切换。

signTaskId 是签署任务号，不是 CertCloud 订单号

本接口及凭预授权 Token 签名中的 signTaskId 是调用方业务侧的签署任务号（由调用方自行定义并保持一致），用于界定预授权额度的作用范围——同一 certId + signTaskId 至多存在一个生效中的预授权。它不是 CertCloud 的证书订单 ID（后者仍称 orderNo，见创建订单与证书签发回调 esign:cert_issued），请勿混淆。

X-ES-Request-ID 必填

本接口为幂等创建类接口，请求头必须携带 X-ES-Request-ID 作为幂等键。同一幂等键重试会复用首次发起的意愿，不会重复发起；同一幂等键携带不同的请求体重试会被上游终态拒绝（HTTP 409），须换新的 X-ES-Request-ID。

Body 参数

参数	类型	必填	说明
certId	string	是	云签证书 ID，可通过证书标识映射查询获取
signTaskId	string	是	签署任务号（调用方业务侧定义，非 CertCloud 订单号）。预授权额度按 `certId + signTaskId` 界定，同一组合至多一个生效中的预授权，重复发起会被上游拒绝
signerId	string	是	签署人 ID。预授权（两步轨）当前仅支持经办人 / 订户本人，不支持委托人代签（一步轨签名意愿可持生效授权的委托人代签，见发起签名意愿）：企业证书取证书标识映射查询响应的 `managerId`（经办人，含亲自经办的法定代表人），个人证书取 `subjectId`（订户本人）。获取方式见下方说明
willDescription	string	是	授权告知文案。预授权阶段不携带文件摘要，该文案是终端用户知情的唯一依据，会在意愿页固定句式展示并纳入存证与审计
multiGrant	boolean	否	是否多次预授权。缺省 `false` = 单次预授权（次数模式与有效期由调用方经下方参数指定，不传则取云签平台默认配置，默认 1 次 / 3 天，意愿页只读展示、不提供次数/时长输入）；`true` = 多次预授权（终端用户在意愿页自行选择次数模式并设置有效期、有限次数再填写次数，受平台硬上限约束，此时禁止传入 `grantCount` / `grantValidity` / `grantValidityUnit`）
usageLimitEnable	boolean	否	次数模式（2026-09-04 新增）。缺省 `true` = 有限次数，须固化次数上限；`false` = 不限次数，只固化有效期、签名不扣减次数。`multiGrant` 缺省 / `false` 时决定下方参数规则（见下方说明）；`multiGrant=true` 时仅作为意愿页的初始选项，最终以终端用户在页面的选择为准
grantCount	int	否	单次预授权次数，正整数。`multiGrant` 缺省 / `false` 且 `usageLimitEnable` 缺省 / `true` 时与 `grantValidity` / `grantValidityUnit` 成组传入（见下方说明）；`usageLimitEnable=false`（不限次数）时禁止传入
grantValidity	int	否	单次预授权有效期数值，正整数。与次数、单位组成不可拆分的参数组
grantValidityUnit	string	否	单次预授权有效期单位：`MINUTE` / `HOUR` / `DAY` / `MONTH` / `YEAR`。`MONTH` / `YEAR` 分别按日历月 / 日历年计算（非固定时长换算，月末自动顺延）
allowedModes	array	否	要求意愿页支持的核验方式，可选 `SMS` / `TENCENT_SMART_WITNESS` / `PIN` / `TOTP`。收紧语义：显式传入时其中每一种方式都必须对该场景与人员实际可用，任一不可用则创建失败；不传表示按实际可用方式开放。空数组非法
successRedirectUrl	string	否	意愿完成后的跳转地址（原样透传云签）
endRedirectUrl	string	否	意愿流程结束后的跳转地址（原样透传云签）

授权窗口 = 次数模式 + 有效期，参数成组不可拆（2026-08-07 新增，2026-09-04 增补不限次数）

usageLimitEnable / grantCount / grantValidity / grantValidityUnit 用于在单次预授权（multiGrant 缺省 / false）下由调用方直接指定授权窗口，规则由云签校验：

有限次数（usageLimitEnable 缺省 / true）：grantCount / grantValidity / grantValidityUnit 传入任意一个则三个必须齐全，缺一被上游终态拒绝（409）；
不限次数（usageLimitEnable=false）：grantValidity / grantValidityUnit 必填、grantCount 禁止传入（传了即 409）；不限次数仍受有效期约束，到期同样失效；
仅单次可用：multiGrant=true 时禁止携带 grantCount / grantValidity / grantValidityUnit，携带即被上游终态拒绝（409）——多次预授权的次数模式与有效期一律由终端用户在意愿页选择，此时 usageLimitEnable 只决定页面初始选项；
硬上限：有限次数的次数、以及两种模式的有效期，超过云签平台配置上限会被终态拒绝（等于上限允许）；最大次数只约束有限次数，不限次数不受其限制；
创建时固化：无论 API 指定还是取默认值，授权窗口在创建时即固化，意愿页只读展示、终端用户不可修改;
四个参数都不传时行为与旧版完全一致（有限次数、取平台默认配置），本变更向后兼容。

不限次数示例（调用方固化、1 年内不限次签署）：

json

{
  "certId": "esign-cert-xxx",
  "signTaskId": "task-20260904-001",
  "signerId": "manager-xxx",
  "willDescription": "授权本任务在 1 年内使用指定云签证书完成签署，不限次数",
  "multiGrant": false,
  "usageLimitEnable": false,
  "grantValidity": 1,
  "grantValidityUnit": "YEAR"
}

窗口来源会随存证留痕，并在查询意愿结果响应中以 source（DEFAULT / API / PORTAL）返回。

signerId 如何获取

signerId 需通过接口反查，两步获取：

用下单响应中拿到的 CertCloud 订单 ID（data.id）调用证书标识映射查询：GET /openapi/v3/esign/certs?orderId=<订单 ID>。
从响应 data 中按证书类型取字段作为 signerId：
- managerId 非空（企业证书）→ 取 managerId（经办人）
- managerId 为空（个人证书）→ 取 subjectId（订户本人）

企业证书不可用 subjectId（那是机构主体，不是自然人、不能签字）；取错字段会被云签拒绝。

响应字段

字段	类型	说明
willId	string	预授权意愿 ID，用于经查询意愿结果按 `willId` 轮询授权进度并取得 `grantId`（见下）
confirmUrl	string	转发给证书归属的终端用户打开、完成核验并确认授权的一次性链接，规则同意愿模型说明（云签域名、原样透传、请勿缓存或记录日志）
confirmUrlExpireAt	string	意愿确认链接（`confirmUrl`）的失效时间（毫秒时间戳字符串）。超过该时间后链接无法打开，请在此之前转发给终端用户完成授权
expireAt	string	意愿整体的过期时间（毫秒时间戳字符串，长整型一律字符串，见通用说明）。超过该时间后意愿转为过期终态
willStatus	string	云签侧的真实意愿状态，创建成功后通常为待确认态 `PENDING`；取值见查询意愿结果

两个过期时间不要混用

confirmUrlExpireAt 管的是链接，expireAt 管的是意愿，二者取值不同且各自独立到期。仅本接口与撤销预授权返回 confirmUrlExpireAt；其余建单类接口（发起签名意愿、凭据管理各接口等）的响应中不含该字段。

预授权生效后可经 get-will 查得 grantId，回调为加速通道

预授权意愿可以通过查询意愿结果按本接口返回的 willId 查询：businessStatus=SUCCEEDED（预授权生效）后返回 grantId 与 usageLimitEnable / usageLimit / usageRemaining / validUntil（不限次数时不含两个次数字段），不含 Token。grantId 首个入口由此是回调 + 主动查询双通道：

主动查询：经查询意愿结果按 willId 查询，生效后即可取得 grantId（见上）。
回调加速：终端用户完成预授权确认后，云签将 grantId 与 Token 一并回调交付 CertCloud、由 CertCloud 加密留存 Token，经预授权完成回调 esign:grant_ready 主动推送，无需等待轮询。

拿到 grantId 后，再经领取预授权 Token按 grantId 拉取 Token（可重复领取），携入凭预授权 Token 签名；额度实时明细以查询预授权状态为准（首次凭预授权 Token 签名的响应中同样返回 grantId）。

请求示例

bash

curl -X POST 'https://api.certcloud.cn/openapi/v3/esign/sign-grants' \
  -H 'Content-Type: application/json' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id' \
  -H 'X-ES-Request-ID: 2d7c9f4a-1b3e-4c5d-8a6f-0e9d8c7b6a5f' \
  -d '{
    "certId": "esign-cert-xxx",
    "signTaskId": "task-20260721-001",
    "signerId": "signer-xxx",
    "willDescription": "对「采购合同批量签署」任务的后续签署进行预授权",
    "multiGrant": true,
    "allowedModes": ["SMS", "PIN"]
  }'

javascript

const response = await fetch('https://api.certcloud.cn/openapi/v3/esign/sign-grants', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CC-Auth-Key': 'your-auth-key',
    'X-CC-Key-ID': 'your-key-id',
    'X-ES-Request-ID': '2d7c9f4a-1b3e-4c5d-8a6f-0e9d8c7b6a5f',
  },
  body: JSON.stringify({
    certId: 'esign-cert-xxx',
    signTaskId: 'task-20260721-001',
    signerId: 'signer-xxx',
    willDescription: '对「采购合同批量签署」任务的后续签署进行预授权',
    multiGrant: true,
    allowedModes: ['SMS', 'PIN'],
  })
})

req, _ := http.NewRequest("POST", "https://api.certcloud.cn/openapi/v3/esign/sign-grants", strings.NewReader(`{
  "certId": "esign-cert-xxx",
  "signTaskId": "task-20260721-001",
  "signerId": "signer-xxx",
  "willDescription": "对「采购合同批量签署」任务的后续签署进行预授权",
  "multiGrant": true,
  "allowedModes": ["SMS", "PIN"]
}`))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-CC-Auth-Key", "your-auth-key")
req.Header.Set("X-CC-Key-ID", "your-key-id")
req.Header.Set("X-ES-Request-ID", "2d7c9f4a-1b3e-4c5d-8a6f-0e9d8c7b6a5f")
resp, _ := http.DefaultClient.Do(req)

python

import requests

resp = requests.post(
    'https://api.certcloud.cn/openapi/v3/esign/sign-grants',
    headers={
        'X-CC-Auth-Key': 'your-auth-key',
        'X-CC-Key-ID': 'your-key-id',
        'X-ES-Request-ID': '2d7c9f4a-1b3e-4c5d-8a6f-0e9d8c7b6a5f',
    },
    json={
        'certId': 'esign-cert-xxx',
        'signTaskId': 'task-20260721-001',
        'signerId': 'signer-xxx',
        'willDescription': '对「采购合同批量签署」任务的后续签署进行预授权',
        'multiGrant': True,
        'allowedModes': ['SMS', 'PIN'],
    }
)

响应示例

200成功

json

{
  "code": "0",
  "data": {
    "willId": "will-xxx",
    "confirmUrl": "https://esign.example.com/wills/portal/eyJ0eXAiOiJKV1Qi",
    "expireAt": "1730000000000",
    "confirmUrlExpireAt": "1729913600000",
    "willStatus": "PENDING"
  }
}

错误码

HTTP 状态码	code	说明
400	`esign_request_id_required`	`X-ES-Request-ID` 缺失，或其值不合规——去除首尾空白后必须非空、不超过 64 个字符，且只能由字母、数字、连字符 `-` 与下划线 `_` 组成；空白、控制字符及其他符号（`:`、`.`、`/`、`+`、中文等）均非法
400	`esign_will_description_required`	缺少 `willDescription` 授权告知文案
400	`esign_invalid_body`	请求体非法：JSON 语法错误或字段类型不符——注意 `grantCount` / `grantValidity` 是整数，不要加引号传成字符串
400	`esign_invalid_request`	请求参数非法（如 `certId` / `signTaskId` / `signerId` 缺失）
404	`esign_cert_not_found`	证书不存在
403	`esign_cross_account_denied`	证书不属于当前账户
409	`esign_upstream_rejected`	当前请求被云签终态拒绝（如同一 `certId + signTaskId` 已存在生效中的预授权、已存在待确认的预授权意愿、`allowedModes` 中存在不可用方式、同 `X-ES-Request-ID` 换请求体重试、有限次数窗口参数组不齐 / 不限次数仍传 `grantCount` / `multiGrant=true` 携带窗口参数 / 次数或有效期超平台上限）；`error` 为 `[上游码] 文案`，仅供人工排查、不可据其编程。修正后使用新的 `X-ES-Request-ID` 再发起。见上游错误响应与重试
409	`esign_upstream_error`	云签暂时性失败；可使用相同 `X-ES-Request-ID` 稍后安全重试。见上游错误响应与重试

预授权能力需开通

预授权签署为云签平台级能力开关，默认关闭。首次对接前请联系我们确认已开通。

业务流程

订单管理

ACME

证书管理

电子签名服务

审核链接

签名意愿

预授权签署（两步调用）

凭据管理（签署 PIN / TOTP）

证书标识与状态

密钥管理

人员信息变更

委托授权（仅企业证书）

组织管理

域名管理

账户设置

创建预授权意愿

Body 参数

响应字段

请求示例

响应示例

错误码

订单管理

ACME

证书管理

组织管理

域名管理

创建预授权意愿 ​

Body 参数 ​

响应字段 ​

请求示例 ​

响应示例 ​

错误码 ​

创建预授权意愿

Body 参数

响应字段

请求示例

响应示例

错误码