获取成员列表
更新时间：2026.07.21 10:41
功能说明
分页查询当前租户的成员列表，可按账号、状态、创建时间、部门和角色筛选。
调用说明
地址：
https://www.shudacloud.com/api/open-api/platform/contacts/members/query
方式：POST
接口编码：contacts:members:query
鉴权方式：在请求 Header 中传入 X-API-Key。无需传入 tenant-id，服务端会根据 API Key 自动识别所属租户。
本页参数和返回值来自测试环境真实调试；请求示例中的域名已按生产环境填写。当前示例 API Key 仅在测试环境有效。
请求参数
| 名称 | 位置 | 类型 | 是否必选 | 示例值 | 描述 |
|---|---|---|---|---|---|
| X-API-Key | Header | String | 是 | qop_f9f5d23ff4c84e2aa513e37d08780022 | 开放平台 API Key |
| pageNo | Body | Integer | 否 | 1 | 页码 |
| pageSize | Body | Integer | 否 | 10 | 每页数量 |
| username | Body | String | 否 | openapi_docs_20260721 | 用户账号，模糊匹配 |
| status | Body | Integer | 否 | 0 | 状态：0 启用，1 停用 |
| createTime | Body | Array | 否 | ["2026-01-01 00:00:00","2026-12-31 23:59:59"] | 创建时间范围 |
| deptId | Body | String | 否 | ea415fa680d92b39e8b7317597d9ce55 | 部门编号 |
| roleId | Body | String | 否 | 4c04041aa40b712574ee02f0b2d5d25d | 角色编号 |
返回数据
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| code | Integer | 0 | 业务状态码，0 表示成功 |
| msg | String | 空字符串 | 业务提示信息 |
| data.total | Long | 1 | 总条数 |
| data.list | Array | 见返回示例 | 成员列表 |
| data.list[].id | String | 2afa41e19b19919a0e98fbb341948e30 | 租户成员编号 system_user_tenant.id |
| data.list[].userId | String | fe95333ea2629dbb4609d6f624280890 | 基础用户编号 |
| data.list[].username | String | openapi_docs_20260721 | 用户账号 |
| data.list[].deptList | Array | 见返回示例 | 所属部门列表 |
| data.list[].roleList | Array | 见返回示例 | 所属角色列表 |
示例
请求示例
curl --request POST \
--url "https://www.shudacloud.com/api/open-api/platform/contacts/members/query" \
--header "X-API-Key: qop_f9f5d23ff4c84e2aa513e37d08780022" \
--header "Content-Type: application/json" \
--data '{
"pageNo": 1,
"pageSize": 10,
"username": "openapi_docs_20260721"
}'
正常返回示例
{
"code": 0,
"msg": "",
"data": {
"total": 1,
"list": [
{
"id": "2afa41e19b19919a0e98fbb341948e30",
"userId": "fe95333ea2629dbb4609d6f624280890",
"username": "openapi_docs_20260721",
"nickname": "开放接口文档测试成员-已更新",
"email": "openapi_docs_20260721@shudacloud.com",
"status": 0,
"deptList": [
{
"id": "ea415fa680d92b39e8b7317597d9ce55",
"name": "开放接口文档测试部门-已更新",
"parentId": "0"
}
],
"roleList": [
{
"id": "4c04041aa40b712574ee02f0b2d5d25d",
"name": "开放接口文档测试角色-已更新"
}
],
"createTime": 1784601334067,
"creatorName": "皮卡丘",
"isCreator": false
}
]
}
}
常见异常
| 业务状态码 | 说明 |
|---|---|
| 400 | 请求参数格式或必填参数校验失败 |
| 1002030001 | 未传入 X-API-Key |
| 1002030002 | API Key 无效 |
| 1002030003 | API Key 已停用 |
| 1002030004 | 当前调用 IP 不在 API Key 白名单内 |
| 1002030006 | 当前 API Key 无权调用该接口 |
开放接口的业务异常通常仍返回 HTTP 200，请以响应体中的
code判断调用是否成功。
