金蝶云星辰商品库存查询接口字段手册：从跨方案实战到盘点单对接

这个接口解决什么问题

在多系统并行的零售与分销场景里，ERP 与 WMS 的库存数据常常各自为政，导致账实不一致、盘点反复纠偏。金蝶云星辰的商品即时库存接口（SCM Inventory）正是为了把 ERP 侧的库存基准同步到 WMS 侧的盘点单而存在的——以 ERP 为准，将库存数量、批次、仓位、辅助属性等维度推送至聚水潭盘点单，实现一次盘点即对账。

接口能力总览

• 认证方式：金蝶云星辰开放平台 OAuth 2.0 协议，需先换取 access_token，再以 Bearer 方式带入请求头。
• 请求方式：POST /jdy/v2/scm/inventory/list，body 为 JSON。
• 核心入参：modify_start_time / modify_end_time（毫秒时间戳，标准增量窗口）、page、page_size，可叠加 material_id / stock_id 等过滤条件。
• 响应结构：分页对象含 data（库存列表）与 total_count。库存对象覆盖商品、仓库、仓位、辅助属性、批次、保质期、数量等多维度字段。
• 分页模式：传统页码分页（page + page_size），默认每页 10 条，建议调用方显式提升至 50-200 以减少请求次数。
• 增量策略：按 modify_time 增量拉取，配合平台变量 {{LAST_SYNC_TIME}}000 与 {{CURRENT_TIME}}000 形成滑动窗口。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台中，该接口被封装为「金蝶云星辰 V2 SCM 库存适配器」，典型配置路径如下：

1. 适配器选型：源系统选择「金蝶云星辰 V2」，接口选「商品库存查询」。
2. 元数据绑定：id 绑定 material_id、number 绑定 material_number，并启用 idCheck 与 autoFillResponse。
3. 字段映射器：在可视化映射画布里，把 material_number → items.sku_id、stock_number → warehouse、qty → items.qty，平台字段映射器会自动处理类型转换与空值兜底。
4. 调度策略：定时器设为 */25 * * * *（每 25 分钟），增量窗口用平台内置变量 {{LAST_SYNC_TIME}}000 / {{CURRENT_TIME}}000。
5. 目标配置：选择聚水潭盘点单上传接口，type=check（全量覆盖）、is_confirm=1、so_id 使用 {{random}}、remark 注明「金蝶即时库存同步」。

跨方案实战要点

1. 复合主键意识：在多个客户项目里，凡涉及批次或辅助属性的库存记录，单凭 material_id+stock_id 必然漏数据；必须叠加 batch_no 或 aux_prop_id，仓位仓库还要加 sp_id。
2. qty 与 valid_qty 的取舍：盘点对账场景务必用 qty（账存基准），不要被 valid_qty（已扣预留）误导，否则账实差异越拉越大。
3. 仓库字典必须前置映射：聚水潭的 warehouse 是枚举值（金蝶侧的编码要翻译成 1/2/3/4），建议在轻易云的「数据字典转换器」里一次性建好映射表，避免下游写脏数据。
4. 批次/保质期商品的窗口：保质期类商品需要把 kf_date / valid_date 一并写入盘点单备注或扩展字段，否则到期判定失真。
5. page_size 调优：金蝶默认每页 10 条在数据量大的仓库非常慢，我们通常显式提到 100-200，配合 25 分钟窗口基本能追平写入。
6. 断点续拉：增量窗口务必保存 LAST_SYNC_TIME 持久化变量，轻易云会自动落库；但跨日切换时要注意时区与 0 点边界。

踩坑复盘

1. 没启用批次却按 batch_no 去重：某零售企业第一次跑盘点时漏掉近三成数据，原因是商品启用了批次但策略里没把 batch_no 加入去重键，导致多条记录被覆盖。
2. 辅助属性与聚水潭 SKU 对不上：颜色尺码类商品在金蝶是辅助属性，在聚水潭是 SKU；直接用 material_id 映射会让聚水潭端无法识别规格。稳妥做法是把 aux_prop_number 拼到 SKU 编码后缀。
3. valid_qty 被误用为盘点基准：把 valid_qty 当成盘点数量写入盘点单，结果盘点差异被预留数量「吃掉」，账实长期对不平。
4. 整件散包单位混淆：qty_package 与 qty 单位不同，整件管理商品如果只取 qty 会少一半；务必根据商品单位策略选字段。
5. 跨时区时间戳漂移：增量窗口在跨日时偶发漏数据，原因是金蝶返回 modify_time 是 UTC+8 而调度器误以为是 UTC；稳妥做法是在轻易云里把窗口变量统一按 Asia/Shanghai 格式化。

何时选用

当企业需要把 ERP 作为库存唯一事实源，并把库存基准同步至 WMS 盘点单以实现一次盘点即对账时，优先选用本接口；若仅做库存预警或粗略看板，可考虑金蝶的轻量 BI 接口；若系统间已是同构库存模型，则不必走盘点单链路，直接走库存调拨接口更合适。