这个接口解决什么问题

金蝶云星空的「销售出库单executeBillQuery」接口用于按业务条件批量拉取出库单数据,典型场景是把电商/聚水潭侧的订单与金蝶侧的出库单做对账、追踪待确认收货状态,并为后续的状态回写提供数据源。它解决了跨系统出库单同步「查不到、查不准、查不全」的问题,是聚水潭↔金蝶供应链集成的核心查询入口。

接口能力总览

认证方式:金蝶云星空标准的 OAuth/账套授权,需传入 acctId、appId、appSecret 等参数;请求头需携带 token。
请求方式:POST,API 为 executeBillQuery,FormId 固定为 SAL_OUTSTOCK(销售出库单)。
请求体:基于 otherRequest 结构,核心参数包含 FormId、FieldKeys、FilterString、Limit、StartRow、TopRowCount。
响应结构:返回 Result 数组,每行包含所请求字段键值对;metadata 中 autoFillResponse:true 由系统自动填充字段。
分页/增量模式:通过 StartRow + Limit 实现分页(Limit 默认 10000),无内置增量字段,通常用业务时间(FDate)或确认收货日期作为软增量游标。
过滤逻辑:默认 F_QKMS_QRSHRQ is null and FCreatorId.FName='传单专用' and FThirdBillNo <> '',即「待确认收货 + 传单专用账号创建 + 内部订单号非空」。

典型字段映射

字段名	类型	含义	实战注意事项
FBillNo	string	单据编号,业务主键	元数据 `number`、`id` 都指向它;跨系统对账的锚点
FID	string	主表唯一ID,系统主键	用于精确查询与去重,不要当业务编号用
FThirdBillNo	int/string	内部订单号(聚水潭单号/平台单号)	过滤要求非空;类型兼容务必确认,见下文踩坑
FCreatorId	object	创建人(含 FName 等子属性)	过滤时用 `FCreatorId.FName='传单专用'` 锁定来源
F_QKMS_QRSHRQ	string	确认收货日期(扩展字段)	为空=待确认,是状态回写的关键触发条件
FSALECHANNEL	string	线上订单号(扩展映射)	在不同客户方案中含义略有差异,需对照元数据
FDate	string	出库单业务日期	用于时间范围筛选与对账,常做增量游标

在轻易云里,字段映射器会自动把 FCreatorId.FName 展开成扁平字段,免去写嵌套解析脚本;同时平台会对 FThirdBillNo 做类型宽容处理,但仍建议在源头规范为 string。

在轻易云上如何配置

适配器选型:轻易云内置金蝶云星空 executeBillQuery 适配器,FormId 选 SAL_OUTSTOCK,平台会自动生成请求骨架与分页器。
元数据配置:把 number、id 都设为 FBillNo,idCheck:true 启用主键校验,buildModel:true 构建数据模型。
过滤条件:在轻易云的「过滤表达式」里直接写 F_QKMS_QRSHRQ is null and FCreatorId.FName='传单专用' and FThirdBillNo <> '',平台会拼装到 FilterString。
字段映射器:把 FieldKeys 列出的字段拖入映射面板,轻易云的字段映射器会自动建立 source→target 字段表;Target 端选「写入空操作」即纯查询策略。
调度:定时任务写为 1-59/30 7-23 * * *,每 30 分钟、7–23 点执行;轻易云的调度器会按该 cron 自动触发。

跨方案实战要点

业务主键优先用 FBillNo:FID 是系统主键,跨系统对账不可靠;FBillNo 在金蝶侧唯一且稳定。
过滤条件三件套:待确认收货 + 传单专用 + 内部订单号非空 是多个客户验证过的最小集,缺一会拉出脏数据。
增量游标选 FDate 还是确认收货日期:高频轮询用 FDate 做软增量,事件驱动用 F_QKMS_QRSHRQ 由空转非空触发。
分页大小别拍脑袋:默认 Limit=10000 在大多数金蝶实例上是稳定上限;超过会触发接口截断或超时。
类型兼容必须在源头解决:FThirdBillNo 在 source 配置里是 int,但聚水潭订单号常含字母,集成前先做类型转换。
纯查询策略的 Target 配置:Target 选「写入空操作」,表明本策略只负责拉数,后续的回写动作由下游策略接管。

踩坑复盘

踩坑1:FThirdBillNo 类型不一致。source 配 int,实际订单号带字母,接口直接报错或返回 null。稳妥做法是源头统一按 string 处理,或在轻易云字段映射器里做强制类型转换。
踩坑2:过滤条件漏写 FCreatorId。只写「确认收货日期为空」会把所有渠道的出库单都拉过来,造成聚水潭侧无法关联。务必把 FCreatorId.FName='传单专用' 加进过滤。
踩坑3:把 FID 当业务编号对账。FID 是数据库主键,在跨账套或跨组织时会变;对账必须用 FBillNo。
踩坑4:分页越界。Limit 超过 10000 后金蝶会静默截断,数据看似完整其实丢尾部。轻易云的分页器内置了安全上限,但自定义脚本时仍需注意。
踩坑5:调度窗口覆盖不到夜单。cron 7-23 漏掉凌晨单,新增策略时容易翻车;若业务跨夜,稳妥的做法是把窗口扩成 0-23 或拆成两段。

何时选用

该接口适用于「金蝶做单、聚水潭做订单」的中大型零售企业,需要按业务条件批量查询销售出库单,并与上游订单做对账或状态回写。边界:它只做查询,不承担写入;若需写入金蝶,请改用 save/submit 类接口;若需实时推送,需配合消息中间件而非纯轮询。

金蝶销售出库单executeBillQuery接口字段手册与跨方案实战教程