这个接口解决什么问题

在多系统集成的客户项目里,仓库主数据是销售订单、采购入库、调拨、盘点等业务单据的「地基」。我们做小满OKKICRM、聚水潭、旺店通与金蝶对接时,第一步几乎都是先把金蝶侧的仓库档案拉成一张对照表,让下游单据知道「这个仓库编码对应金蝶哪条记录」。金蝶体系下有两个分支:金蝶云星辰V2走轻量级 WebAPI(/jdy/v2/bd/store),金蝶云星空走企业级 executeBillQuery(FormId: BD_STOCK)。本教程把这两个接口的字段、增量、踩坑一次性讲透。

接口能力总览

金蝶云星辰V2:RESTful 风格的 GET 请求,路径 /jdy/v2/bd/store。支持按 modify_start_time、modify_end_time 毫秒时间戳做增量过滤,分页参数 page(默认 1)、page_size(默认 100)。请求体可选过滤 enable(默认 1,只查启用仓库)。策略类型为 QUERY_ONLY,Target 端配置「写入空操作」,只拉不写。

金蝶云星空:通过通用单据查询接口 executeBillQuery 提交表单 BD_STOCK,使用金蝶特有的 FilterString 过滤语法(如 FNumber = 'CK001'、FAuditDate>='{{LAST_SYNC_TIME}}'),分页用 Limit(默认 2000)、StartRow、TopRowCount。同样为 QUERY_ONLY 策略,Target 端空操作。

两个接口在轻易云里都被注册为「查询型适配器」,源系统为金蝶,目标端标记为空写策略,定时调度以 crontab 形式挂在策略编排里。

典型字段映射

字段名	类型	含义	实战注意事项
id / FStockId	string	仓库主键,系统内唯一标识	增量同步的去重锚点,跨系统关联建议用主键而非编码
number / FNumber	string	仓库业务编码	跨系统仓库映射的「桥字段」,与小满/聚水潭/旺店通的 warehouse_no 直接对接
name / FName	string	仓库显示名称	仅用于展示,不要拿去做匹配
group_id / FGroup	string	仓库分类/分组	星辰V2分三个字段(id/number/name),云星空只返 FGroup 一个字符串,要做分组路由时注意差异
enable	string	启用状态(1启用/0禁用)	星辰V2才有,云星空通常在 FilterString 里直接过滤 `FForbidStatus='A'`
is_allow_freight	string	是否启用仓位管理	仓位是仓库的子存储位置,启用后会改变下游库存接口的返回结构
is_allow_neg	string	是否允许负库存	开启后支持先出后入业务,关闭则严格按可用量校验
FUseOrgId	string	使用组织	云星空多组织架构特有,按 `FUseOrgId.FNumber` 格式传参

在轻易云上如何配置

在轻易云数据集成平台里,「查询金蝶仓库」通常被封装为一个 QUERY_ONLY 源适配器。我们配置时几个关键点:

适配器选择:源系统选「金蝶云星辰V2」或「金蝶云星空」,平台会自动加载对应的 endpoint 模板和字段元数据。
字段映射器:轻易云的字段映射器会自动把 id、number、name 识别为主键、编码、名称三类关键字段,并在目标端 schema 中生成 warehouse_id、warehouse_code、warehouse_name 的通用命名,方便下游策略复用。
增量参数:星辰V2直接配置 modify_start_time/modify_end_time;云星空则需要在 FilterString 中嵌入 FAuditDate>='{{LAST_SYNC_TIME|dateTime}}' 表达式,轻易云的表达式引擎会按上次同步时间自动渲染。
Target 空操作:由于是纯查询,Target 端选择「空操作」,数据落到轻易云中台的数据池,供其他策略(如销售订单仓库映射)按编码反查。

跨方案实战要点

从多个客户方案里,我们提炼出以下共性经验:

编码字段是跨系统映射的命脉:不管星辰还是星空,number/FNumber 都是业务侧唯一标识,务必把它作为映射表的主键,而不是 id/FStockId。
增量同步优先按修改时间,而不是创建时间:仓库新建后还会频繁改名、调整分组、切换启用状态,用 modify_start_time(星辰)或 FAuditDate(星空)更稳。
启用状态过滤放在请求侧:默认只同步 enable=1 的仓库,可大幅减少下游脏数据,禁用仓库通常不参与业务流转。
分页大小要看接口脾气:星辰V2默认 100 条/页比较保守;云星空 Limit=2000 是单次上限,大批量同步时建议每页 1000-2000 平衡性能与稳定性。
分组字段的语义差异:星辰V2拆成 group_id/number/name 三段,云星空只有 FGroup 一个字段,在轻易云映射器里要做字段合并或拆分处理。
轻易云的 QUERY_ONLY 策略必须配 Target 空操作:否则调度器会因找不到写入目标而报错,这是新同学最容易踩的配置坑。

踩坑复盘

坑一:用 name 做跨系统匹配。某零售企业项目里,仓库改了名字,下游销售订单的仓库映射全部失联。这里容易翻车,稳妥的做法是永远用编码字段做匹配,名称仅做人工核对。
坑二:增量时间窗口没设上限。星辰V2的 modify_end_time 如果不传,会拉到当前时刻所有增量,长跑后内存爆掉。稳妥的做法是每次调度只取「上次同步时间 → 当前时间」的窗口,end_time 严格封口。
坑三:云星空 FilterString 用错分隔符。金蝶过滤语法要单引号包字符串,双引号会直接 400。FNumber = "CK001" 是错的,正确写法是 FNumber = 'CK001'。
坑四:仓位管理字段未对齐。星辰V2的 is_allow_freight 是仓库级别开关,但仓位数据要走单独的 /jdy/v2/bd/position 接口,不要在这个查询里期望拿到仓位明细。
坑五:负库存配置未与业务规则联动。is_allow_neg=1 只是技术开关,实际是否允许先出后入还要看客户业务策略,轻易云里建议把它映射成一个「业务规则标签」字段,供下游库存校验策略引用。

何时选用

本接口适用于「需要把金蝶仓库档案同步到中台,构建跨系统仓库映射表」的所有场景,覆盖小满CRM、聚水潭、旺店通等异构系统对接。边界提示:若客户同时使用星辰V2和云星空(混合部署),需要在轻易云里分别配置两套源适配器,并通过统一的 warehouse_code 主键做合并;若仅需仓库名称做展示,直接调单条查询接口即可,不必拉全量。

金蝶仓库查询接口字段手册权威教程:从星辰V2到云星空 executeBillQuery 全景实战