金蝶云星空客户信息查询接口字段手册权威教程

这个接口解决什么问题

在聚水潭与金蝶云星空的供应链集成场景中,客户主数据是销售出库单、退货单、采购单据能够正确找到「收货方」的前提。我们经常遇到:金蝶里的客户改了名称或编码,聚水潭侧还在用旧值,导致下游单据挂错客户、对账对不上。通过 executeBillQuery 把金蝶 BD_Customer 增量拉到中台,即可统一编码对照口径,为后续业务单据的客户映射提供权威源。

接口能力总览

• 认证方式:金蝶云星空基于应用身份认证,需要在轻易云凭证管理处配置 AppId、AppSecret、帐套语言、帐套 ID 等参数,通过 Kingdee.BOS.WebApi.ServicesStub.AuthService.ValidateUser 获取登录票据后调用业务 API。
• 请求结构:核心入参包括 FormId(本接口为 BD_Customer)、FieldKeys(按需声明字段)、FilterString(增量条件)、Limit/StartRow(分页参数)、OrderString。
• 响应结构:返回 JSON 数组,每个元素对应一条客户记录;基础资料类字段以「字段名.FNumber」复合形式返回(例如 FCreateOrgId_FNumber),分录主键以「分录字段_FEntryId」形式返回。
• 分页/增量模式:采用按 FApproveDate>='{{LAST_SYNC_TIME}}' 的增量拉取,结合 Limit+StartRow 实现翻页;典型定时为每 30 分钟在 7–23 点执行。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,该接口被封装为「金蝶云星空查询适配器」,通过可视化配置即可完成接入:

1. 数据源选择:在「数据源」中选择「金蝶云星空」,填入接入地址、帐套信息与认证凭证。
2. API 模板选择:从 API 模板列表里选择「executeBillQuery-客户查询」,FormId 自动填入 BD_Customer。
3. 字段映射器:轻易云的字段映射器会自动读取 metadata,把金蝶字段(如 FCUSTID、FNumber、F_QKMS_JSTBM)与聚水潭侧客户字段建立对照关系;你也可以拖拽自定义映射。
4. 增量策略:在「调度策略」里启用按 FApproveDate 增量,设置执行时段(例如 5-59/30 7-23 * * *)。
5. Target 配置:由于是纯查询策略,Target 选择「写入空操作」,仅做数据落库与触发下游编排。

跨方案实战要点

1. 统一以 FNumber 为业务主键:虽然 FCUSTID 是系统主键,但跨系统对码时编码更稳定,轻易云里也推荐把 FNumber 作为对照键。
2. 必拉 F_QKMS_JSTBM:这是金蝶为聚水潭扩展的对照字段,不拉等于丢掉了「双向定位」能力。
3. 基础资料字段拆解要小心:金蝶返回的是「字段名.FNumber」复合形式,做映射时记得取 .FNumber 后缀,不要把整个对象当字符串塞给目标系统。
4. 多组织字段不要省:FCreateOrgId 与 FUseOrgId 经常不同,只拉其中一个会在跨组织使用时丢单。
5. 增量字段用 FApproveDate 而非 FModifyDate:审核日期更稳定,避免草稿态变更带来抖动。
6. Target 选「空操作」:纯查询策略不要写目标系统,留给编排层触发下游同步更灵活。

踩坑复盘

• 过滤条件里直接拼接时间字符串报错:金蝶要求 ISO 格式且带引号,稳妥的做法是通过轻易云的 {{LAST_SYNC_TIME|datetime}} 占位符自动格式化。
• 分页参数 Limit 过大被服务端截断:金蝶单次返回有上限,轻易云适配器默认会按 2000 行/页拆分,不要手动覆盖成 50000。
• 基础资料字段被当作普通字符串映射:把 FCreateOrgId_FNumber 直接当成字符串塞进去,导致下游系统收到「{Number:001,Name:总仓}」之类的 JSON 字符串。正确做法是在字段映射器里只取 .FNumber。
• 增量字段选错导致漏数据:有客户用了 FModifyDate 做增量,但草稿态修改会被同步触发,产生大量空跑。换成 FApproveDate 后立刻稳定。
• 聚水潭编码字段为空导致下游匹配失败:F_QKMS_JSTBM 在某些历史客户上没有维护,需要在映射里加一个「为空时跳过」的容错分支。

何时选用

该接口适用于「以金蝶云星空为客户主数据权威源、需要把客户信息单向同步到聚水潭或中台、做基础资料对照与业务单据映射」的场景。若需要双向写入或实时事件驱动,建议改用变更通知 + 单据接口组合,而非高频轮询此查询接口。