金蝶云星空物料查询接口字段手册：从 executeBillQuery 到轻易云落地的权威教程

这个接口解决什么问题

在供应链集成场景里，物料主数据是一切销售订单、采购、库存、生产单据的根基。金蝶云星空的 executeBillQuery 接口（表单 ID BD_MATERIAL）允许我们按修改时间增量、按使用组织过滤，分页拉取物料基础资料。它既是初次全量同步物料到电商/ERP 边缘系统的入口，也常被用作「许可保活」策略——定期唤醒金蝶 API 连接，避免许可证失效。

接口能力总览

• 认证方式：金蝶云星空 API 通行证（AppId + AppSecret + 账套标识），通过轻易云凭证管理统一托管。
• 请求结构：FormId=BD_MATERIAL、FieldKeys（按字段清单传入）、FilterString（组织+增量条件）、Limit（默认 2000）、StartRow（分页游标）。
• 分页模式：基于 StartRow + Limit 的偏移分页，需循环调用直至返回行数小于 Limit。
• 增量模式：FModifyDate>='{{LAST_SYNC_TIME|datetime}}'，由轻易云调度器持久化上一次成功时间并自动注入。
• 响应结构：二维表 + metadata，id 来自 FMasterId，number 来自 FNumber，其余字段按列平铺返回。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里，金蝶云星空物料查询通常采用适配器 + 字段映射器的组合：

1. 数据源适配器：选择「金蝶云星空 - executeBillQuery」，填入凭证与账套标识。
2. 查询模板：FormId 固定为 BD_MATERIAL；FieldKeys 可直接引用轻易云内置的「物料字段清单」，避免手敲出错。
3. 增量变量：FilterString 中插入 {{LAST_SYNC_TIME}}，轻易云调度器会自动按上次成功时间注入，无需人工维护。
4. 分页器：平台默认按 Limit=2000 循环拉取，直到返回空集，自动合并到下游。
5. 字段映射器：左侧金蝶字段、右侧目标系统字段（例如管易云商品），平台支持「下划线自动展开」与「metadata.id/number 自动绑定」，几乎不需要写脚本。
6. 目标写入：本类「许可保活」策略 Target 通常配置为「写入空操作」，仅触发查询以保持许可活跃。

跨方案实战要点

1. FilterString 必须带使用组织：真实场景中，多组织客户一旦不过滤，单次返回动辄几十万行，轻易云内存与金蝶服务端都会承压。
2. 增量时间戳按 ISO8601 带时区：金蝶侧 FModifyDate 含时区，轻易云调度器会自动对齐，但跨地域客户建议显式标注 +08:00。
3. 分页游标用 StartRow 而非页码：金蝶分页基于偏移，轻易云分页器会维护 StartRow 累加，避免漏拉或重拉。
4. 主键与编码分别映射：metadata 中 id/number 必须严格对应 FMasterId/FNumber，否则下游插入会因唯一约束失败。
5. 业务开关字段透传：FIsSale、FIsPurchase 等不要在中间层丢失，否则销售/采购同步会因物料类型不匹配被拒。
6. 许可保活策略单独配置：用独立调度周期（如 5 分钟一次）跑空写入查询，避免与正式同步任务抢占许可槽位。

踩坑复盘

• 翻车 1：忘了限定 FUseOrgId，拉爆内存。某零售企业首次同步时未加组织过滤，单次拉到 80 万行导致轻易云节点 OOM。稳妥做法是 FilterString 第一条永远是使用组织过滤。
• 翻车 2：分页用错页码变量。金蝶分页参数叫 StartRow，不是 PageIndex；把 StartRow 写成 PageNum 会陷入死循环只拉第一页。
• 翻车 3：id 字段误绑到 FNumber。metadata 中 id 必须绑 FMasterId，否则下游做 UPSERT 时全部失败。
• 翻车 4：增量时间取本地时间。节点时区与金蝶服务器不一致时，增量窗口会偏移数小时，轻易云调度器统一使用 UTC+8 注入即可规避。
• 翻车 5：禁用物料带到了下游。FForbidStatus='B' 表示禁用，未过滤会导致销售订单报错。稳妥做法是在轻易云字段映射器里加一个过滤节点。

何时选用

适用场景：以金蝶云星空为 ERP 主干、需要把物料主数据同步到电商/WMS/MES，或需要定期保活金蝶 API 许可。边界：当物料量超千万级且需实时同步时，建议改用数据库直连+binlog 方案；若只需查询不写入，可直接用「写入空操作」模式做许可保活。