金蝶云星空部门查询接口字段手册权威教程

这个接口解决什么问题

在金蝶云星空与钉钉的集成场景里,部门主数据是组织架构同步的基石。金蝶云星空的 ExecuteBillQuery 接口(表单 BD_Department)用于查询部门主数据,为金蝶-钉钉部门对照、员工归属映射、审批流部门选择提供数据源。该接口采用纯查询模式,目标端配置为空操作,不写回任何系统,常作为下游同步策略(如部门写入钉钉)的可信数据源。

接口能力总览

• 认证方式:基于金蝶云星空的 API 网关鉴权,需传入合法的应用票据与用户令牌,轻易云适配器已封装签名逻辑。
• 请求方式:HTTP POST,Body 为 JSON,核心参数 FormId 固定为 BD_Department。
• 响应结构:标准金蝶 Result 响应,业务数据封装在 Result.Result.Results 数组中,每行对应一条部门记录。
• 分页机制:通过 Limit(每页行数)、StartRow(起始索引)、TopRowCount(总行数)实现分页,轻易云默认每页 2000 条,自动翻页合并。
• 增量模式:采用审核日期增量,FilterString 形如 FAuditDate>='{{LAST_SYNC_TIME|dateTime}}',配合使用组织编码 in ('04','0402','0401') 进行多组织过滤。
• 执行周期:定时任务每 2 小时执行(* */2 * * *),契合主数据变更频率。

典型字段映射

在轻易云的字段映射器里,这些字段会被自动注册为可拖拽的源字段,工程师只需在画布上完成「金蝶字段 → 钉钉字段」的连线即可。

在轻易云上如何配置

轻易云对金蝶云星空的 ExecuteBillQuery 接口做了深度封装,具体配置路径如下:

1. 适配器选择:在数据源配置中选择「金蝶云星空」适配器,填入服务地址、应用 ID 与密钥。
2. 表单 ID:填入 BD_Department,轻易云会自动拉取该表单的元数据与字段列表。
3. 主键与编码字段:在 metadata 配置中,将 id 指向 FDEPTID,number 指向 FName,轻易云据此生成对照关系。
4. 增量过滤:在 FilterString 模板中使用 {{LAST_SYNC_TIME|dateTime}} 占位符,轻易云会在每次执行时自动替换为上次成功同步时间。
5. 目标端空操作:策略类型选择 QUERY,目标端配置为「写入空操作」,查询结果仅缓存于轻易云数据中台,供下游策略消费。
6. 定时调度:配置 crontab 为 * */2 * * *,轻易云调度器会按周期拉取最新数据。

跨方案实战要点

从多个客户的金蝶-钉钉集成方案中,我们提炼出以下共性经验:

1. 主键优先:始终以 FDEPTID 作为跨系统唯一标识,不要用 FName,因为部门名称存在重名可能。
2. 编码对齐:金蝶的 FNumber 与钉钉的部门编码需建立一一映射,避免下游同步时出现重复创建。
3. 多组织过滤:FilterString 中务必带上 FUseOrgId.FNumber in (...) 条件,否则会拉取全集团部门,导致数据量爆炸。
4. 增量字段选择:优先使用 FAuditDate 而非 FModifyDate,因为审核日期更稳定,未审核的记录不应进入下游。
5. 分页上限:金蝶接口单次返回上限通常为 2000 行,轻易云自动翻页,但仍需在监控中关注总行数是否异常。
6. 层级字段利用:FFullName 含完整路径,可直接用于钉钉组织架构的层级展示,无需在下游拼接。

踩坑复盘

1. 过滤条件失效:曾有客户因 FilterString 中使用 FUseOrgId.FNumber 而非 FUseOrgId,导致多组织过滤无效,拉取了全量部门。稳妥的做法是先用轻易云的「测试执行」验证返回行数是否符合预期。
2. 增量时间漂移:{{LAST_SYNC_TIME|dateTime}} 默认按 UTC 时区替换,若金蝶服务器在东八区,会出现 8 小时偏差。建议在轻易云中显式配置时区或改用 FAuditDate>='{{LAST_SYNC_TIME|dateTime:+08:00}}'。
3. 主键冲突:金蝶的 FDEPTID 在多组织下可能重复,需结合 FUseOrgId 组成复合主键,否则下游钉钉部门会出现覆盖。
4. 分页漏数据:金蝶接口在并发场景下可能因 StartRow 偏移导致漏页,轻易云的翻页器已做幂等处理,但仍建议在首次全量同步时关闭增量,跑完后再切换。
5. 空组织名称:FUseOrgId_FName 在某些历史数据中为空,集成映射时需做空值兜底,否则钉钉侧会显示「undefined」。

何时选用

该接口适用于金蝶云星空与钉钉(或轻易云中台)之间的组织架构同步、部门对照表维护、员工归属映射等场景。若业务仅需单次全量拉取,建议直接使用金蝶后台导出;若需持续增量同步,ExecuteBillQuery + 轻易云 QUERY 模式是最稳妥的组合。