金蝶云星空物料批号启用查询(executeBillQuery)接口字段手册权威教程

这个接口解决什么问题

在多组织、多账套的金蝶云星空与 SQL Server 供应链集成场景中,业务方经常需要快速定位「电商账套下、已启用批号管理」的物料清单,以支撑批次库存、电商订单履约、批次调整等下游策略。本接口通过 executeBillQuery + FormId BD_MATERIAL,按使用组织、物料分组、审核日期等条件精准过滤,输出纯查询结果,不写回任何目标系统,是供应链批号域最常用的「清单型」前置策略。

接口能力总览

• 认证方式:金蝶云星空标准 OAuth/账号体系,私有化部署下走内网网关,需在轻易云连接器中配置账套信息与用户凭证。
• 请求结构:基于 executeBillQuery,提交 FormId BD_MATERIAL、FilterString 过滤条件、字段集合以及分页参数。
• 响应结构:返回金蝶标准单据集合,字段以 F 前缀暴露(如 FMasterId、FNumber、FName、FIsBatchManage)。
• 分页/增量:支持分页;增量通过 FApproveDate >= '{{LAST_SYNC_TIME|dateTime}}' 实现,轻易云调度器自动维护游标。
• 策略类型:effect = QUERY,Target 为「写入空操作」,纯查询,不写目标。
• 调度:定时任务 3-59/5 * * * *,每 5 分钟拉取一次。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,这个接口的封装非常轻量:在「金蝶云星空」连接器下新建策略 → 选择 API executeBillQuery、FormId BD_MATERIAL → 在可视化表单里勾选上述 7 个字段,平台会自动把 F 前缀字段解析成中文标签。

轻易云的字段映射器会根据 metadata 自动填充 id = FMasterId、number = FNumber,并启用 idCheck = true、autoFillResponse = true。FilterString 在平台里可直接编辑,常用片段:

• FUseOrgId.FNumber = '100'(锁定电商账套)
• FApproveDate >= '{{LAST_SYNC_TIME|dateTime}}'(增量)
• FMaterialGroup.FNumber IN (...)(按分组圈定)

策略类型选 QUERY,Target 选「写入空操作」,定时器设 3-59/5 * * * * 即可上线。

跨方案实战要点

在多个客户的 SQL Server × 金蝶云星空供应链集成项目里,我们沉淀出以下共性经验:

1. 「使用组织」是电商账套的金线:几乎所有物料域策略都必须按 FUseOrgId.FNumber 圈定,否则会混入制造、零售等其他账套数据。
2. FIsBatchManage 必须作为下游开关:电商订单、库存批次、批次调整三个下游策略普遍以本接口输出作为过滤清单。
3. 增量字段优先用 FApproveDate:相比 FModifyDate,审核日期更稳定,避免草稿态物料被反复拉取。
4. 纯查询也要配置 Target:选「写入空操作」是稳妥做法,既保留策略可观测性,又防止误写。
5. 每 5 分钟一次是性价比甜点:电商账套物料变更频率不高,过密会触发金蝶网关限流;过稀又影响下游批次库存时效。
6. 主键与编码双轨:同时维护 FMasterId 与 FNumber,在 SQL Server 侧建两张索引,既可按主键比对,又可按编码比对。

踩坑复盘

• 踩坑一:漏配 FUseOrgId 过滤。直接后果是返回全集团物料,下游批次库存「爆量」。稳妥做法是在轻易云 FilterString 里硬编码 FUseOrgId.FNumber = '100',并在调度自检脚本里抽样校验。
• 踩坑二:增量字段选错。曾有项目用 FModifyDate,导致审核前的物料被反复推送,下游批次库存出现重复行。稳妥的做法是统一用 FApproveDate,轻易云调度器会以状态变更时点为准推进游标。
• 踩坑三:idCheck 未开。一旦 SQL Server 侧编码被人工修改,缺少主键校验会出现数据错位。务必在轻易云 metadata 里打开 idCheck = true。
• 踩坑四:批号字段被忽略。曾有下游策略不看 FIsBatchManage,把所有物料都按批次处理,导致无批次物料库存异常。稳妥的做法是在下游链路第一步就 filter FIsBatchManage = '是'。
• 踩坑五:定时器触发金蝶限流。把周期调到 1 分钟一次,触发私有化网关 QPS 限流,查询失败。稳妥的做法是按业务峰值选 5 分钟或更长,并错开多策略的整点峰。

何时选用

适用:多组织金蝶云星空与 SQL Server 供应链集成中,需要按账套、按物料分组、按审核日期增量获取「启用批号管理」的物料清单,作为电商订单、批次库存、批次调整等下游策略的前置筛选。 边界:本接口仅做纯查询,不写回目标系统;若需要写回 SQL Server,请另建 SYNC 策略;多语言、长文本、附件类字段不在本接口输出范围内。