这个接口解决什么问题

在旺店通与金蝶云星空的供应链集成场景中，销售订单是核心业务对象。该接口（executeBillQuery，表单ID：SAL_SaleOrder）用于从金蝶云星空批量查询未关闭的销售订单，作为下游同步策略（如「云星空销售订单>旺店通销售订单」）的源数据支撑，典型用途包括订单主数据同步、状态跟踪、跨系统对账等。

接口能力总览

认证方式：金蝶云星空标准 API 鉴权，需配置数据中心账号与第三方系统接入授权。
请求方式：POST，调用 executeBillQuery 接口。
请求参数：通过 otherRequest 传入，包含 FormId（固定为 SAL_SaleOrder）、FilterString、Limit（默认 2000）、StartRow（默认 0）、FieldKeys 等。
响应结构：返回主表与明细表扁平化后的宽表，每条记录对应一个订单行项目。
增量模式：通过 FilterString 中的 FApproveDate>='{{LAST_SYNC_TIME|dateTime}}' 实现按审核日期增量筛选。
分页模式：基于 Limit + StartRow 循环拉取，直至返回行数小于 Limit。
过滤规则：固定追加 FCloseStatus='A'，仅查询未关闭订单。
定时策略：通常配置为每 5 分钟执行一次，运行时段 6:00–22:00。

典型字段映射

字段名	类型	含义	实战注意事项
FSaleOrderEntry_FEntryID	string	明细行ID，行级主键	metadata 中 `id` 字段配置为此值；用于行项目维度的唯一标识
FID	string	单据内码，单据级主键	同一订单的多行明细共享相同 FID；若按订单维度处理需去重
FBillNo	string	单据编号	metadata 中 `number` 字段配置为此值；可作为与旺店通订单编号的跨系统对照键
FCloseStatus	string	关闭状态	固定过滤 'A'（活动）；其他值（如 'B' 已关闭）已被 FilterString 排除
FMaterialId_Fnumber	string	物料编码	用于与旺店通货品主数据对照，是跨系统商品映射的关键字段
FEntryTaxRate	string	税率%	行项目税率，用于税额计算与价税合计

在轻易云上如何配置

在轻易云数据集成平台中，金蝶云星空的销售订单查询通常通过「金蝶云星空适配器」封装。该适配器已内置 executeBillQuery 调用模板，配置时只需指定表单ID SAL_SaleOrder，平台会自动构造请求体。

关键配置步骤：

在轻易云的「数据源」管理中选择金蝶云星空适配器，填入数据中心地址与授权凭证。
在「查询策略」中新建方案，策略类型选 QUERY_ONLY（仅查询）。
设置 FilterString 模板：FApproveDate>='{{LAST_SYNC_TIME|dateTime}}' and FCloseStatus='A'。
在 metadata 中将 id 映射到 FSaleOrderEntry_FEntryID，number 映射到 FBillNo。
Target 配置为「写入空操作」，表明该策略为纯查询，不写入目标系统。
配置定时任务：crontab */5 6-22 * * *，每 5 分钟拉取一次。

轻易云的字段映射器会自动识别金蝶返回的扁平化结构，并按 metadata 中的 id/number 字段标记主键与编码，方便下游策略引用。

跨方案实战要点

在多个客户项目中，我们提炼出以下共性经验：

主键层级必须区分清楚：FID 是单据级主键，FSaleOrderEntry_FEntryID 是行级主键。若下游需要行项目粒度的数据（如发货、开票），用行级主键；若是订单级聚合（如对账），用单据级主键并去重。
FBillNo 是跨系统对照的桥梁：金蝶的 FBillNo 与旺店通的订单编号通常有明确的业务映射关系，在轻易云的映射器里应优先用 FBillNo 做关联键，而非 FID（后者是金蝶内码，外部系统无法识别）。
FilterString 的增量逻辑要测试边界：FApproveDate 是审核日期，不是创建日期。如果业务上依赖创建时间来触发同步，需要额外加上 FCreateDate 条件，否则会有延迟。
分页参数要稳态设置：Limit=2000 是经验值，太大容易超时，太小会增加请求次数。在轻易云里通常配合断点续传机制使用。
扁平化结果的内存开销：当订单行数较多时，扁平化后的宽表记录数 = 订单数 × 平均行数。某零售企业的实测中，单次拉取 2000 行限制对应约 300~500 个订单，需要预估下游处理能力。
关闭状态的语义不止 'A' 和 'B'：金蝶还可能有 'C'（手工关闭）等状态，本策略通过 FilterString 只保留 'A'，但下游若需要分析已关闭订单，需另建查询策略。

踩坑复盘

踩坑 1：用 FID 当跨系统关联键导致对账失败 某客户把金蝶的 FID（如数字内码）作为与旺店通订单的关联键，结果旺店通侧无法识别。稳妥的做法是用 FBillNo（业务单据编号）做关联键，FID 仅用于金蝶内部去重。

踩坑 2：忽略扁平化结构导致数据膨胀 下游策略误以为每条记录是一个订单，实际每条是一个行项目。结果同一个订单被处理多次。稳妥的做法是明确 metadata 中 id 字段为行级主键，并在下游做订单聚合。

踩坑 3：增量筛选漏掉审核日期边界 某次同步窗口期内的订单因审核时间恰好跨过整点，被遗漏两次同步。稳妥的做法是在 FilterString 中加上 FApproveDate<='{{CURRENT_TIME|dateTime}}'，确保不遗漏边界数据。

踩坑 4：FCloseStatus 过滤过严导致下游数据缺失 业务方反馈某些已发货但未关闭的订单未被同步。检查后发现金蝶的 'A' 状态定义在不同版本略有差异。稳妥的做法是在轻易云的调试模式下手动执行查询，确认返回数据符合预期。

踩坑 5：定时窗口覆盖不全 crontab 配置为 */5 6-22 * * *，导致晚 22:00 之后审核的订单无法被及时增量捕获。稳妥的做法是 24 小时轮询，或在次日开市前手动触发一次全量补差。

何时选用

该接口适用于以金蝶云星空为 ERP 主数据源、需要将销售订单同步至外部系统（旺店通、WMS、TMS 等）的供应链集成场景。当业务需要按订单行粒度处理数据（如逐行发货）、依赖审核日期增量同步、或需要扁平化宽表快速写入下游时，是首选方案。若需实时推送（秒级延迟），建议改用金蝶的实时消息队列接口。

金蝶云星空销售订单查询接口字段手册：executeBillQuery 实战权威教程