聚水潭×金蝶云星辰供应链集成接口字段手册：从出库到采购的21个策略全解读

这个接口解决什么问题

在零售与电商场景下，聚水潭作为前端电商 ERP、金蝶云星辰作为后端财务 ERP，两边都会产生商品、库存、销售出退库、采购入退库、移仓等单据。如果不把它们打通，业务人员就要在两个后台重复录单，库存数对不上、财务结账慢、异常单据无人跟。这套接口的核心价值，就是让聚水潭的电商业务单据自动落到金蝶做财务核算，把金蝶的成品档案与库存回写到聚水潭做前端运营，做到业务流与财务流的单据一体化。

接口能力总览

• 认证方式：金蝶云星辰采用 OAuth2 授权码模式（需周期性刷新 access_token），聚水潭采用 AppKey + AppSecret + 签名机制，奇门接口另走单独的授权链路。
• 请求结构：均为 HTTPS + JSON，POST 为主；分页参数通常为 page_index / page_size，增量拉取依赖 modify_start_time / modify_end_time 或 modified 时间戳。
• 响应结构：金蝶侧统一包络 { "code", "message", "data" }，聚水潭侧返回 { "code", "msg", "data" }，成功码通常为 200 / 0。
• 分页/增量模式：金蝶商品/库存类接口支持分页+时间窗口，窗口不超过 7 天；聚水潭出退库/采购类接口走修改时间增量，单据状态 Confirmed 才会被同步。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里，这套接口会被封装成「聚水潭连接器」与「金蝶云星辰 V2 连接器」两个标准适配器。通常的做法是：先在轻易云的连接器市场里创建这两个数据源账号，开启授权刷新策略（对应策略 3）保证 Token 不过期；然后用轻易云的字段映射器把上述源/目标字段一一配好，数组型 material_entity 走轻易云内置的「分录映射」节点即可，无需手写循环。

对于 21 个策略，轻易云的方案画布支持把「查询商品/品牌/币别」这类基础资料同步作为前置依赖节点，业务单据节点通过引用上游输出即可自动拿到编码映射结果。轻易云的调度器支持 crontab 直接配置，把错峰策略（如 */8 与 */30）错开，避免金蝶侧限流。

跨方案实战要点

1. 编码映射是单据能不能落库的命门：在多个客户项目里，80% 的初次失败都来自 material_number↔sku_id 与 customer_number 映射缺失，必须先跑基础资料查询策略再跑业务单据。
2. 奇门与非奇门要分清楚：聚水潭同一张出仓单，奇门接口走 shop_id / open_id / shop_buyer_id 三套客户字段映射，非奇门接口只走 shop_id，单据类型不能错配。
3. 退仓单一定要用 as_id：出库用 io_id，退库用 as_id，混用会导致金蝶侧单据编号重复触发审核失败。
4. 批次维度优先用 batch_qty：当聚水潭明细里同时存在 items 与 batchs，优先用 batchs 作为 material_entity 数据源，否则批次号无法带到金蝶。
5. 时间窗口必须 ≤7 天：金蝶侧增量接口硬性限制单次查询时间跨度不超过 7 天，超出会直接报错，建议按天分片。
6. 自动审核 operation_key 显式传值：移仓、其他出库、采购入退库都需要在请求体里显式传 operation_key: "audit"，否则单据会停在「保存未审核」状态。

踩坑复盘

• Token 过期导致整批失败：金蝶 access_token 有效期约 2 小时，没配自动刷新就会出现「下午单据突然全失败」。稳妥的做法是：在轻易云里把策略 3 设为 0 */2 * * *，并开启触发式刷新钩子。
• 盘点单覆盖把库存清零：金蝶库存同步到聚水潭盘点单时，type=check 表示盘点覆盖，若库存数量为 0 推送，会把聚水潭可用库存刷成 0。正确做法是加数量阈值过滤，低于 1 不推送。
• 客户映射错位引发财务串户：shop_id 与 shop_buyer_id 在不同电商店铺含义不同，错映射会导致销售出库单落到错误的客户名下，财务对账对不上。建议：在轻易云映射器里加 dry-run 预演，先跑一周影子模式。
• 采购入库单缺批次被拒：聚水潭采购入库如未启用批次，batchs 为空，但金蝶物料启用了批次管理，会校验失败。这里容易翻车，稳妥的做法是先用策略 4 查询物料是否启用批次，分类处理。
• 奇门接口与标准接口重复落单：奇门策略与非奇门策略同时启用，会出现同一张聚水潭单据在金蝶生成两份。正确做法是按客户/店铺维度二选一，绝不并行。

何时选用

只要业务是「电商 ERP（聚水潭）↔ 财务 ERP（金蝶云星辰）」的供应链闭环，且需要库存、订单、批次、单据级别的实时/准实时同步，就应优先选用这套接口组合。边界是：纯财务核算场景不必启用销售出退库同步；纯电商运营场景不必启用采购入退库同步；多组织/多账套的金蝶环境需要先确认星辰 V2 是否对应。