聚水潭·奇门销售出库单接口字段手册权威教程

这个接口解决什么问题

聚水潭·奇门销售出库单接口是电商 ERP 与传统 ERP 之间订单数据流转的桥梁。在多个零售企业的供应链集成项目里,我们用它把淘宝、天猫、京东等渠道的电商出库单同步为金蝶云星空的销售订单,实现线上出库自动生成 ERP 销售订单、补齐财务核算与库存联动数据,避免人工二次录入。

接口能力总览

• 认证方式:聚水潭奇门采用 AppKey + AppSecret + 平台标识的签名鉴权,通过授权码换取 access_token;请求头携带 token 与平台编码。
• 请求结构:POST JSON 体,核心入参为 modified_begin/modified_end(增量时间窗)、page_index/page_size(分页)、shop_id(店铺过滤)。
• 响应结构:外层 datas 数组,内层单据对象含主表字段与 items 明细行数组;has_next/page_index 标识分页状态;modified 为 ISO 时间戳。
• 分页/增量模式:基于 modified 字段的增量拉取 + page_size(建议 50)分页;首次部署全量回填后切换增量。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,该接口的调用通常封装为「聚水潭奇门适配器」,只需配置 AppKey、AppSecret、平台授权码即可启用,token 自动刷新。

平台字段映射器会自动识别聚水潭响应结构,主表与明细行按 items 数组绑定,支持常量(销售组织 FSaleOrgId=7000、收款条件 FRecConditionId=09)、直接映射、脚本转换三类规则。金额分摊脚本可直接挂在 AfterSourceInvoke 钩子上,平台提供沙箱调试器实时回放。增量调度按 modified 游标推进,失败记录自动进入死信队列。

跨方案实战要点

1. 基础资料优先:物料、店铺→客户、仓库三类映射表必须先全量写入轻易云集线器,否则销售订单、库存策略会因编码缺失大面积失败。
2. 增量游标精度:modified 必须以服务端返回为准,不要用本地时间戳;跨天调度建议加 2 分钟重叠窗口,防边界丢单。
3. 金额分摊不可省:聚水潭优惠、运费在单据级,金蝶要求明细级,AfterSourceInvoke 脚本按数量或金额比例分摊是稳妥做法。
4. 渠道分支必加:node+order_type 决定单据类型,京东&天猫超市渠道固定 XSDD01_SYS,普通淘宝/天猫需走条件分支,否则 FBillTypeID 错位会被金蝶驳回。
5. 幂等键设计:以 io_id+shop_id 组合作为幂等键,避免重跑产生重复销售订单。
6. 审核态过滤:仅同步已审核(C 状态)单据,避免把草稿态推到 ERP 导致单据无法撤销。

踩坑复盘

• 坑 1:店铺编码直接写入。某零售企业初期直接把 shop_id 写入 FCustId,导致金蝶客户档案缺失,后续对账全线失败。稳妥做法是先建店铺→客户映射表。
• 坑 2:分摊金额四舍五入累计差。脚本分摊后明细行合计与单据级金额差 1 分,金蝶校验失败。这里容易翻车,稳妥的做法是最后一行用减法倒挤,锁定尾差。
• 坑 3:增量游标丢失跨天单据。modified 跨天调度时被截断,漏单若干。重叠窗口 + 服务端时间游标是必加项。
• 坑 4:款式商品映射错位。聚水潭 i_id(款式)与 sku_id(SKU)区分不清,部分客户用 i_id 映射 FMaterialId 导致一品多码。统一约定:SKU 级映射 FMaterialId,i_id 仅作辅助。
• 坑 5:奇门 token 过期未刷新。access_token 通常 2 小时过期,平台若未自动续期会出现大面积 401。轻易云适配器已内置续期,自研脚本需加定时刷新。

何时选用

聚水潭·奇门销售出库单接口适用于多渠道电商出库需快速进入 ERP 财务与库存链路的场景;若企业仅使用聚水潭自营仓或仅需非奇门渠道数据,可改用 simple 接口精简策略。若源系统非聚水潭,本接口不适用。