photo-live/docs/open-v1-users-api.md

用户信息开放接口文档（/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）

{"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. 调用示例

# 基本拉取（默认在职第一页）
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 另立路径。字段需求变化联系服务方评估。