文档中心

Appearance

变更人员联系信息 ​

POST
/openapi/v3/esign/personnel-update

发起变更证书关联人员（企业经办人、委托人或个人订户本人）联系方式的意愿。接口返回 confirmUrl，需转发给该人员打开完成确认，再通过查询意愿结果轮询结果。

这是修改联系方式的唯一通道

其他接口都不会覆盖既有人员的手机号 / 邮箱：新增委托人在身份组合命中而手机号不一致时直接拒绝创建（409 esign_upstream_rejected，上游码 -5056），而不是更新号码。

因此委托人换号必须先走本接口（personType=ENTERPRISE_PERSON、personId=delegateId），换号生效后再发起新的委托授权；顺序反了会一直卡在 -5056。

姓名与证件类型 / 证件号码不可变更——「姓名 + 证件号码」是识别自然人的唯一标识。信息有误或需要换人，走禁用委托人后重新新增委托人。

X-ES-Request-ID 必填

本接口为幂等创建类接口，请求头必须携带 X-ES-Request-ID 作为幂等键。

Body 参数 ​

参数类型必填说明
certIdstring是云签证书 ID，作为人员归属校验的锚点
personTypestring是人员类型，可选 ENTERPRISE_PERSON（企业人员：经办人（含亲自经办的法定代表人）/ 委托人）/ PERSONAL_SUBSCRIBER（个人订户本人）
personIdstring是人员 ID。须是该证书下与 personType 相符的实际人员，按身份取值：个人订户本人取证书标识映射查询响应的 subjectId；企业经办人取同一响应的 managerId；委托人取新增委托人响应的 delegateId。获取方式见下方说明
mobilestring否新手机号。mobile / email 至少填写一项；修改手机号时还须对新手机号完成可达码验证（意愿页内先本人核验、再验证新号可达，两阶段均通过才生效；仅改邮箱不要求第二次可达验证）
emailstring否新邮箱。mobile / email 至少填写一项

personId 如何获取

personId 需通过接口反查，按人员身份取值：

  1. 用下单响应中拿到的 CertCloud 订单 ID（data.id）调用证书标识映射查询：GET /openapi/v3/esign/certs?orderId=<订单 ID>。
  2. 按本请求所指人员的实际身份，取对应字段作为 personId：
    • 个人订户本人（personType=PERSONAL_SUBSCRIBER）→ 取映射响应的 subjectId
    • 企业经办人（personType=ENTERPRISE_PERSON）→ 取映射响应的 managerId
    • 委托人（personType=ENTERPRISE_PERSON）→ 取新增委托人响应的 delegateId（该字段不在映射响应中，无需第 1 步）。若手上没有当初的建单响应（例如该委托人由他人早先登记），可改用查询企业人员按 certId 反查：响应中 personType=DELEGATE 的条目，其 personId 即为所需值

personType 与所取字段必须对应（个人证书用 subjectId、企业证书用 managerId 或 delegateId）；取错字段或填入其它来源的 ID，会返回 403 esign_person_not_in_scope。

⚠️ 委托人须已生效：只有出现在查询企业人员结果中、 且 status=ENABLED 的人员才可用。新增委托人是双向意愿， 须授权主体与被委托人双方都确认、查询意愿结果返回 businessStatus=SUCCEEDED 后，云签才登记该人员。若意愿仍停在 PARTIAL_CONFIRMED （businessStatus=PENDING），说明尚有一方未确认、该委托人还未登记，此时传入其 delegateId 会返回 403 esign_person_not_in_scope。该错误码专指「人员不在本证书可用范围」， 与 esign_cross_account_denied（证书不属于当前账户）已分开，可据此程序化区分； 但它仍合并了「人员不存在」「委托未生效」「与 personType 不匹配」三种成因， 排查时请用上述接口核对人员是否在册且启用。

响应字段 ​

字段类型说明
willIdstring意愿 ID，用于经查询意愿结果按 willId 轮询确认与生效进度
confirmUrlstring转发给待变更联系方式的本人（企业经办人或个人订户）打开确认的一次性链接，规则同意愿模型说明（云签域名、原样透传、请勿缓存或记录日志）
expireAtstring意愿过期时间（毫秒时间戳字符串，长整型一律字符串，见通用说明）。超过该时间后意愿转为过期终态
willStatusstring意愿当前状态，创建成功后通常为待确认态 PENDING；取值见查询意愿结果。CONFIRMED 不代表变更已生效，见下方判定说明

变更生效的判定

本人在意愿页完成确认后（查询接口 willStatus=CONFIRMED），联系方式变更在云签侧异步生效——CONFIRMED 不代表新联系方式已更新。以查询意愿结果返回的 businessStatus=SUCCEEDED 作为变更完成的判定依据（FAILED 时 failReason 给出原因）。

请求示例 ​

bash
curl -X POST 'https://api.certcloud.cn/openapi/v3/esign/personnel-update' \
  -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: 5c9d3a1e-7b2f-4e6a-8d0c-3f1a2b4c5d6e' \
  -d '{
    "certId": "esign-cert-xxx",
    "personType": "ENTERPRISE_PERSON",
    "personId": "manager-xxx",
    "mobile": "13800138000"
  }'

响应示例 ​

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

错误码 ​

HTTP 状态码code说明
400esign_request_id_requiredX-ES-Request-ID 缺失，或其值不合规——去除首尾空白后必须非空、不超过 64 个字符，且只能由字母、数字、连字符 - 与下划线 _ 组成；空白、控制字符及其他符号（:、.、/、+、中文等）均非法
400esign_invalid_body请求体非法：JSON 语法错误或字段类型不符（整数字段传字符串、字符串字段传数字等），请求体未被解析
400esign_invalid_request请求参数非法
400esign_person_info_requiredmobile 与 email 均未填写
404esign_cert_not_found证书不存在
403esign_cross_account_denied证书不属于当前账户
403esign_person_not_in_scope人员不在该证书的可用人员范围——personId 不存在、委托授权尚未生效 / 已撤销 / 已过期，或与 personType 不匹配
409esign_idempotency_conflict复用同一 X-ES-Request-ID 但请求体与首次发起不一致；不回放旧意愿、也不创建新意愿，请改用新的 X-ES-Request-ID。见X-ES-Request-ID 幂等键
409esign_upstream_rejected当前请求被云签终态拒绝；error 为 [上游码] 文案，仅供人工排查、不可据其编程。修正输入或证书状态后，使用新的 X-ES-Request-ID 再发起。见上游错误响应与重试
409esign_upstream_error云签暂时性失败；error 为 [上游码] 文案，仅供人工排查、不可据其编程。可使用相同 X-ES-Request-ID 稍后安全重试。见上游错误响应与重试