## 接口说明
cgi-bin/user/list 按部门 ID 返回成员完整信息(含手机号、邮箱等敏感字段),是组织与人员主数据同步的标准接口。注意:该接口使用【通讯录同步】助手的 secret 换取的 token,而非普通自建应用 token;自建应用如需读通讯录,只能拿到受限字段。
### 请求要点
1. POST + application/json,access_token(通讯录 secret 换取)放 URL query。
2. body 参数:department_id(部门 ID,根部门 1,必填)、fetch_child(1 递归子部门,0 仅本部门)。
3. 响应 userlist 为成员数组,含 userid、name、department(部门数组)、position、mobile、email、status(1 已激活,4 未激活)等。
4. 全量同步一般先 cgi-bin/department/list 拉部门树,再按部门拉成员;开启通讯录回调可实时接收成员变更事件,替代轮询。
### 主数据同步建议
- 关联键用 userid(企业内唯一);姓名可重复,不要作为关联键。
- 离职成员从接口中消失,主数据侧做停用标记而非物理删除,保留历史单据归属。
- mobile/email 属于敏感字段,通讯录 secret 要严格控制知悉范围;同步到下游系统前评估字段必要性,最小化敏感数据扩散面。
### 与轻量接口的选择
若只需要成员 userid 与姓名等轻量信息,可使用 simplelist 系列接口,响应更小、权限要求更低;user/list 返回全字段(含手机号、邮箱等敏感信息),仅在确需这些字段时使用,遵循数据最小化原则,也缩小通讯录 secret 泄露后的影响面。