金蝶云星辰仓库查询接口字段手册:P2-283 跨方案实战权威教程

这个接口解决什么问题

金蝶云星辰 V2 的 /jdy/v2/bd/store 仓库查询接口,是旺店通与金蝶供应链集成中仓库主数据同步的源头接口。它按启用状态、修改时间、分类过滤并分页拉取仓库数据,为后续出入库单、调拨单、库存查询提供仓库编码与名称的权威依据,避免下游业务单据因仓库缺失或错配而卡住。

接口能力总览

• 认证方式:金蝶云星辰 WebAPI 标准鉴权,AccessToken 走请求头。
• 请求方法:GET /jdy/v2/bd/store。
• 过滤参数:enable(启用状态,1/0)、modify_start_time / modify_end_time(毫秒时间戳区间增量)、group_id(仓库分类 ID)。
• 分页模式:page(默认 1)+ page_size(默认由轻易云平台变量 PAGINATION_PAGE_SIZE 控制),增量场景按修改时间切片。
• 响应结构:数组型数据对象列表,每条记录承载主键 id、编码 number、名称及扩展配置字段。
• 策略类型:QUERY_ONLY 纯查询,Target 写入空操作,不落目标系统。
• 调度:典型部署每日 6:01 执行(crontab 1 6 * * *),增量窗口按 modify_end_time 收敛。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,这个接口的调用通常通过金蝶云星辰 V2 适配器封装。配置时把 id 设为 metadata 主键、number 设为编码字段,策略类型选 QUERY_ONLY。轻易云的字段映射器会自动把 id → warehouse_id、number → warehouse_code、name → warehouse_name、enable → status、is_allow_freight → enable_location_management、is_allow_neg → allow_negative_stock 映射到下游模型,无需手写转换。分页参数由平台统一注入 page 与 page_size,增量字段绑定 modify_start_time / modify_end_time 后,平台会按调度自动滑动窗口。

跨方案实战要点

1. 主键与编码双轨制:id 与 number 都要落库,前者用于系统间精确关联,后者用于业务可读对照,缺一会导致后续单据推送找不到仓库。
2. 增量窗口用 modify_end_time 收敛:宁可少拉不要多拉,真实场景中跨天调度的边界值最容易翻车。
3. 启用状态严格同步:enable=0 的禁用仓库在下游必须屏蔽,否则会出现已禁用仓库仍被下单的脏数据。
4. 分类字段做语义分组:group_name 用来区分电商仓、线下仓、虚拟仓,旺店通多店铺多仓场景下依赖它路由。
5. 仓位管理是下游开关:is_allow_freight=1 时,出库单必须携带库位,否则会卡在金蝶校验环节。
6. 负库存策略提前对齐:is_allow_neg 与业务规则的差异要提前与仓管确认,避免同步后才发现策略冲突。

踩坑复盘

• 坑 1:同名仓库仅靠 name 对照。同一企业可能有多个"总仓",仅靠 name 匹配会撞车,稳妥做法是用 number 作为映射键。
• 坑 2:增量起始时间用本地时区。金蝶返回的是毫秒时间戳,若把本地时间字符串直接传,会丢 8 小时导致漏拉。这里容易翻车。
• 坑 3:禁用仓库仍参与库存查询。过滤参数 enable 没传,会把禁用仓一起拉回来,下游单据会出现找不到启用仓的报错。
• 坑 4:分类名称被误当编码。group_name 易变,跨系统对接必须用 group_id 或 group_number,别贪图可读性。
• 坑 5:page_size 设置过大触发限流。金蝶云星辰对单次返回有上限,轻易云里建议先用平台默认值压测,再视网络情况微调。

何时选用

该接口适用于旺店通与金蝶云星辰供应链集成中,以金蝶为仓库主数据权威源的同步场景;边界在于它不承担仓内库位、库存余额数据,若需要仓位级数据或库存余量,需另配库存查询与库位主数据接口组合使用。