金蝶云星空业务员查询接口（BD_OPERATOR）字段手册权威教程

这个接口解决什么问题

业务员（Salesperson / Operator）是金蝶云星空连接 CRM 与业务单据的关键基础资料。该接口通过 executeBillQuery WebAPI 批量拉取 BD_OPERATOR 表单数据，用于 CRM 用户与金蝶业务员映射、销售订单归属人同步、客户负责人对照、组织架构初始化等场景。在多个真实集成项目里，CRM 与 ERP 的用户主数据不一致是销售链路最大的卡点——业务员缺失或错配会导致订单归属、业绩核算全部失真。本接口是打通 CRM↔ERP 人员主链路的起点。

接口能力总览

• 认证方式：金蝶云星空 WebAPI 采用 appId + appSecret + acctId（账套）签名认证，部分环境支持用户票据登录。
• 请求方法：POST /k3cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.executeBillQuery。
• 请求结构：表单参数（FormId、FieldKeys、FilterString、OrderString、TopRowCount、Limit、StartRow）以 form-data 提交。
• 响应结构：返回 JSON 数组，每个元素包含请求字段；元数据（Metadata）独立配置于轻易云 source-metadata 中。
• 分页模式：基于 StartRow + Limit 偏移分页，循环拉取直至返回行数小于 Limit。
• 增量模式：通过 FilterString 中 FModifyDate>='{{LAST_SYNC_TIME}}' 或 FCreateDate>{{LAST_SYNC_TIME}} 实现，按修改时间或创建时间增量。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里，金蝶云星空业务员查询通常采用以下封装模式：

1. 数据源适配器：选择「金蝶云星空（公有云）」适配器，填写接入点、appId/appSecret、组织编码等认证信息。
2. 表单/接口配置：FormId 填写 BD_OPERATOR，选择 executeBillQuery 操作。
3. 元数据 (source-metadata)：配置 id 字段为 FEntity_FEntryId 或 FOperatorId 组合键；number 字段为 FNumber；request 中按需列出 FieldKeys。
4. 字段映射器：轻易云的字段映射器会自动将金蝶 FName 系列字段（_FName 后缀为显示值、_FNumber 为编码、Id 为对象引用）拆为编码+名称两列，下游可直接绑定。
5. 增量与过滤：在 FilterString 中插入 {{LAST_SYNC_TIME|dateTime}} 占位符，平台调度时自动注入上次同步时间戳。
6. 目标配置：选择「写入空操作」（No-Op），表示纯查询策略，数据进入平台后供下游 CRM 用户映射策略消费。
7. 调度：crontab 表达式可设为 25 3 * * *（每日凌晨）或 0 10 * * 1（每周一上午），按业务量调整。

跨方案实战要点

1. 主键选取要适配多组织：金蝶业务员存在「一人多组织、多类型」的分录结构，单一 FOperatorId 不能保证跨组织唯一。稳妥做法是采用 FEntity_FEntryId 作主键，或用 {{FOperatorId}}{{FBizOrgId}}{{FName}}{{Fdept}} 组合主键。
2. 增量字段首选 FModifyDate，慎用 FCreateDate：FCreateDate 只能捕获新建记录，修改/启用/禁用操作会漏；FModifyDate 覆盖全量变更。
3. 过滤条件三层叠加：启用状态（FForbiddenStatus='0' 或 FIsUse='1'）+ 业务员类型（FOperatorType_ETY='XSY'）+ 业务组织白名单（FBizOrgId.FNumber in (...)）三层同时上，避免拉回已禁用、采购员、跨组织的脏数据。
4. 编码映射优于名称映射：跨系统对接一律使用 FNumber 而非 FName，名称易重名、易改名，编码稳定。
5. 分页参数用平台变量：用 {{PAGINATION_START_ROW}}、{{PAGINATION_PAGE_SIZE}} 而非硬编码，方便调整页大小与断点续传。
6. 业务组织编号是金蝶多组织隔离的核心：未指定 FBizOrgId.FNumber 会拉全集团数据，触发权限报错或数据污染，每个方案都必须在 FilterString 中限定。

踩坑复盘

1. 业务员一查就报错「无权限」——根因：FilterString 没限定 FBizOrgId.FNumber，跨组织数据被云星空拒绝。修：补上业务组织白名单。
2. 同步后 CRM 出现重复用户——根因：主键选用了 FNumber，而同一编码下存在多条分录。修：改用 FEntity_FEntryId 或组合主键，并在下游策略侧去重。
3. 增量漏数据——根因：FilterString 用 FCreateDate 做增量，修改操作不触发创建时间更新。修：切换为 FModifyDate。
4. 拉到已禁用业务员导致下游报错——根因：未过滤禁用状态。修：FilterString 增加 FForbiddenStatus='0'。
5. FieldKeys 写了字段但返回为空——根因：金蝶云星空对未授权字段返回 null，部分自定义字段未在权限列表中。修：在用户授权中勾选对应字段，或从 FieldKeys 中剔除。

何时选用

当业务场景需要在 CRM（金蝶云星空对接的 CRM 如小满 OKKICRM）与 ERP 之间同步销售/业务人员主数据，建立统一的归属人、负责人、业绩核算口径时，选用本接口。典型边界：仅适用于金蝶云星空公有云部署；不写入目标系统，需配合下游「写 CRM 用户」策略使用；不适合实时性要求极高（秒级）的场景，建议分钟级以上的批量同步。