这个接口解决什么问题

在金蝶云星空与钉钉的集成场景里,「部门」是组织架构同步的主数据底座:员工归属、审批流的部门选择器、数据权限隔离都依赖它。topapi/v2/department/listsub 是钉钉开放平台用于「查询指定父部门下直接子部门列表」的轻量接口,我们用它把钉钉组织树按层级逐步拉取,再与金蝶部门建立映射,避免一次性递归带来的性能与权限风险。

接口能力总览

所属系统:钉钉开放平台(DingTalk Open Platform)
接口路径:topapi/v2/department/listsub
请求方法:POST
认证方式:通过钉钉开放平台的 AppKey/AppSecret 换取 access_token,再以 access_token 鉴权调用;在轻易云里通常配置为「应用凭证」模式,平台负责 token 缓存与刷新。
请求参数:dept_id(父部门 ID,可选,默认 1 即根部门);仅支持查询下一级子部门,不返回孙级及以下节点。
响应结构:JSON 数组,每条记录包含部门主键、名称、父部门 ID、企业群标志等字段。
分页/增量:该接口本身不分页,一次返回父部门下的全部直接子部门;增量依赖客户端按 dept_id 递归轮询。
策略类型:QUERY(只读,不写目标系统);典型调度为 8–22 点每 45 分钟一次(crontab: 5-59/45 8-22 * * *)。

典型字段映射

字段名	类型	含义	实战注意事项
`dept_id`	string	部门唯一标识,作为组织架构主键	metadata 中 `id` 配置为该字段;跨系统映射时务必当作「不可变主键」对待,不要用 `name` 做关联
`name`	string	部门显示名称	metadata 中 `number` 配置为该字段;名称可能被管理员修改,不能作为主键
`parent_id`	string	上级部门 `dept_id`,根部门固定为 1	用于在前端构建组织树;递归拉取时下一轮的请求参数就是上一轮返回的 `dept_id`
`create_dept_group`	string	是否创建企业群	在金蝶侧通常无对应字段,轻易云字段映射器可标记为「忽略」或映射到自定义扩展字段
`auto_add_user`	string	新成员是否自动加入部门群	同上,多为钉钉侧行为字段,集成到金蝶时一般不下发

在轻易云上如何配置

在轻易云数据集成平台里,这个接口通常被封装为「钉钉部门查询」适配器,典型配置路径如下:

在「数据源」中选择 DingTalk,填入应用的 AppKey、AppSecret 与 CorpId;平台会接管 access_token 的获取与失效重试。
选择目标端(本场景为金蝶云星空)后,在策略类型上选 QUERY,并把 dept_id 默认值设为 1。
在「字段映射器」里,把 dept_id 映射到金蝶部门的「编码」字段,把 name 映射到「名称」字段;轻易云会自动处理字符串类型的空值与编码。
如果要按层级递归拉取整棵组织树,可以借助轻易云的「循环调用」或「父子策略编排」:把当前轮返回的 dept_id 队列作为下一轮入参,直到队列为空。
调度配置按业务高峰设置,常见做法是工作时间每 45 分钟一次,夜间降频或停跑。

跨方案实战要点

在多个客户的金蝶–钉钉集成项目里,我们沉淀出以下共性经验:

根部门 ID 是 1:这是钉钉开放平台的硬编码约定,任何递归拉取都要从 dept_id=1 起,不要假设租户根节点是其他值。
接口只返一级,不要强求递归:不要被文档误导以为支持 sub_dept_id_list 全量返回,实际只返回直接子部门;递归逻辑必须由调用方实现。
dept_id 当主键,name 当显示:名称可被管理员随时改,跨系统对照必须用 dept_id 做唯一锚点。
企业群相关字段多为钉钉侧行为:在金蝶侧通常无意义,轻易云字段映射器里建议直接忽略,避免脏数据下发。
调度频率与登录态:45 分钟的间隔既能跟上部门调整,又不会触发钉钉开放平台的频控;夜间停跑可降低 token 失效带来的告警噪音。
错误重试要区分 401 与业务错误:access_token 过期属于可重试错误,轻易云会自动刷新;部门被删除等业务错误应记入死信队列,人工介入。

踩坑复盘

把 name 当主键:某零售企业早期用部门名称做关联,管理员重命名后金蝶侧出现重复部门,后续花了整整两周清洗。稳妥的做法是:任何跨系统关联一律以 dept_id 为锚点,名称仅用于展示。
期望一次拿到整棵树:有客户在测试环境发现接口只返一级,误以为权限问题,反复申请企业级超管;实际是接口设计如此,需要在调用端做 BFS/DFS 递归。
忽略企业群字段的类型差异:create_dept_group 在不同钉钉版本里可能是布尔也可能是字符串 "true"/"false",轻易云字段映射器需开启「类型宽松解析」,否则会写入失败。
调度太密导致 token 抖动:某制造业客户一开始设成每 5 分钟一次,触发了钉钉开放平台的频控,后续 access_token 频繁刷新反而拉低了整体稳定性。
删除部门后的孤儿节点:钉钉侧删除部门后,金蝶侧若没有同步停用,会出现「孤儿部门」;建议在轻易云的策略里加一条「比对删除」逻辑,把目标端已不存在的部门置为禁用。

何时选用

如果业务需要把钉钉组织架构同步到金蝶、构建部门选择器、或做员工归属映射,这个接口是最稳的「只读入口」;但它只支持一级查询,如果要一次拉全树,需要在调用端自己实现递归;若需要写入钉钉部门,请改用 topapi/v2/department/create 等写入类接口。

【查询】钉钉部门接口字段手册权威教程:跨方案聚合实战