金蝶云星空客户查询接口字段手册权威教程（executeBillQuery / BD_Customer）

这个接口解决什么问题

在吉客云与金蝶云星空的供应链集成里,客户主数据是订单、应收、开票业务的根基。该接口通过金蝶云星空 executeBillQuery WebAPI,按分页批量拉取 BD_Customer(客户)主数据,典型用途包括:吉客云渠道/客户与金蝶客户档案同步、跨系统客户编码映射、销售组织与销售员归属下发,使下游模块有可靠的主数据基底。

接口能力总览

• 认证方式:金蝶云星空 WebAPI 第三方登录/集成登录,需在轻易云适配器中配置数据中心、用户、密钥、应用 ID 等信息。
• 请求方式:POST 到 executeBillQuery,固定 FormId = BD_Customer。
• 请求参数:Limit(默认 2000)、StartRow(从 0 开始)、TopRowCount(可选,返回总行数)、FilterString(过滤条件)、FieldKeys(字段列表,如 FCUSTID,FNUMBER,FNAME,...)。
• 响应结构:返回二维表行集,每行一个客户档案。metadata 中 id 字段为 FCUSTID、number 为 FNumber。
• 分页/增量模式:典型做法是用 FApproveDate >= '{{LAST_SYNC_TIME|dateTime}}' 做增量,结合 StartRow/Limit 分页拉完一页后再 StartRow += Limit,直至返回行数小于 Limit。
• 策略类型:QUERY_ONLY,Target 配置为「写入空操作」,策略本身只负责取数,落库与对照交给下游策略。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,金蝶云星空通常以「适配器 + 元数据」的方式封装:适配器负责 executeBillQuery 的鉴权、URL 拼装与分页迭代,源端元数据 source-metedata/金蝶客户查询_source.json 描述 BD_Customer 的字段集与主键(id=FCUSTID,number=FNumber)。Target 元数据设为「写入空操作」,策略类型为 QUERY_ONLY。

字段映射阶段,轻易云的字段映射器会自动加载源端所有字段,你可以直接把 FCUSTID 映射到目标系统的 customer_id、FNumber 映射到 customer_code,而 _FNumber 后缀的基础资料类字段(组织、客户类别、销售员等)通常映射为目标侧的编码字段,运行期由轻易云再按需转换为名称展示。定时任务可按客户业务节奏配置,如 3-59/20 7-22 * * *(每 20 分钟,7:00–22:00 执行)。

跨方案实战要点

1. 主键优先用 FCUSTID,编码用 FNumber 做跨系统对接:金蝶内部主键稳定不变,FNumber 才是业务编码,与吉客云渠道编码做映射时一定要走 FNumber。
2. 过滤条件一定要带上 FUseOrgId 和 FApproveDate:多组织客户必须先按使用组织收敛,否则会拉出全集团客户;增量则依赖审核日期,未审核的客户即使已建档也不应下发。
3. 分页按 StartRow/Limit 推进,不要用 TopRowCount 当结束条件:TopRowCount 是总行数,容易让循环提前结束;稳妥的做法是循环到返回行数 < Limit 才视为拉完。
4. 基础资料类字段全部以「_FNumber」后缀提供编码:组织、客户类别、销售员、价目表等都是关联字段,轻易云拿到的就是编码,名称需要在目标系统二次解析或在下拉辅助表里维护。
5. 开票信息与收款银行是两套独立字段集:开票走 FINVOICE* 系列,收款走 FBANK*/FACCOUNTNAME 系列,做开票接口或打款接口时千万不要混用。
6. 价目表与折扣表必须配合客户生效版本:FDISCOUNTLISTID_FNumber、FPRICELISTID_FNumber 取到的是编码,但下单时还会校验版本与有效期,轻易云侧建议加一道客户档案完整性校验。

踩坑复盘

• 翻车一:FilterString 写错语法导致整页为空。金蝶过滤条件要严格按 FUseOrgId.FNumber = '100' and FApproveDate>='2024-01-01 00:00:00' 这种写法,字符串要用单引号包起来,日期要写完整。
• 翻车二:增量起点选错字段。用 FModifyDate 做增量时,审核未通过的数据也会被变更,容易把无效变更同步下去;用 FApproveDate 更稳妥。
• 翻车三:默认账户不唯一。一个客户下多个银行账户时,FISDEFAULT1='1' 未必只有一条,轻易云侧要按 (客户编码 + 默认标志) 做去重,避免落库冲突。
• 翻车四:客商一体导致供应商资料被覆盖。FSUPPLIERID_FNumber 关联到供应商档案时,如果目标系统同时维护了供应商,容易反向覆盖;稳妥做法是在写入前先判断 FCustTypeId 是否包含「客商」标识。
• 翻车五:FieldKeys 没带 FCUSTID。有些方案只取业务字段、漏掉主键,结果目标系统落库时找不到主键导致重复插入,轻易云的字段映射器默认会保留主键,不要再手贱删掉。

何时选用

当业务需要把金蝶云星空的客户主数据(档案、分类、组织归属、开票与银行信息)同步到吉客云、电商中台或下游 ERP/CRM 时,选用本接口;不适用于写入客户档案、删除客户、审核客户的写操作,这类需求要走 save/submit/audit 等写接口。