轻易云
注册体验

金蝶云星空「客户分组查询」接口字段手册权威教程

· 何金辉· 工程最佳实践· 58 次浏览· 约 4 分钟读完
小满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 条件并定期做全量对账。

典型字段映射

字段名类型含义实战注意事项
FIDstring金蝶内部主键,客户分组唯一标识用于系统内部引用,也是 FParentId 关联的锚点
FNumberstring业务编码,metadata 中 id/number 均指向它跨系统映射的主用键,CRM 侧建议以 code 字段承载
FNamestring显示名称用于 UI 展示,集成时注意多语言/编码差异
FParentIdstring上级分组 FID,根节点常为空或 0构建树形层级必备字段,集成顺序错误会导致孤儿节点

在轻易云上如何配置

在轻易云数据集成平台里,这套金蝶查询接口通常被封装为一个金蝶云星空适配器,源端的 AMB_CustomerGroup 数据对象对应平台的「金蝶客户分组」模型。配置时通常这样处理:在数据源选择「金蝶云星空—基础资料查询」模板,把 FormId 设为 AMB_CustomerGroup,把分页参数接入平台的 {{PAGINATION_PAGE_SIZE}} 与 {{PAGINATION_START_ROW}} 变量。字段映射器会自动把 FNumber 映射为下游的分组编码字段,把 FParentId 映射为父分组字段,目标端常配置为「写入空操作」,使其成为纯查询策略,方便其他写入策略引用主数据。

跨方案实战要点

  1. metadata 中 id 与 number 都指向 FNumber:这是金蝶基础资料的常见约定,跨系统对账时务必以 FNumber 为唯一键,避免与 FID 混用导致重复数据。
  2. 树形结构必须按层级顺序处理:真实场景中,我们通常先在内存里建好 FID → Node 的 Map,再二次遍历挂父子关系,根节点判定为 FParentId 为空/0/"0"。
  3. 增量条件选 FModifyDate 更稳妥:用修改时间做增量比创建时间更安全,能覆盖修改名称、移动分组等场景,但要配合定期全量对账兜底。
  4. 分页大小不要贪大:单页超过 5000 在大数据量下易超时,2000 是一个比较安全的甜点值。
  5. FilterString 注意转义:分组名称里若含特殊字符(如 '、&),要预先转义,否则整批查询会 500。
  6. 定时任务安排在业务低峰:日终后、凌晨业务空闲时执行,可减少金蝶侧锁表与限流压力。

踩坑复盘

  • 坑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

评论