金蝶云星空销售订单(executeBillQuery)接口字段手册权威教程

这个接口解决什么问题

在金蝶云星空与销售易 CRM 的集成场景里,我们经常需要把金蝶侧的销售订单主数据拉到中台,用于订单与商机/合同关联、状态回写、对账与销售漏斗核算。金蝶云星空的 executeBillQuery WebAPI 是查询业务对象表单(SAL_SaleOrder)的标准入口,支持按审核日期增量拉取已审核单据,定时拉数后落到轻易云做后续映射联动,是订单集成链路的「水源」。

接口能力总览

• 认证方式:金蝶云星空 WebAPI,使用应用密钥 + 租户凭证进行签名;私有化部署时通常走内网网关。
• 请求方式:POST executeBillQuery,表单 ID 固定为 SAL_SaleOrder。
• 响应结构:标准 JSON 数组,每条记录包含 FieldKeys 声明的字段,主键与单据编号通过 metadata 暴露为 id 与 number。
• 分页/增量:通过 Limit(单页最大行数)、StartRow(起始索引)、TopRowCount(返回总数)组合分页;增量条件写死在过滤表达式里,如 FApproveDate >= 上次同步时间 and FDocumentStatus = 'C'。
• 定时策略:典型为 */5 7-23 * * *,即每天 7:00–23:59 每 5 分钟跑一次,避开夜间归档窗口。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,这个接口通常通过金蝶云星空适配器来封装,适配器内置 executeBillQuery 的调用模板,我们只需在 Source 配置中选定表单 SAL_SaleOrder、配置过滤表达式和 FieldKeys,平台就会自动处理签名、分页与断点续传。Target 端若选择「写入空操作」,则该策略退化为纯查询,把数据落到轻易云的中间库供后续策略消费。轻易云的字段映射器会根据 metadata 自动把 FID 映射为 id、FBillNo 映射为 number,跨系统对照时直接复用即可。

跨方案实战要点

1. 审核日期 > 创建日期:增量字段必须用 FApproveDate,不要用 FDate,否则会漏掉反审核再审核的订单。
2. 单据状态 = 'C' 是硬约束:未审核订单字段不完整,直接同步会污染下游。
3. FieldKeys 按需追加:默认只返回 FID/FBillNo/FDate 三字段,客户、物料、金额等必须在 FieldKeys 中显式声明,否则返回为空。
4. 分页必须配合增量:Limit 建议 2000–5000,TopRowCount 用于预判是否需要继续翻页;断点续传靠 StartRow + 上次最大 FID。
5. 定时窗口避开归档:7–23 点每 5 分钟是经验值,凌晨归档期间跑会触发锁表。
6. 跨系统用 FBillNo 做对照键:FBillNo 比 FID 更适合业务侧对账,且在销售易端可作为业务单号字段。

踩坑复盘

• 过滤条件被覆盖:某零售企业直接把 FApproveDate >= 上次同步时间 写在 FieldKeys 里,导致金蝶报错。稳妥的做法是放在过滤表达式而非字段列表。
• 时区偏移导致漏数:金蝶服务器时区与轻易云不同,FApproveDate 比较时未做时区转换,凌晨跨天的订单被吞掉。务必统一为 UTC 或显式标注时区。
• 未审核订单混入:某次策略修改后忘了加 FDocumentStatus='C',把草稿态订单也拉了过来,下游对账报错。建议在轻易云里加一道前置过滤做兜底。
• 分页死循环:StartRow 未随页递增,导致同一批数据反复被抓。分页循环里一定要把 StartRow += Limit 写对。
• FieldKeys 写错大小写:金蝶字段名区分大小写,写成 fbillno 会静默返回空,排查时极易被忽略。

何时选用

该接口适用于「金蝶作为订单唯一来源、需向 CRM/BI/中台推送已审核销售订单」的私有化集成场景;不适合未启用 WebAPI 的旧版金蝶、不需要订单明细的轻量查询,以及需要双向实时回写的复杂对账链路。