## 接口说明
topapi/v2/user/list 按部门 ID 游标分页返回该部门用户的详细信息,是组织与人员主数据集成的标准接口。典型场景:以钉钉组织架构为权威源,定时把人员主数据(userid、姓名、部门、职位、手机号、邮箱)同步到 ERP 业务员档案、费用报销系统的成本中心映射表,保证单据归属与审批流一致。
### 请求要点
1. POST + application/json,access_token 放 URL query。
2. body 参数:dept_id(部门 ID,根部门为 1,必填)、cursor(游标,首页 0)、size(每页 ≤100)、order_field(排序,默认 entry_asc)、contain_access_limit(是否返回受限制的字段)。
3. 响应 result.list 为用户对象数组,含 userid、name、mobile、email、title、dept_id_list 等;has_more/next_cursor 控制翻页。
4. 全量组织同步通常先调 topapi/v2/department/listsub 拉部门树,再逐部门拉用户;手机号等敏感字段需要应用在开发者后台额外申请字段权限。
### 注意事项
- 通讯录权限范围(应用可见部门)决定能拉到哪些部门与用户,权限范围外返回空列表而不是报错,排查时先确认可见范围。
- 人员主数据建议以 userid 作为关联键,name 可能重复;离职用户会从列表中消失,主数据侧要做软删除而非物理删除。