金蝶云星空客户联系人查询接口字段手册权威教程

这个接口解决什么问题

在零售、批发、服务等行业里,客户联系人散落在 CRM(如小满 OKKICRM)与 ERP(金蝶云星空)两套系统。我们需要在两边建立一份统一的「联系人档案」:把金蝶里的联系人主数据按增量方式拉到 CRM,或反过来比对 CRM 与 ERP 的联系人是否一致。这个接口正是为这种场景而生——通过金蝶的 executeBillQuery WebAPI,按审核日期增量分页拉取 BD_CommonContact(通用联系人)主数据,为后续的同步、对照、关联关系维护提供数据底座。

接口能力总览

• 所属系统:金蝶云星空(Kingdee.Cloud),基础资料域。
• 接口入口:executeBillQuery WebAPI(POST)。
• 查询表单:BD_CommonContact(通用联系人)。
• 请求参数:Limit(分页大小)、StartRow(起始行)、TopRowCount(总行数,默认 0)、FilterString(过滤条件)、FieldKeys(返回字段集合)、FormId(固定 BD_CommonContact)。
• 响应结构:金蝶标准 ListView,内含若干行记录,每行以 FieldKeys 指定字段为列。
• 分页模式:基于 StartRow + Limit 的传统分页,通过 {{PAGINATION_START_ROW}} 与 {{PAGINATION_PAGE_SIZE}} 占位符驱动。
• 增量模式:默认按 FApproveDate >= '{{LAST_SYNC_TIME|dateTime}}' 过滤,定时任务每 10 分钟执行,工作时段 8:00–20:00。
• 策略类型:QUERY_ONLY,Target 端为「写入空操作」,纯查询。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,这个接口被封装成金蝶云星空适配器中的一个「查询策略」模板。配置时通常按以下几步:

1. 选源系统:金蝶云星空,选择 executeBillQuery 适配器。
2. 填 FormId:BD_CommonContact,平台会回填默认字段集。
3. FieldKeys 选择:在轻易云字段映射器里勾选需要返回的字段,平台会自动按 FieldKeys 拼装请求体。
4. FilterString 配置:默认模板已带 FApproveDate 增量过滤,替换为平台的 {{LAST_SYNC_TIME|dateTime}} 占位符即可。
5. 分页设置:StartRow 与 Limit 分别绑定 {{PAGINATION_START_ROW}} 与 {{PAGINATION_PAGE_SIZE}},平台调度器会自动翻页直到返回空集。
6. Target 端:选「写入空操作」,本策略只产出数据快照,不落目标。
7. 定时:crontab */10 8-20 * * *,工作时段每 10 分钟拉取一次。

跨方案实战要点

1. 以 FNumber 为锚点做跨系统对照:FCUSTID 是金蝶内部主键,跨系统迁移后会失效;FNumber 作为业务编码稳定性更高。
2. 增量字段优先用审核日期而非修改日期:FApproveDate 比 FModifyDate 更能反映业务生效状态,避免抓到「草稿态」联系人。
3. 多组织场景一定要带 UseOrgId:不同使用组织看到的联系人列表不同,漏带会导致数据缺失。
4. FGroup 的编码与名称要同时拉:编码稳定但不可读,名称可读但可能被改,两者结合既稳定又便于排查。
5. 分页大小不要贪大:金蝶 WebAPI 单页过大易超时,真实场景中 PageSize 控制在 500–1000 比较稳妥。
6. Target 写入空操作不要误改成真实目标:本策略定位是「查询快照」,一旦挂上真实目标写入,会出现重复落库。

踩坑复盘

1. FilterString 时间格式问题:金蝶期望 yyyy-MM-dd HH:mm:ss,如果用 UTC 或带时区的 ISO 字符串会直接返回空集。稳妥做法是用平台变量 {{LAST_SYNC_TIME|dateTime}} 由轻易云统一格式化。
2. 联系人下挂客户被过滤:联系人没有直接的「客户编码」字段,而是通过关联关系带出 FCustTypeId、FGroup 等。若只想取某客户下的联系人,需要在 FilterString 里加 FCUSTID IN (...) 子查询,而不是直接 FCUST='xxx'。
3. 分页死循环:当 StartRow 越界时金蝶会返回空集,但部分版本会返回错误码。轻易云会自动根据返回行数判定结束,但若自定义脚本里把空集当成异常处理,就会陷入死循环。
4. FIsTrade 类型漂移:不同金蝶版本返回 true/false、1/0、True/False 都见过,集成层要做归一化。
5. 多语言环境 FName 编码:客户切到繁体或英文环境后,FName 可能包含 emoji 或全角字符,CRM 端入库前要做 UTF-8 校验,避免乱码。

何时选用

适用于 CRM 与金蝶云星空之间,需要对客户联系人做单向拉取、对照、镜像的场景,例如 CRM 联系人档案补全、ERP 联系人变更回流通知、联系人-客户关联关系重建。不适用于联系人写入金蝶、双向实时同步(那需要搭配写入策略)以及非金蝶 ERP 系统的联系人集成。