Appearance
新增委托人
POST
/openapi/v3/esign/delegates
为企业证书新增一名委托人（受托代签人），使其在授权生效期间可代替经办人在该证书上签署。仅企业证书支持委托授权，个人证书不适用。
本接口是双向意愿：一次调用返回一个 willId，但同时返回两条 confirmUrl——grantorConfirmUrl（转发给授权主体/经办人）与 delegateConfirmUrl（转发给被委托人）。两条链接同时有效、确认不限先后，须双方都完成确认，委托授权才真正生效。
X-ES-Request-ID 必填
本接口为幂等创建类接口，请求头必须携带 X-ES-Request-ID 作为幂等键，规则见通用说明。
Body 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| certIds | array<string> | 是 | 委托授权覆盖的云签证书 ID 列表，须非空数组，且逐个属于调用方账户；全部 certIds 必须归属同一个企业订户（跨企业混传返回 400 esign_invalid_request） |
| validFrom | string | 否 | 生效时间（毫秒时间戳字符串）；不传或空串表示立即生效 |
| validTo | string | 否 | 失效时间（毫秒时间戳字符串）；不传或空串表示无固定止期（长期有效）。传入时须晚于当前时间（否则 409 esign_upstream_rejected，上游码 -5106），且须晚于 validFrom；授权区间按 [validFrom, validTo) 判定——双方确认完成后云签还会复检 validTo，已过期则生效失败（businessStatus=FAILED） |
| grantorPersonId | string | 是 | 授权主体的云签经办人 ID（企业经办人，即 personType=ENTERPRISE_PERSON）。取自证书标识映射查询响应的 managerId，须与 certIds 锚定的企业一致，否则返回 403 esign_person_not_in_scope |
| delegate | object | 是 | 被委托人信息 |
| delegate.platformId | string | 是 | 来源平台标识——标识「这条人员记录由哪个平台报送」，是您平台的固定常量（如 "cc-sign"），不是每个终端用户各不相同的用户 ID。它参与云签的人员判重组合，一经使用不得变更，见下方说明 |
| delegate.platformName | string | 是 | 调用方平台名称 |
| delegate.lastName | string | 是 | 被委托人姓氏 |
| delegate.firstName | string | 是 | 被委托人名字 |
| delegate.idCardType | string | 是 | 证件类型；云签当前仅支持 IDCARD（强枚举，仅限中国大陆居民身份证），传入其他值会被上游拒绝 |
| delegate.idCardNo | string | 是 | 证件号码 |
| delegate.mobile | string | 是 | 被委托人手机号 |
| delegate.email | string | 否 | 被委托人邮箱 |
certIds 必填，CC 不支持云签"缺省展开全部"
云签上游允许 certIds 缺省，此时按登记时刻该企业下的全部证书展开授权。CertCloud 刻意不暴露这个默认值——"全部证书"是登记时刻的快照、语义模糊，作为默认值风险过高，且重叠授权预检（见下方「重叠授权冲突」）需要精确知道涉及哪些证书。请显式传入完整的 certIds 列表。
被委托人身份如何匹配
云签按 enterpriseId + platformId + idCardType + idCardNo + personType + firstName + lastName 七项组合定位/复用委托人身份（enterpriseId 由本请求 certIds 所属企业派生、personType 固定为委托人，二者无需您传）——判重限定在同一企业范围内，不同企业下的同一自然人是两条独立记录：组合命中已存在的委托人记录时会直接复用，仅当命中记录的 mobile 与本次传入不一致时，创建会被上游拒绝（409 esign_upstream_rejected）。首次为某人建委托时该组合务必与其证件、姓名保持一致，避免后续因手机号不一致被拒。
委托人换手机号，先走「变更人员联系信息」
云签不会用本接口传入的 mobile 去覆盖既有委托人记录：身份组合命中而手机号不一致时，直接拒绝创建（409 esign_upstream_rejected，上游码 -5056）。
正确顺序是：先用变更人员联系信息（personId=delegateId）由该委托人本人确认完成换号，再用新号发起新的委托授权。
旧号已停用不阻断换号：变更意愿页的本人身份确认可用人脸核验或动态口令（TOTP）代替原号短信，新手机号另有可达性验证。请不要改用新的 platformId 重复建档来绕开——那会在同一自然人名下产生两条互不相干的委托人记录，历史授权与存证无法关联。
重叠授权冲突
同一委托人在同一证书上的授权有效期不可重叠（首尾相接允许）：新请求的 [validFrom, validTo] 区间若与该委托人在该证书上任一既有生效授权的区间重叠（含未设 validTo 的长期授权），返回 409 esign_delegate_authorization_overlap，响应体 data.conflicts[] 携带每条冲突的明细（见下方错误码），供调用方决定收窄证书集合或调整时间窗后换新的 X-ES-Request-ID 重试。
相同授权确认中勿重复发起
同一身份组合 + 相同证书范围的委托授权已有确认中的意愿时，重复发起会被终态拒绝（409 esign_upstream_rejected，上游码 -5046「相同委托授权正在确认中」）。此时应先按既有 willId 经查询意愿结果确认在途意愿的结果（链接丢失可用同一 X-ES-Request-ID 幂等回放取回），而不是修改参数重试。
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| willId | string | 意愿 ID，用于经查询意愿结果按 willId 轮询双方确认与生效进度 |
| grantorConfirmUrl | string | 转发给**授权主体（经办人）**打开确认的一次性链接，规则同意愿模型说明（云签域名、原样透传、请勿缓存或记录日志） |
| delegateConfirmUrl | string | 转发给被委托人打开确认的一次性链接，规则同上 |
| delegateId | string | 本次建单落库的委托人人员 ID（新建与幂等回放两种情形取值一致）。这是后续该委托人代签时须传入的 signerId——委托生效后，代签时调发起签名意愿，以 signerId=delegateId 指定由该委托人签署，请务必保存 |
| expireAt | string | 意愿过期时间（毫秒时间戳字符串，长整型一律字符串，见通用说明） |
| willStatus | string | 意愿当前状态，创建成功后通常为待确认态 PENDING；取值见查询意愿结果。生效判定见下方说明 |
双方确认与生效的判定
经查询意愿结果按 willId 轮询：willStatus 依次经历 PENDING（均未确认）→ PARTIAL_CONFIRMED（一方已确认，另一方待确认，不限哪一方先）→ CONFIRMED（双方均已确认）。与其他意愿类接口相同，willStatus=CONFIRMED 不是生效信号——委托授权在云签侧异步生效，须以 businessStatus=SUCCEEDED 作为生效完成的判定依据（FAILED 时 failReason 给出原因），期间应继续轮询。生效后可经查询委托授权记录确认逐证书的授权明细。
请求示例
bash
curl -X POST 'https://api.certcloud.cn/openapi/v3/esign/delegates' \
-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: 3b9e2c1a-6f4d-4a8e-9c2b-1e5f7a8d9c0b' \
-d '{
"certIds": ["esign-cert-xxx"],
"validFrom": "1784457961968",
"validTo": "1790000000000",
"grantorPersonId": "manager-xxx",
"delegate": {
"platformId": "cc-sign",
"platformName": "your-app",
"lastName": "张",
"firstName": "三",
"idCardType": "IDCARD",
"idCardNo": "110101199001010011",
"mobile": "13800138000",
"email": "zhangsan@example.com"
}
}'响应示例
错误码
| HTTP 状态码 | code | 说明 |
|---|---|---|
| 400 | esign_request_id_required | X-ES-Request-ID 缺失或不合规，规则见通用说明 |
| 400 | esign_invalid_body | 请求体非法：JSON 语法错误或字段类型不符（整数字段传字符串、字符串字段传数字等），请求体未被解析 |
| 400 | esign_invalid_request | certIds 缺失/为空数组；delegate 必填字段缺失；或 certIds 横跨了不同企业订户 |
| 404 | esign_cert_not_found | certIds 中存在不存在的证书 |
| 403 | esign_cross_account_denied | certIds 中存在不属于当前账户的证书 |
| 403 | esign_person_not_in_scope | grantorPersonId 与该企业的经办人不符（授权主体只能是经办人，不能是委托人本人） |
| 409 | esign_idempotency_conflict | 复用同一 X-ES-Request-ID 但请求体与首次发起不一致；请改用新的 X-ES-Request-ID。见X-ES-Request-ID 幂等键 |
| 409 | esign_delegate_authorization_overlap | 新请求的生效期与该证书上既有生效中的委托授权重叠；响应体 data.conflicts[] 携带冲突明细（见下表）。个别情形下（云签侧并发预检漏网）conflicts 可能为空数组 []，仍应按此码处理 |
| 409 | esign_delegate_replay_unavailable | 复用的 X-ES-Request-ID 命中了此前发起的建单记录，但该记录已流转出可回放窗口（例如已进入终态、或已被取消意图接管）；请改用新的 X-ES-Request-ID 重新发起 |
| 409 | esign_upstream_rejected | 当前请求被云签终态拒绝；error 为 [上游码] 文案，仅供人工排查、不可据其编程。常见场景包括被委托人身份匹配命中但手机号不一致。修正输入后使用新的 X-ES-Request-ID 再发起。见上游错误响应与重试 |
| 409 | esign_upstream_error | 云签暂时性失败，可使用相同 X-ES-Request-ID 稍后安全重试。见上游错误响应与重试 |
conflicts[] 字段说明
409 esign_delegate_authorization_overlap 响应体 data.conflicts 为数组，每个元素对应一条产生冲突的既有授权记录：
| 字段 | 类型 | 说明 |
|---|---|---|
| certId | string | 发生重叠的证书 ID |
| validFrom | string | 冲突的既有授权生效时间（毫秒时间戳字符串） |
| validTo | string | 冲突的既有授权失效时间（毫秒时间戳字符串）；空字符串表示该既有授权长期有效 |
| conflictAuthorizationId | string | 冲突的既有授权记录 ID，可用于查询委托授权记录进一步核实 |
json
{
"code": "esign_delegate_authorization_overlap",
"error": "delegate authorization overlaps an existing grant",
"data": {
"conflicts": [
{
"certId": "esign-cert-xxx",
"validFrom": "1700000000000",
"validTo": "1800000000000",
"conflictAuthorizationId": "auth-xxx"
}
]
}
}