金蝶云星空员工查询接口executeBillQuery实战手册：从BD_Empinfo到MES/旺店通的字段映射权威教程

这个接口解决什么问题

在ERP与MES、电商WMS等下游系统集成的场景里,"人员主数据从哪儿来"往往是第一个要回答的问题。金蝶云星空作为组织人事主数据的源头,其员工基础资料(BD_Empinfo)需要被多个下游系统订阅:四化智造MES用员工编码做工序派工与报工、旺店通用业务员编码做采购销售单据的人员对照。executeBillQuery 就是金蝶开放给这些下游的统一查询入口,负责把员工主键、编码、姓名、部门、组织等核心字段稳定地拉出来,供后续策略链调用。

接口能力总览

• 认证方式:金蝶云星空API标准鉴权(AppId + AppSecret + 账套ID + 用户),通过私有化网关调用。
• 请求方式:HTTP POST,Body 为 JSON,核心参数封装在 otherRequest 中。
• 表单ID:固定为 BD_Empinfo(员工基础资料,单表结构,记录粒度为员工级)。
• 分页机制:Limit + StartRow 分页,TopRowCount=0 时接口返回总行数;在轻易云的元数据适配器里通常用 {{PAGINATION_PAGE_SIZE}} 与 {{PAGINATION_START_ROW}} 占位符自动循环翻页。
• 增量模式:基于审核日期 FAuditDate>='{{LAST_SYNC_TIME|datetime}}',轻易云的字段映射器会自动注入上次同步时间戳;也支持按编码、姓名、手机号、部门等条件精准过滤。
• 响应结构:返回员工记录数组,metadata 中 id 指向 FID(主键)、number 指向 FName(姓名)。在真实业务里,建议把 FNumber 作为跨系统对照的业务键,而非 FName。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,金蝶员工查询通常以「金蝶云星空适配器 + 写入空操作」的组合出现,作为整条基础资料同步链路的上游节点。

1. 适配器选择:选用「金蝶云星空 executeBillQuery 适配器」,FormId 填写 BD_Empinfo,平台已封装好分页、FilterString 注入与结果解析逻辑。
2. 字段映射器:在轻易云可视化画布里,把 FID 映射到目标主键、FNumber 映射到 employee_code、FName 映射到 employee_name;FPostDept.FNumber 通过「关联字段展开」节点拆出部门编码。
3. 增量变量:平台内置 LAST_SYNC_TIME 上下文,无需手写SQL,FilterString 直接引用 {{LAST_SYNC_TIME|datetime}} 即可按审核日期增量。
4. 调度策略:常见的 cron 表达式为 * 7-22 * * *(MES场景,工作时段每小时拉取)与 */10 7-23 * * *(旺店通场景,高频短周期);轻易云的调度器对这两个表达式都已原生支持。
5. 目标节点:Target 配置为「写入空操作」,意味着该策略是纯查询,真正的写入由下游 MES/旺店通 的写入策略消费其产出数据。

跨方案实战要点

• FNumber 才是真正的业务键:几乎所有客户方案里,只要把 FName(姓名)当主键做对照,后续必出现重名或人员调动后的关联断裂;统一收敛到 FNumber 后稳定性显著提升。
• 部门字段要拆出 .FNumber:金蝶的 FPostDept 是关联对象,接口默认返回的是对象引用而非编码字符串,务必在 FilterString 或字段映射里显式取 FPostDept.FNumber,否则下游对账会全部失败。
• 多组织靠 FCreateOrgId 隔离:私有化部署常有多账套/多组织,FilterString 加 FORGID.FNumber='xxx' 或映射 FCreateOrgId 即可避免数据串组织。
• 分页要可控:单次 Limit 不建议超过 2000,超过后金蝶侧易超时;轻易云分页器会自动按 TopRowCount 计算总页数,你只需要确认 PageSize 即可。
• 审核日期 vs 修改日期:增量字段优先用 FAuditDate(审核日期),它代表业务侧确认过的时间点,比 FModifyDate 更稳定,避免草稿态数据污染下游。
• 与下游策略强耦合:本接口通常只是上游,真正的价值在与「金蝶部门→MES部门」+「金蝶员工→MES人员」+「金蝶员工→旺店通业务员」等下游策略形成链路;部署时务必确认依赖顺序(sequence A/B)。

踩坑复盘

1. 以姓名为 number 导致重复主键:某零售企业把 FName 配成 metadata.number 后,下游 MES 收到两条同名员工直接去重失败。稳妥做法是 metadata.number 仍用 FName(金蝶侧约定),但跨系统业务键单独用 FNumber 做映射。
2. 部门字段忘了展开 .FNumber:FilterString 写 FPostDept='生产部' 永远查不到,因为实际存储的是对象引用;改成 FPostDept.FNumber='SC001' 即可。
3. 增量时间戳时区错位:金蝶审核日期是东八区,轻易云的 LAST_SYNC_TIME 默认 UTC,跨天调度会出现「拉不到昨天最后几小时数据」;在轻易云变量里加 |datetime 后缀并指定时区即可修复。
4. FCreateOrgId 没配置 fname:默认返回的是组织对象引用而非名称字符串,下游展示时直接打印 [object Object];务必按 FCreateOrgId.fname 取值。
5. 定时任务 7-22 点之外的工单被遗漏:如果工厂有夜班,* 7-22 * * * 会漏掉夜间审核的人员;要么改成 */10 * * * * 全天候拉取,要么在夜班结束后补一次手动同步。

何时选用

该接口适用于「金蝶云星空作为人员主数据源、需要把员工编码/部门/组织稳定同步到MES、旺店通等下游」的私有化集成场景;不适用于需要写入金蝶、需要实时推送(本接口仅查询且依赖轮询)、或金蝶非云星空版本(如EAS、K/3)的项目。