这个接口解决什么问题

在供应链集成场景里，客户主数据是销售订单、出库单、退货单等所有下游单据的「地基」。当我们要把金蝶云星空作为 ERP 主数据源，把客户档案同步到电商前端、OA 审批系统或其他业务系统时，第一个必须打通的接口就是「查询金蝶客户」。本接口通过金蝶云星空的 executeBillQuery 能力，按主键、编码、名称、组织、外部码等条件批量拉取客户档案，作为跨系统客户编码对照与单据匹配的基准数据源。

接口能力总览

所属系统：金蝶云星空（Kingdee Cloud）
业务对象表单：BD_Customer（基础资料-客户）
API：executeBillQuery，方法 POST，效果 QUERY
认证方式：金蝶云星空标准的用户身份与账套鉴权，私有化部署下需配置内网访问通道
请求结构：表单 ID FormId + 字段集合 FieldKeys + 过滤条件 FilterString + 分页参数 Limit/StartRow/TopRowCount
响应结构：JSON 数组，每行一条客户记录，字段顺序与 FieldKeys 一致；autoFillResponse: true 时由系统自动补充响应字段
分页模式：Limit（页大小，通常 2000）+ StartRow（起始行索引），通过游标式翻页
增量模式：FilterString 中按审核时间过滤，形如 FApproveDate>='{{LAST_SYNC_TIME|datetime}}'，结合元数据的 idCheck: false 实现按需拉取
调度：在多个客户方案中，常见的执行节奏是「每 5 分钟（7:00–23:59）」或「每 8 分钟（7:00–23:59）」，业务闲时关闭

典型字段映射

字段名	中文名	类型	业务含义	实战注意事项
FCUSTID	实体主键	string	金蝶系统内客户唯一标识，跨系统关联与去重主键	系统内 ID，跨系统集成时不建议直接做映射键，建议用 `FNumber` 或 `F_352_waibuma`
FNumber	编码	string	客户业务编码，组织内/跨系统引用的主业务标识	metadata 中 `number` 字段；跨系统对照的首选键
FName	名称	string	客户全称，用于界面展示与人工核对	名称易重名，做匹配时必须与编码组合
FCreateOrgId_FNumber	创建组织	string	客户创建所属组织编码	多组织场景下区分数据归属
FUseOrgId_FNumber	使用组织	string	客户使用所属组织编码，多组织场景下的归属组织	必填；FilterString 常按此字段限定查询范围
FDescription	描述	string	客户描述或备注	长度有限，不放敏感信息
FCustTypeId_FNumber	客户类别	string	客户分类编码（零售/批发/企业等）	引用型，指向客户类别基础资料
FGroup_FNumber	客户分组	string	客户分组编码	用于按区域、渠道等维度分类
FSALDEPTID_FNumber	销售部门	string	负责客户的销售部门编码	业绩统计与归属判定常用
FSELLER_FNumber	销售员	string	负责客户的销售员编码	客户归属与业绩考核
FSETTLETYPEID_FNumber	结算方式	string	结算方式编码（现结/月结/预付款等）	影响后续收款流程
FRECCONDITIONID_FNumber	收款条件	string	收款条件编码	与信用额度、账期联动
FShortName	简称	string	客户简称	单据与报表空间受限时展示
FADDRESS	地址	string	联系地址	物流与开票都需使用
FTEL	电话	string	联系电话	频繁更新，建议做单独校验
FFAX	传真	string	传真号码	老客户才用，新客户多为空
FCompanyClassify_FNumber	公司类别	string	公司类别编码（一般纳税人/小规模等）	直接影响开票规则
FINVOICETITLE	发票抬头	string	开票用发票抬头	与税务信息强绑定
FINVOICEBANKACCOUNT	银行账号	string	开票用银行账号	敏感字段，注意脱敏
FCURRENCYID_FNumber	币别	string	默认交易币别编码	多币种场景必看
FTRADINGCURRID	结算币别	string	结算币别标识	与交易币别可以不一致
F_352_waibuma	外部码	string	外部系统编码，与管易等系统客户编码映射	跨系统集成的关键对照字段；前缀 `F_352_` 表示是自定义扩展字段

在轻易云上如何配置

在轻易云数据集成平台里，金蝶云星空客户查询通常被封装为「金蝶适配器」的一个查询动作，配置链路分三步：

数据源选型：在「数据源」中选择「金蝶云星空」，填入私有化部署的访问地址与账套信息；适配器内部已封装好 executeBillQuery 的鉴权与请求拼装。
接口动作配置：新建策略时选择「查询金蝶客户」模板，FormId 自动填 BD_Customer，FieldKeys 默认勾选全部 22 个核心字段。FilterString 可视时间变量（LAST_SYNC_TIME）做增量条件。
字段映射器：轻易云的字段映射器会把金蝶的 FNumber、FName、F_352_waibuma 等字段自动映射到目标系统（管易云、泛微 OA 等）的客户编码、客户名称、外部码。映射完成后，可在「预览」中抽样核对主键与名称是否一致，再启用调度。

Target 端如果配置为「写入空操作」，则本策略就是纯查询策略，只拉数据不做落库，常用于给下游同步策略提供主数据基准。

跨方案实战要点

从多个真实集成方案（管易云供应链集成、泛微 OA-E9 集成等）里，我们提炼出以下共性经验：

以 FNumber 作为跨系统主映射键：FCUSTID 在跨系统集成中不适合直接做映射键，FNumber 是组织内与跨系统都稳定的主业务标识。
F_352_waibuma 是跨系统集成的关键字段：它的值通常维护为外部系统（如管易云）的客户编码，做单据匹配时优先用它。
多组织场景必须按 FUseOrgId_FNumber 过滤：否则会把其他组织的客户拉过来，导致映射错乱。
增量条件用 FApproveDate 而不是 FModifyDate：审核时间更稳定，避免中间态数据被同步出去。
_FNumber 后缀字段都是引用型：响应里返回的是编码而不是主键 ID，下游系统需要用编码去解析对应的基础资料。
调度窗口按业务时段收敛：7:00–23:00 是常见做法，业务闲时关掉，省资源也减少对账套的冲击。

踩坑复盘

踩坑 1：用 FCUSTID 做跨系统主键 真实场景中，某零售企业直接把金蝶的 FCUSTID 存到管易云的客户关联字段，结果金蝶账套一旦做主键重整或迁移，外部系统的关联就全失效。稳妥的做法是以 FNumber 为主、F_352_waibuma 为辅做双向映射。
踩坑 2：没按使用组织过滤，把全集团的客户都拉过来 多组织架构下，某个销售组织的客户不应被同步到其他组织。一旦不过滤，单次查询可能拉回几十万条客户记录，触发接口限流。稳妥的做法是在 FilterString 里加 FUseOrgId.FNumber='具体组织编码'。
踩坑 3：增量字段用错导致漏数据或重数据 有方案用 FModifyDate 做增量，但金蝶审核中的客户 FModifyDate 会被反复改写，导致同一条客户被多次同步。稳妥的做法是用 FApproveDate，且配合 idCheck: false 让系统按需重新拉取。
踩坑 4：_FNumber 字段被当成主键 ID 用 工程师看到 FSELLER_FNumber 返回一串数字就以为是员工 ID，实际上它是员工编码。下游做反查时拿编码去匹配基础资料才正确。
踩坑 5：F_352_waibuma 没维护导致主数据对不上 外部码依赖人工在金蝶端维护，部分老客户漏填，集成跑起来后下游系统找不到对应客户。稳妥的做法是增加「外部码缺失报表」，定期清理。

何时选用

本接口是供应链集成中客户主数据的「标配」，只要存在「金蝶云星空 ↔ 任意业务系统」的客户档案同步或单据客户字段对照需求，就应该优先使用 BD_Customer + executeBillQuery。不适用场景是：仅需做单据级客户匹配（可直接走单据接口的客户字段）、或客户数据来源不是金蝶云星空（如用其他 ERP）。

金蝶云星空客户查询接口字段手册：executeBillQuery 实战权威教程