金蝶云星辰【联动查询】仓库接口字段手册权威教程

这个接口解决什么问题

在旺店通与金蝶云星辰的供应链集成场景里,「仓库」是入库单、出库单、调拨单、库存查询等业务流转的根主数据。我们通过金蝶云星辰 V2 的 /jdy/v2/bd/store 接口做纯查询联动,把仓库编码、名称、分类、仓位与负库存配置拉取出来,用于与旺店通的仓库/店铺仓库做编码对照,并为后续业务单据的仓库映射提供统一基准。该策略 Target 配置为「写入空操作」,定位是供其他写入策略调用的「主数据前置查询」。

接口能力总览

• 接口路径:/jdy/v2/bd/store(金蝶云星辰 V2 WebAPI)
• 请求方法:GET
• 策略类型:QUERY,纯查询,不写入目标系统
• 认证方式:采用金蝶云星辰标准的 OAuth/AccessToken 体系,在轻易云里通过「金蝶云星辰 V2」适配器托管凭证,免维护 access_token 刷新
• 过滤参数:enable(默认 1,只取启用仓库)、group_id(按仓库分类过滤)
• 分页参数:page(默认 1)、page_size(由轻易云变量 PAGINATION_PAGE_SIZE 控制,典型 100~500)
• 响应结构:数组式分页返回,每条记录包含主键 id、编码 number、名称、分类、仓位与负库存标志
• 调度建议:在多个客户方案里,定时任务统一配置为每日凌晨 15 3 * * * 执行,避开业务出库高峰

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,该接口的封装非常省心:

1. 适配器:在「数据源」选择「金蝶云星辰 V2」,填入授权信息(凭证由平台统一托管,无需在策略里硬编码 access_token)。
2. 数据对象:选用 bd/store 仓库主数据,轻易云会自动把 id、number、enable、group_id 等字段加载到字段映射器。
3. 过滤与分页:在策略配置面板里勾选 enable=1,如有特殊分类需求,在「请求参数」中追加 group_id;分页大小直接绑定环境变量 PAGINATION_PAGE_SIZE。
4. 目标端:Target 选择「写入空操作」(NoOp),明确这是一个纯查询联动节点,用于被其他写入策略依赖。
5. 调度:crontab 填 15 3 * * *,与金蝶侧库存初始化时序对齐。
6. 依赖编排:轻易云的策略依赖图会自动识别该查询为前置节点,后续「销售出库同步」「调拨单同步」等写入策略可在字段映射器里直接引用 warehouse_code(number)。

跨方案实战要点

在多个客户项目里,我们沉淀出以下共性经验:

• 优先用 number 做业务映射键:id 在系统升级或跨账套迁移时会变,而业务编码几乎不变,集成稳定性更高。
• 「启用状态」务必前置过滤:禁用仓库一旦参与后续单据映射,会出现出库失败或库存错乱,默认 enable=1 是稳妥做法。
• 分类编码优于分类名称:同名分类重命名很常见,group_number 才是稳定的对照锚点。
• 仓位与负库存标志要透传:这两个字段直接影响下游业务规则,不能因为当前场景用不到就丢掉。
• 纯查询节点要明确标注:Target 设为「写入空操作」,并把策略 type 标注为 QUERY,让依赖图清晰可读。
• 调度避开业务高峰:凌晨 3:15 是经验值,既避开白天高频写入,又能在早班前完成主数据刷新。

踩坑复盘

• 坑 1:把 id 当作旺店通侧的对照键。某次系统升级后金蝶 id 发生变化,导致历史单据全部失联。修复方案:切换为 number 作为对照键,轻易云字段映射器一键即可替换。
• 坑 2:忽略了禁用仓库。拉取了 enable=0 的仓库,下游出库单引用后被金蝶拒收。修复方案:在请求参数里固化 enable=1 过滤。
• 坑 3:group_name 作为分类对照键。客户改了「成品仓」的名称,依赖该映射的下游策略全部失败。修复方案:统一改用 group_number。
• 坑 4:分页 page_size 写死过大。一次拉取 5000 条触发金蝶限流。修复方案:把 page_size 交给 PAGINATION_PAGE_SIZE 变量管控,轻易云里调成 200 即可。
• 坑 5:忘了把 is_allow_neg 透传。某零售企业允许负库存的虚拟仓,在出库环节被默认业务规则拦截。修复方案:在字段映射器里显式透传该字段。

何时选用

「金蝶云星辰仓库查询」适用于旺店通与金蝶云星辰做供应链集成、需要做仓库主数据联动对照或为后续写入策略提供仓库基准数据的场景;纯查询不写入,必须搭配其他写入策略才能形成完整业务闭环;若客户不需要金蝶做账或无跨系统仓库对照需求,可跳过此节点。