## 接口说明
contact/v3/users 按部门分页返回用户基础信息,是飞书组织主数据集成的标准接口。典型场景:以飞书组织架构为权威源,把人员主数据同步到 ERP 业务员档案、BI 权限表与审批-单据归属映射,保证跨系统人员口径一致。
### 请求要点
1. GET 请求,header 带 Authorization: Bearer {tenant_access_token}。
2. query 参数:department_id(部门 ID,根部门为 0,必填)、department_id_type(open_department_id 或 department_id)、user_id_type(返回用户 ID 类型:open_id/union_id/user_id)、page_size(≤50)、page_token。
3. 响应 data.items 为用户数组,含 open_id、union_id、name、en_name、email、mobile、department_ids、status 等;has_more/page_token 翻页。
4. 应用需在权限管理开通 contact:user.base:readonly 等 scope 并发版;手机号/邮箱等字段需要更高级别 scope,未授权时字段返回为空。
### 主数据同步建议
- 关联键推荐 union_id(跨应用稳定),open_id 仅在单应用内稳定。
- status.is_frozen 标识离职/冻结用户,主数据侧据此做停用而非删除,保留历史单据归属。
- 与 ERP 人员编码的映射表建议按工号(employee_no)对齐,避免姓名冲突。