浅念
103 lines
4.4 KiB
Markdown
103 lines
4.4 KiB
Markdown
# 用户信息开放接口文档（/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 另立路径。字段需求变化联系服务方评估。
|