金蝶云星空「客户分组查询」接口字段手册权威教程
小满OKKICRM金蝶云星空客户分组executeBillQuery基础资料同步轻易云字段映射手册
这个接口解决什么问题
在 CRM 与 ERP 的基础资料同步场景里,「客户分组」是把客户做层级化分类(行业、区域、规模)的核心主数据。该接口通过金蝶云星空的 executeBillQuery 批量拉取 AMB_CustomerGroup 表单下的客户分组,典型用途包括:CRM 客户分类与 ERP 客户分组对照、客户档案分类同步、跨系统的客户分层管理。
接口能力总览
- 认证方式:金蝶 WebAPI 标准的 Cookie/Session 鉴权,通常需要在前置的登录接口换取会话。
- 请求结构:
POST executeBillQuery,请求体为 JSON,关键参数包括FormId(固定为AMB_CustomerGroup)、FieldKeys、FilterString、Limit、StartRow、TopRowCount。 - 响应结构:返回二维数组形式的记录集,每行对应一个客户分组,字段顺序与
FieldKeys一致。 - 分页模式:通过
Limit + StartRow翻页,Limit通常以{{PAGINATION_PAGE_SIZE}}变量注入,推荐 2000/页以平衡吞吐与稳定性。 - 增量模式:利用
FilterString过滤FModifyDate > 上次同步时间,可实现按修改时间增量;为防止漏单,稳妥做法是叠加FCreateDate条件并定期做全量对账。
典型字段映射
| 字段名 | 类型 | 含义 | 实战注意事项 |
|---|---|---|---|
| FID | string | 金蝶内部主键,客户分组唯一标识 | 用于系统内部引用,也是 FParentId 关联的锚点 |
| FNumber | string | 业务编码,metadata 中 id/number 均指向它 | 跨系统映射的主用键,CRM 侧建议以 code 字段承载 |
| FName | string | 显示名称 | 用于 UI 展示,集成时注意多语言/编码差异 |
| FParentId | string | 上级分组 FID,根节点常为空或 0 | 构建树形层级必备字段,集成顺序错误会导致孤儿节点 |
在轻易云上如何配置
在轻易云数据集成平台里,这套金蝶查询接口通常被封装为一个金蝶云星空适配器,源端的 AMB_CustomerGroup 数据对象对应平台的「金蝶客户分组」模型。配置时通常这样处理:在数据源选择「金蝶云星空—基础资料查询」模板,把 FormId 设为 AMB_CustomerGroup,把分页参数接入平台的 {{PAGINATION_PAGE_SIZE}} 与 {{PAGINATION_START_ROW}} 变量。字段映射器会自动把 FNumber 映射为下游的分组编码字段,把 FParentId 映射为父分组字段,目标端常配置为「写入空操作」,使其成为纯查询策略,方便其他写入策略引用主数据。
跨方案实战要点
- metadata 中 id 与 number 都指向 FNumber:这是金蝶基础资料的常见约定,跨系统对账时务必以 FNumber 为唯一键,避免与 FID 混用导致重复数据。
- 树形结构必须按层级顺序处理:真实场景中,我们通常先在内存里建好
FID → Node的 Map,再二次遍历挂父子关系,根节点判定为FParentId为空/0/"0"。 - 增量条件选 FModifyDate 更稳妥:用修改时间做增量比创建时间更安全,能覆盖修改名称、移动分组等场景,但要配合定期全量对账兜底。
- 分页大小不要贪大:单页超过 5000 在大数据量下易超时,2000 是一个比较安全的甜点值。
- FilterString 注意转义:分组名称里若含特殊字符(如
'、&),要预先转义,否则整批查询会 500。 - 定时任务安排在业务低峰:日终后、凌晨业务空闲时执行,可减少金蝶侧锁表与限流压力。
踩坑复盘
- 坑1:根节点判定差异。有的环境根节点的
FParentId是空字符串,有的环境是"0",有的甚至等于自身 FID。稳妥做法是三态都判空或等于 0,缺一不可。 - 坑2:增量漏单。仅按
FModifyDate增量时,被禁用/反审核的分组修改时间不更新,会导致下游 CRM 一直保留旧记录。建议每周做一次全量重算或对账。 - 坑3:父子层级死循环。金蝶理论上不会出现自引用,但跨系统写入后如果回写错误,极易产生
A→B→A。检测时若发现FParentId等于自身 FID,直接判为根节点。 - 坑4:编码长度截断。FNumber 在某些版本的字段长度上限为 80 字符,跨系统对接时如果 CRM 侧编码更长会被截断,需要在源端校验。
- 坑5:同名分组混淆。FName 可重名,做幂等写入时不要用名称做主键,必须以 FNumber 为准。
何时选用
适合 CRM 与 ERP 需要做客户分类对齐、做客户分层运营、定期做主数据对账的场景。若仅需单次导入或仅做客户档案而非分组映射,可考虑用更轻的「客户查询」接口替代。
本文为原创内容,转载请注明出处:https://www.qeasy.cloud/insights/engineering/hb-p2-090-ok-copy-2c8f