获取角色列表

更新时间：2026.07.21 10:41

功能说明

分页查询当前租户的角色列表，可按名称、角色标识、状态和创建时间筛选。

调用说明

地址：

https://www.shudacloud.com/api/open-api/platform/contacts/roles/query

方式：POST

接口编码：contacts:roles: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	每页数量
name	Body	String	否	开放接口文档测试角色-已更新	角色名称
code	Body	String	否	openapi_docs_role	角色标识，查询兼容字段
status	Body	Integer	否	0	状态：0 启用，1 停用
createTime	Body	Array	否	["2026-01-01 00:00:00","2026-12-31 23:59:59"]	创建时间范围

返回数据

名称	类型	示例值	描述
code	Integer	0	业务状态码，0 表示成功
msg	String	空字符串	业务提示信息
data.total	Long	1	总条数
data.list	Array	见返回示例	角色列表
data.list[].id	String	4c04041aa40b712574ee02f0b2d5d25d	角色编号
data.list[].name	String	开放接口文档测试角色-已更新	角色名称
data.list[].sort	Integer	95	排序值
data.list[].status	Integer	0	角色状态
data.list[].type	Integer	2	角色类型

示例

请求示例

curl --request POST \
  --url "https://www.shudacloud.com/api/open-api/platform/contacts/roles/query" \
  --header "X-API-Key: qop_f9f5d23ff4c84e2aa513e37d08780022" \
  --header "Content-Type: application/json" \
  --data '{
  "pageNo": 1,
  "pageSize": 10,
  "name": "开放接口文档测试角色-已更新"
}'

正常返回示例

{
  "code": 0,
  "msg": "",
  "data": {
    "total": 1,
    "list": [
      {
        "id": "4c04041aa40b712574ee02f0b2d5d25d",
        "name": "开放接口文档测试角色-已更新",
        "sort": 95,
        "status": 0,
        "type": 2,
        "remark": "开放接口官网文档测试数据-已更新",
        "createTime": 1784601333054
      }
    ]
  }
}

常见异常

业务状态码	说明
400	请求参数格式或必填参数校验失败
1002030001	未传入 X-API-Key
1002030002	API Key 无效
1002030003	API Key 已停用
1002030004	当前调用 IP 不在 API Key 白名单内
1002030006	当前 API Key 无权调用该接口

开放接口的业务异常通常仍返回 HTTP 200，请以响应体中的 code 判断调用是否成功。

上一条 批量删除部门 下一条 添加角色