乾策立方开放平台文档

GET /api/openplatform/employees

查询当前企业员工分页列表。

查询参数

参数	类型	必填	说明
`page`	int	否	页码，默认 1。
`pageSize`	int	否	每页条数，默认 20，最大 100。
`keyword`	string	否	按员工姓名或拼音模糊查询。

响应示例

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "total": 1,
    "items": [
      {
        "virtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz",
        "name": "张三",
        "phone": "138****5678",
        "departmentName": "运营部",
        "positionName": "运营经理",
        "isBound": true
      }
    ]
  }
}

响应字段

员工列表的 data.items 单项与员工详情的 data 使用相同的 Employee 结构。

字段	类型	说明
`data.total`	long	列表接口的员工总数。
`data.page`	int	列表接口当前页码，从 1 开始。
`data.pageSize`	int	列表接口当前页返回条数上限，范围为 1 到 100。
`data.items`	Employee[]	列表接口当前页员工数据。
`virtualId`	string	员工在当前企业和 API Key 维度的公开稳定标识。
`name`	string	员工姓名。头像与登录账号不下发。
`phone`	string	脱敏手机号（保留前三后四）。
`departmentName`	string	部门名称；未设置时为空字符串。
`positionName`	string	岗位名称；未设置时为空字符串。
`isBound`	bool	当前 API Key 下是否已存在第三方账号绑定关系。

字段说明：virtualId 在当前企业 + 当前 API Key 维度唯一且稳定，由平台按算法实时生成；重置 ApiSecret 不会改变同一员工在当前 API Key 下的 virtualId。isBound 表示当前 API Key 下是否已存在第三方账号绑定关系。

GET /api/openplatform/employees/{virtualId}

按 virtualId 查询员工详情。

响应示例

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "virtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz",
    "name": "张三",
    "phone": "138****5678",
    "departmentName": "运营部",
    "positionName": "运营经理",
    "isBound": true
  }
}

响应字段：详情 data 返回一个 Employee 对象，字段、类型和含义见员工列表下方“响应字段”表。

GET/api/openplatform/departments

获取当前企业的部门列表。权限 departments.read；不要求 X-Employee-Virtual-Id。只读，不写库、不排队，不影响任何可见性。

查询参数	类型	默认	说明
`departmentIds`	int[]	不过滤	按部门 Id 集合精确取回，元素是整型部门 Id（取自本接口返回的 `id`，不是 Guid）。多个值必须用同名查询参数重复传，如 `departmentIds=3&departmentIds=4`；不支持逗号分隔（`departmentIds=3,4` 会被参数绑定拒绝，返回 `400`「请求参数错误：departmentIds 格式不正确」）。最多 100 个（与 MCP `department_resolve` 同口径）；超限返回 `400` 并提示「departmentIds 最多 100 个」，不做截断。重复值自动去重，非正数被静默丢弃而不是报错。
`keyword`	string	不过滤	按部门名称模糊匹配（先 `Trim`，空白等价于不传）。
`page`	int	1	页码，小于 1 时按 1 处理，不报错。
`pageSize`	int	20	每页条数，静默收敛到 1 到 100；非数字返回 `400`。

data 为分页结构 {total, page, pageSize, items}；items 按部门 Id 升序（由小到大），字段：id（int）、name、parentId（int，根部门为 0）、path、level（根为 1）。

失败情况：下游部门解析失败时返回 400 并透传内网码与文案（如 101「缺少企业上下文」、102「操作人不存在」）。

员工接口

查询参数

响应示例

响应字段

响应示例