金蝶云星辰仓库查询接口(/jdy/v2/bd/store)字段手册与实战教程

这个接口解决什么问题

在零售与电商场景里,仓库主数据是出入库、调拨、盘点等单据的维度基础。多个客户方案都把金蝶云星辰作为 ERP 主数据源,通过 /jdy/v2/bd/store 接口把仓库按修改时间增量拉取,再与聚水潭等业务系统的仓库编码建立对照表,从而保证后续单据在跨系统流转时仓库维度不丢不错。

接口能力总览

• 认证方式:金蝶云星辰 WebAPI 标准的 AccessToken 鉴权,通常由独立的「获取最新授权」前置策略刷新。
• 请求方式:GET /jdy/v2/bd/store。
• 请求参数:modify_start_time、modify_end_time(增量时间戳)、page(默认 1)、page_size(默认 50)。
• 响应结构:列表型,每条记录包含仓库主数据字段,主键 id,业务编码 number。
• 分页模式:标准分页,通过 page 与 page_size 控制;增量通过时间区间游标实现。
• 策略类型:本场景定位为 QUERY(纯查询,Target 配空操作),不承担写入。
• 调度:crontab */5 8-20 * * *,营业时段内 5 分钟轮询。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台中,该接口一般以「金蝶云星辰适配器」封装,字段映射器会自动识别 id、number、name、enable 等基础字段,无需手工解析 JSON。配置上注意三点:

1. 选择数据查询模式,Target 端选择「写入空操作」,保证策略只做主数据拉取。
2. 把增量区间绑定到调度变量,每次执行自动推进 modify_end_time,避免漏单。
3. 把 number 标记为业务主键输出,后续商品、单据同步策略可复用该映射结果。

跨方案实战要点

• 以 number 而非 id 做业务主键:多个客户都因 ERP 内部 id 易变而踩坑,统一用编码做跨系统锚点。
• 增量区间要留重叠:为了防止边界数据被漏拉,通常把上一窗口的尾部时间回拨 1–2 分钟。
• 禁用仓库的处理策略:不要直接过滤 enable=0,否则后续单据会找不到仓库;建议在目标端做状态映射,保留禁用记录。
• 仓库分类与聚水潭仓库类型:聚水潭主仓/销退仓/进货仓/次品仓需通过对照表与金蝶仓库分类映射,不要硬编码在脚本里。
• 营业时段调度:8:00–20:00 每 5 分钟的调度在多家客户验证过,既能保证及时性又避免夜间无效请求。
• 授权前置:依赖「获取星辰最新授权」策略的输出,部署时务必确认依赖顺序正确。

踩坑复盘

1. 增量边界漏单:只取闭区间导致同一秒修改的数据重复或丢失,稳妥的做法是开闭区间混用并加小窗口回拨。
2. page_size 过大触发限流:金蝶星辰对单次返回量有限制,超过阈值会截断,稳妥做法是把 page_size 控制在 50 以内并加重试。
3. 分类字段为空导致映射断裂:新建仓库未填分类时 group_* 全空,聚水潭侧需要给出默认兜底仓库类型。
4. is_allow_freight 语义混淆:不同星辰版本既可能代表运费也可能代表仓位管理,集成前必须用真实租户数据核对,别照搬文档。
5. Target 空操作误配成写入:一旦把空操作配成真实写入,会污染下游,稳妥的做法是在 metadata 显式标注策略类型为 QUERY。

何时选用

适用于「金蝶星辰作为 ERP 主数据源,需要把仓库同步到聚水潭等业务系统,或为后续商品/单据同步提供仓库对照表」的场景。若需要双向同步或金蝶不是主数据源,则应改用通用主数据治理方案,而不是直接复用该查询接口。