这个接口解决什么问题

钉钉开放平台的 topapi/v2/department/listsub 用于按"父部门 ID"取出下一级直接子部门列表,是企业把钉钉组织架构同步到 ERP(如金蝶云星空)、审批流、权限系统的主入口。它本身只查下一级、不递归,因此需要工程侧自建"遍历-聚合"循环,常用于组织架构同步、员工归属映射、审批人按部门过滤等场景。

接口能力总览

认证方式:钉钉开放平台 AppKey/AppSecret + access_token,旧版企业 corpId/corpSecret 仍兼容,access_token 一般 7200 秒过期,需要缓存与刷新。
请求结构:HTTP POST,Content-Type application/json,请求体传 dept_id(父部门 ID,默认 1 即根部门)、可选 language 等。
响应结构:errcode/errmsg + result 数组,数组元素即部门对象(含 dept_id、name、parent_id、create_dept_group、auto_add_user 等)。
分页/增量模式:本接口不返回分页字段,实测单次返回当前父部门下全部直接子部门;不支持 cursor/offset,也没有官方增量时间戳;增量通常依赖下游 ERP 的 lastModifiedTime 或主数据变更日志。
限频与边界:调用频次受企业级 QPS 限制,大批量遍历需要加入队列与退避;只查单级、不是递归接口是这一接口最大的设计特征。

典型字段映射

字段名	类型	含义	实战注意事项
dept_id	string	部门唯一主键,作为金蝶部门对照的关联键	字符串型,跨系统传输务必保持原样,不要做数值化;在轻易云的 metadata 里通常配为 `id`。
name	string	部门显示名	容易含全角空格、换行和 emoji,落库前要做 trim 与统一编码;metadata 里配为 `number`(业务标识)。
parent_id	string	上级部门 ID,根部门固定为 1	这是构建组织树的唯一线索,务必与请求参数中的 `dept_id` 严格区分,避免父子错乱。
create_dept_group	string	是否创建部门群	历史返回存在布尔/字符串两种形态,在金蝶侧一般映射为 0/1 或枚举,需做兼容。
auto_add_user	string	新成员是否自动加入部门群	同上,做布尔归一化处理,避免下游 ES/数据库字段类型不一致。

在轻易云上如何配置

在轻易云数据集成平台里,这类接口通常以"钉钉适配器 + 字段映射器"的形式被封装好:

适配器选择:源系统选「钉钉 - 部门查询」,目标系统按业务选金蝶云星空「部门」或轻易云内部主数据存储;平台已内置 access_token 缓存与刷新策略。
请求参数:把 dept_id 暴露为策略参数,默认填 1;如果要做多级遍历,通常在「轻易云集成平台」侧配置"循环调用器",把上次结果中的子部门 ID 列表压入下一轮请求。
字段映射:字段映射器会自动识别 dept_id → id、name → number,并允许你把 parent_id 映射到金蝶部门的"上级部门"字段;在多方案对比中,我们通常把 create_dept_group 和 auto_add_user 统一归一为布尔再下传。
调度:典型的 cron 是每月 1 日 1 时 1 分(1 1 1 * *),适配器会把组织全量推送到金蝶,日常新增则交给变更检测策略。

跨方案实战要点

必须做单级遍历 + 内存/B 端任务聚合:listsub 不递归,我们在多个客户方案里都采用"队列 + 递归调用"的方式,把每层的子部门 ID 收集后再发起下一轮,直到 result 为空数组。
根部门 ID 默认为 1,但要支持自定义根:部分客户的钉钉组织是从非 1 的子部门起算(常见于子集团/分公司场景),策略参数 dept_id 必须可配置,而不是写死 1。
组织树重建建议在下游做:钉钉侧只负责返回扁平的父子关系,组织树的"展开/排序/层级编号"放在金蝶或轻易云侧完成,降低钉钉接口耦合。
与金蝶云星空的部门对照键优先用 dept_id:编码在跨组织合并、子公司重组时容易重号,而 dept_id 由钉钉保证全局唯一;轻易云的对照表模块会自动以 dept_id 作为匹配键。
企业群相关字段做布尔归一:历史 API 返回值类型不稳定,需要在映射器里做 true/false 与 1/0 的双向兼容,这是多次客户踩坑后沉淀下来的"标配动作"。
调度建议"全量 + 增量"双轨:全量每月一次跑组织比对,增量靠钉钉事件回调或源系统轮询;轻易云的调度中心支持这两种模式并存。

踩坑复盘

踩坑 1:把单级接口当递归用,只取到一级部门。 真实场景中,只调用一次 dept_id=1 只能拿到一级部门,后续子公司、人员挂不上去;稳妥的做法是,在轻易云里配置"递归遍历器",逐层请求直到空数组。
踩坑 2:parent_id 与请求 dept_id 混淆。 曾有方案把返回的 parent_id 当作下一轮请求的 dept_id,造成无限循环或路径丢失;这里容易翻车,务必以"本层返回的 dept_id"作为下一轮起点。
踩坑 3:access_token 频次超限被限流。 全量组织遍历时一次性发起大量请求,触发钉钉企业级 QPS 限制;稳妥的做法是接入轻易云的限频器与重试退避策略,把节奏交给平台。
踩坑 4:企业群布尔字段类型不一致,落库报错。 同样是 create_dept_group,不同租户/历史版本返回 true/false 或 1/0,落库字段类型不匹配就会报错;建议在字段映射器里统一做归一。
踩坑 5:把"部门查询"和"部门写入"混在一条链路里。 钉钉侧是只读的 QUERY 策略,写入金蝶应交给下游写入策略,不要把 create/update 操作叠加在查询接口上,否则失败时无法回滚。

何时选用

适用于需要把钉钉组织架构定期/实时同步到 ERP、HR、审批或数据仓库,且组织层级清晰、变更频次可控的场景;不适合"只同步少数指定部门 + 实时高频变更"的业务,后者应直接使用钉钉事件回调流,而不是按 listsub 轮询。

钉钉部门查询接口字段手册权威教程：从 listsub 单级遍历到多端组织架构同步