查询企业人员

POST

/openapi/v3/esign/enterprise-persons/query

按证书查询其所属企业下的人员列表（经办人——含亲自经办的法定代表人，云签按经办人统称建档——与已登记的委托人），用于在发起新增委托人前定位候选人员，或核对企业人员的当前状态。

本接口为纯查询接口，不要求携带 X-ES-Request-ID。

企业范围由 certId 派生，不可自行指定

本接口按 certId 定位——该证书必须归属调用方账户，所查询的企业范围由 CertCloud 从证书归属关系派生，调用方无法直接传入企业 ID 来查询任意企业的人员，避免跨企业枚举。

Body 参数

参数	类型	必填	说明
certId	string	是	云签证书 ID，用作归属校验锚点，同时决定查询的企业范围（须为调用方账户名下的企业证书，个人证书传入会被拒绝）。返回范围为该企业下与本账户证书关联的人员
page	int	否	页码，从 1 开始；不传或非正数按 1 处理
pageSize	int	否	每页条数；不传或非正数按 20 处理，超过 100 按 100 截断

响应字段

字段	类型	说明
content	array	企业人员列表
content[].personId	string	云签侧人员 ID
content[].enterpriseId	string	云签侧企业 ID
content[].personType	string	人员类型：LEGAL_REPRESENTATIVE（法定代表人——预留枚举，当前无建档来源、不会返回；法定代表人亲自经办按 MANAGER 建档，统称经办人）/ MANAGER（经办人）/ DELEGATE（委托人）
content[].name	string	姓名
content[].idCardType	string	证件类型
content[].idCardNo	string	证件号码
content[].mobile	string	手机号
content[].email	string	邮箱；未登记时为空字符串
content[].status	string	人员状态：ENABLED（启用）/ DISABLED（停用）
page	int	当前页码
pageSize	int	每页条数
total	string	总条数（长整型一律字符串，见通用说明）

请求示例

curl -X POST 'https://api.certcloud.cn/openapi/v3/esign/enterprise-persons/query' \
  -H 'Content-Type: application/json' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id' \
  -d '{
    "certId": "esign-cert-xxx",
    "page": 1,
    "pageSize": 20
  }'

const response = await fetch('https://api.certcloud.cn/openapi/v3/esign/enterprise-persons/query', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CC-Auth-Key': 'your-auth-key',
    'X-CC-Key-ID': 'your-key-id',
  },
  body: JSON.stringify({
    certId: 'esign-cert-xxx',
    page: 1,
    pageSize: 20,
  })
})

req, _ := http.NewRequest("POST", "https://api.certcloud.cn/openapi/v3/esign/enterprise-persons/query", strings.NewReader(`{
  "certId": "esign-cert-xxx",
  "page": 1,
  "pageSize": 20
}`))
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")
resp, _ := http.DefaultClient.Do(req)

import requests

resp = requests.post(
    'https://api.certcloud.cn/openapi/v3/esign/enterprise-persons/query',
    headers={
        'X-CC-Auth-Key': 'your-auth-key',
        'X-CC-Key-ID': 'your-key-id',
    },
    json={
        'certId': 'esign-cert-xxx',
        'page': 1,
        'pageSize': 20,
    }
)

响应示例

200成功

{
  "code": "0",
  "data": {
    "content": [
      {
        "personId": "manager-xxx",
        "enterpriseId": "ent-xxx",
        "personType": "MANAGER",
        "name": "张三",
        "idCardType": "IDCARD",
        "idCardNo": "110101199001010011",
        "mobile": "13800138000",
        "email": "zhangsan@example.com",
        "status": "ENABLED"
      },
      {
        "personId": "delegate-xxx",
        "enterpriseId": "ent-xxx",
        "personType": "DELEGATE",
        "name": "李四",
        "idCardType": "IDCARD",
        "idCardNo": "110101199001010029",
        "mobile": "13900139000",
        "email": "",
        "status": "ENABLED"
      }
    ],
    "page": 1,
    "pageSize": 20,
    "total": "2"
  }
}

错误码

HTTP 状态码	code	说明
400	esign_invalid_body	请求体非法：JSON 语法错误或字段类型不符（整数字段传字符串、字符串字段传数字等），请求体未被解析
400	esign_invalid_request	certId 缺失
404	esign_cert_not_found	certId 不存在
403	esign_cross_account_denied	certId 不属于当前账户
409	esign_upstream_rejected	云签终态拒绝；error 为 [上游码] 文案，仅供人工排查。见上游错误响应与重试
409	esign_upstream_error	云签暂时性失败，可稍后重试。见上游错误响应与重试