这个接口解决什么问题

在金蝶云星空与泛微 OA-E9Http 的供应链集成中,终端客户(辅助资料类别 ZDKKH)是客户主数据、销售订单、客户档案中常用的分类字典。该接口通过 executeBillQuery 按分页批量拉取已审核的终端客户字典项,用于 OA 审批流与金蝶客户分类对照、客户属性映射等场景。Target 配置为「写入空操作」,定位为纯查询策略,供下游同步任务消费结果。

接口能力总览

认证方式:金蝶云星空 WebAPI 协议,通常采用应用级 AppId/Secret 签名,接口路径 executeBillQuery。
请求结构:FormId 固定为 BOS_ASSISTANTDATA_DETAIL,Filter 固定为 FId.FNumber in ('ZDKKH') and FDocumentStatus='C',字段选择通过 FieldKeys 控制返回列。
响应结构:JSON 数组,每条记录对应一个辅助资料明细分录,主键为 FEntryID。
分页/增量模式:采用 Limit + StartRow 偏移分页,典型 Limit=1000,StartRow 由 {{PAGINATION_START_ROW}} 占位符动态注入,平台根据上一次响应条数自动计算。
调度策略:真实方案中通常采用 crontab */8 7-23 * * *,白天高频轮询,夜间停跑。

典型字段映射

字段名	类型	业务含义	实战注意事项
FEntryID	string	辅助资料明细分录主键	唯一标识,建议作为下游去重键;`idCheck:false` 不强制唯一校验
FID	string	辅助资料主表主键	与 FEntryID 区别:前者为分录级,后者为主表级
FNumber	string	终端客户业务编码	跨系统映射的关联键,与目标系统编码一一对照
FDataValue	string	终端客户显示名称	用于下拉展示与人工核验
FId_FNumber	string	辅助资料类别编码	本策略固定为 `ZDKKH`,可作为结果校验断言
FDocumentStatus	string	单据审核状态	C=已审核,本策略已硬过滤;暂存(A)/提交中(B)不会出现
FForbidStatus	string	禁用状态	A=启用、F=禁用,字典同步时建议同时过滤 F
FCreateOrgId_FNumber	string	创建组织编码	多组织场景下区分来源组织
FUseOrgId_FNumber	string	使用组织编码	多组织场景下判定可见性,常用于按组织分发
FParentId	string	上级辅助资料主键	支持层级结构,部分终端客户存在父子关系
FSeq	string	显示顺序	决定下拉列表排序
FDescription	string	备注	可选扩展字段
FCreatorId	string	创建人 ID	审计字段,通常不参与业务映射

在轻易云上如何配置

在轻易云数据集成平台里,这个接口通常采用「金蝶云星空查询适配器 + 空操作写入适配器」的组合:

适配器选型:源端选用金蝶云星空 executeBillQuery 适配器,FormId 预置为 BOS_ASSISTANTDATA_DETAIL,Filter 直接复用过滤表达式。
分页器:平台的分页器会自动管理 StartRow 与 Limit,每次调用结束后依据返回条数推进下一页,空响应判定为拉取完成。
字段映射器:轻易云的字段映射器会按 FieldKeys 自动生成目标字段清单,FNumber、FDataValue 通常映射为 terminal_customer_code、terminal_customer_name。
空操作 Target:Target 选择「空操作」即代表纯查询模式,结果暂存于平台中转区供后续策略消费,也可直接推送至数据仓库。
调度器:crontab 表达式可在平台调度面板中可视化配置,无需手写。

跨方案实战要点

过滤条件必须双锁定:同时过滤 FId.FNumber in ('ZDKKH') 与 FDocumentStatus='C',避免拉回未审核或非本类别脏数据。
FNumber 作为黄金关联键:在多套供应链方案里,跨系统匹配都优先用 FNumber 而非名称,因为名称可能被改而编码稳定。
FForbidStatus 不可忽视:即便单据已审核,被禁用(F)的字典仍可能下发给业务系统,真实场景中需要再叠加一层过滤。
分页条数不宜过大:Limit=1000 是较稳的选择,过大易触发金蝶网关超时;在多组织场景下可适度下调。
多组织区分要看 FUseOrgId:同一编码在不同组织下含义可能不同,下游分发时务必按使用组织拆分。
审计字段慎用:FCreateOrgId、FUseOrgId、FDescription 这类字段不应作为主数据映射依据,只用于追溯。

踩坑复盘

坑一:名称改了导致下游错位。某零售企业曾因销售部门直接在金蝶改 FDataValue,而下游 OA 仍按名称匹配,造成分类错乱。稳妥做法是始终以 FNumber 做关联键,名称仅做展示。
坑二:未审核数据被拉取。若忘记硬过滤 FDocumentStatus='C',会出现大量草稿态字典,后续启用后产生双版本。务必在 Filter 中明确写入。
坑三:FEntryID 与 FID 混用。明细级主键 FEntryID 与主表级主键 FID 在跨表关联时差异很大,曾有方案把它俩当同一字段去重,导致漏数。要按业务粒度选择。
坑四:分页死循环。当返回空数组时未及时终止分页,会无限循环拉取。在轻易云里通常由分页器自动判定终止,但自定义脚本方案需显式判断。
坑五:禁用字典仍在使用。已审核但 FForbidStatus='F' 的字典如果照常下发,业务系统下拉会出现「幽灵选项」。建议在轻易云字段映射器里加一个条件过滤步骤。

何时选用

适用场景:供应链集成中需要从金蝶云星空拉取终端客户、销售渠道、客户属性等辅助资料字典,并同步到 OA、CRM 或数据仓库。边界:本策略仅适用于辅助资料明细表,不适合直接查询客户档案主表;若需实时单条查询,应改用 executeBillQueryById 或 view 接口。

金蝶云星空终端客户辅助资料查询接口字段手册