# 用户信息开放接口文档（/open/v1/users）

> 面向外部系统对接 · 2026-09-22 上线 · 服务方：uniservice（合塑/新友合集团统一后台）

## 1. 基本信息

| 项 | 值 |
|---|---|
| 生产地址 | `https://uniservice.server.hnxinyouhe.com/open/v1/users` |
| 方法 | `GET` |
| 鉴权 | Header `X-Api-Key`（独立钥匙，遗失/泄露请联系服务方重发） |
| 交互风格 | 标准 HTTP 状态码 + JSON；文档另见服务方 `/docs`（OpenAPI） |

## 2. 请求参数（Query）

| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `page` | int | 1 | 页码，<1 归一为 1 |
| `page_size` | int | 20 | 每页条数，<1 或 >200 归一为 20 |
| `company_id` | int | - | 按公司 id 精确筛选 |
| `status` | string | `"1"` | `1`=在职（默认）/ `2`=离职 / `0`=停用 / `all`=全部 |
| `keyword` | string | - | 姓名 / 邮箱 / 手机 模糊匹配（`%` `_` 会按字面匹配） |
| `ids` | string | - | 用户 id 逗号分隔精确拉取，如 `9,10`；非法项自动忽略 |

## 3. 响应

### 成功（HTTP 200）

```json
{"success": true, "message": "ok",
 "data": {"items": [ /* 用户对象数组 */ ],
          "total": 213, "page": 1, "page_size": 20}}
```

### 用户对象字段

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | int | 用户 id（**稳定主键**） |
| `sn` | string | 工号 |
| `name` | string | 姓名 |
| `sex` | int/null | 性别 |
| `email` | string | 企业邮箱 |
| `phone` | string | 手机号 |
| `avatar` | string/null | 头像 URL（飞书 CDN 直链，可直接展示） |
| `status` | int | 1=在职 / 2=离职 / 0=停用 |
| `user_type` | int | 用户类型 |
| `manager_id` | int/null | 直属上级用户 id |
| `company_id` | int | 所属公司 id（见下方"一人多档"说明） |
| `union_id` | string/null | **飞书 union_id**（同开发商体系内跨应用稳定） |
| `created_at` / `updated_at` | string | 档案时间 |
| `company_name` | string | 公司名称（关联） |
| `company_abbr` | string | 公司简称 |
| `company_tenant_key` | string | 公司飞书 tenant_key（关联） |
| `feishu_open_id` | string/null | 飞书 open_id（**应用域**，见 §5 注意①） |
| `feishu_user_id` | string/null | 飞书 user_id |
| `feishu_tenant_key` | string/null | 绑定应用的 tenant_key |
| `last_login_at` | string/null | 该飞书绑定最近登录时间 |
| `roles` | string[] | 角色 code 列表（如 `["user","admin"]`） |

### 失败

| HTTP | 响应 | 场景 |
|---|---|---|
| 401 | `{"success":false,"message":"Invalid API Key","error_code":"INVALID_API_KEY"}` | key 缺失/错误/未配置 |
| 400 | `{"success":false,"message":"查询失败","error_code":"QUERY_FAIL"}` | 服务端查询异常 |

## 4. 调用示例

```bash
# 基本拉取（默认在职第一页）
curl -H "X-Api-Key: <你的key>" \
  "https://uniservice.server.hnxinyouhe.com/open/v1/users?page=1&page_size=50"

# 按公司 + 关键词
curl -G -H "X-Api-Key: <你的key>" \
  "https://uniservice.server.hnxinyouhe.com/open/v1/users" \
  --data-urlencode "company_id=1" --data-urlencode "keyword=张"

# 精确拉一批人（含离职）
curl -H "X-Api-Key: <你的key>" \
  "https://uniservice.server.hnxinyouhe.com/open/v1/users?status=all&ids=9,10,74"
```

## 5. 重要注意事项（对接飞书登录必读）

1. **`feishu_open_id` 是应用域的**：它是用户在**服务方飞书应用**里的 open_id。
   贵方若使用**自己另建的飞书应用**，此 id 在贵方应用内查不到人，请改用：
   - `union_id`（仅当双方应用属**同一飞书开发商**时跨应用一致）；或
   - `email` / `phone` 匹配（登录后用 contact API 反查）。
   若贵方直接复用服务方的飞书应用凭证，则 `feishu_open_id` 可直接用。
2. **一人多档**：本系统用户档案**按公司分档**——同一自然人在不同公司各有一行
   （不同 `id`/`sn`，`company_id` 不同）。归并自然人请用 `union_id`（或手机号），
   不要假设姓名唯一。
3. **未绑定飞书**的用户 `feishu_*` 三字段为 `null`（`union_id` 亦可能为 null）。
4. 分页上限 200/页；全量同步建议按 `page` 递增循环至取空。
5. key 是贵方系统专属，请勿嵌入前端/客户端代码，仅服务端持有。

## 6. 变更约定

接口属 v1 冻结面：**只增字段不改既有字段语义**（新增字段贵方可忽略）。
不兼容变更将升 v2 另立路径。字段需求变化联系服务方评估。