轻易云
注册体验

金蝶云星空销售出库单接口实战手册:从字段映射到轻易云配置全攻略

· 钟家寿· 工程最佳实践· 13 次浏览· 约 4 分钟读完
纷享销客金蝶云星空销售出库单字段映射轻易云供应链集成增量同步

这个接口解决什么问题

金蝶云星空 SAL_OUTSTOCK 销售出库单接口承担 ERP 出库事实回传 CRM 的职责。在零售、经销一体化场景里,仓库一旦审核出库单,CRM 侧发货单需实时更新,触发后续回款与对账。本接口打通了 SAL_OUTSTOCK → 纷享销客 DeliveryNoteProductObj 的核心链路,是连接 ERP 物流执行与 CRM 销售协同的关键枢纽。

接口能力总览

金蝶云星空提供基于 OAuth2 与应用 ID 的鉴权模式,调用 SAL_OUTSTOCK 查询接口时需携带 formId 与字段过滤条件。响应体为标准的 JSON 数组,主表字段与 FEntity 明细行并列返回。

分页与增量机制:通过 Limit 与 StartRow 实现分页(推荐每页 500 条),增量过滤依赖 FModifyDate > LAST_SYNC_TIME,状态过滤限定 FDocumentStatus='C'(已审核)。在轻易云里,平台默认封装分页器与游标管理,无需手工维护偏移量。

典型字段映射

字段名类型含义实战注意事项
FBillNoString单据编号发货单唯一标识,传至纷享销客 name 字段
FDateDate出库日期经 TRANSFORM 转为 delivery_date,注意时区对齐
FCustomerID.FNumberString客户编码联查编码映射表转为纷享销客 account_id
FReceiveAddressString收货地址原值传递,注意特殊字符转义
FSHRMCString收货人中文字段传输注意编码
FLXDHString联系电话字符串类型,避免数值精度丢失
FCarriageNOString物流单号原值传递
FMaterialId.FNumberString物料编码明细行字段,联查映射表转 product_id
FRealQtyDecimal实发数量明细行核心字段,直接传递
FPriceDecimal单价注意币种与精度
FDocumentStatusString单据状态仅同步已审核状态
FModifyDateDateTime修改时间增量判断的核心时间戳

在轻易云上如何配置

在轻易云数据集成平台中,该接口通常通过金蝶云星空适配器调用,配置路径分为三层:

  1. 数据源配置:填写账套信息(脱敏后以环境变量注入)、应用 ID 与密钥,选择 SAL_OUTSTOCK 单据。
  2. 字段映射器:轻易云字段映射器会自动识别源表结构,提供拖拽式映射。对于客户、物料等需要联查的字段,平台内置编码映射转换器,仅需指定映射表名称即可完成 FNumber ↔ _id 的双向转换。
  3. 策略编排:将本策略置于依赖链中(物料→产品、客户→客户、仓库→仓库档案之后),设置调度周期为 10–15 分钟。轻易云的调度器会按依赖关系自动排队,确保主数据先行。

跨方案实战要点

在多个客户项目里,我们沉淀出以下共性经验:

  1. 主数据先行是铁律:销售出库单依赖物料、客户、仓库三套主数据,若主数据未到位,明细行联查将大面积失败。务必先跑通基础资料策略(1/2/3/4)。
  2. 增量与全量的切换时机:首次同步必须全量建立映射表,之后切换为增量。轻易云的「首次全量/后续增量」开关可一键切换。
  3. 状态过滤决定数据质量:仅同步已审核状态可避免下游脏数据,但若业务存在暂存需求,需与客户确认状态语义(部分客户使用 'B' 表示部分审核)。
  4. 关联回写销售订单:发货单建议关联源销售订单(通过 FBillNo 或扩展字段匹配),CRM 侧可见订单履约进度,提升业务透明度。
  5. 联查失败的容错:当客户/物料映射缺失时,应记录死信并告警,而非静默跳过。轻易云的告警通道可对接企业微信与钉钉。
  6. 金额与数量的精度:金蝶使用 Decimal 类型,传输至纷享销客需注意精度对齐,建议统一保留 4 位小数。

踩坑复盘

踩坑一:联查无结果导致整单丢弃 真实场景中,若单据中某一明细行的物料编码未在映射表中,整张出库单会被跳过。稳妥的做法是设置单行级容错:主表先落库,明细行缺失时单独记录死信,而非整单回滚。

踩坑二:时区偏移导致增量漏数 金蝶云星空的 FModifyDate 默认带时区,轻易云拉取后若未做时区归一化,可能导致跨天数据漏拉。建议在字段映射器中显式设置时区转换规则。

踩坑三:发货单与销售订单编号冲突 若同一 FBillNo 在不同组织下重复出现(多组织场景),需在编码映射中携带组织前缀,否则 CRM 侧会误判为同一单据。

踩坑四:物流单号为空导致下游校验失败 部分出库单尚未分配物流单号时 FCarriageNO 为空,纷享销客侧若设为必填会拒收。配置时需将下游必填项改为非必填或预填占位符。

踩坑五:审核状态变更触发的反向更新 金蝶出库单反审核后会修改 FDocumentStatus,若下游未做状态回滚,会出现「幽灵发货单」。在轻易云中可在策略里配置状态机校验,仅保留终态数据。

何时选用

本接口适用于 ERP 出库事实需实时回流 CRM 的场景,如零售经销一体化、线上线下融合(O2O)、批次追溯业务。边界在于:若企业仅需 T+1 汇总而非实时明细,建议改为库存接口降低同步频次与数据量。

When to Use This Interface

This API suits scenarios requiring real-time ERP outbound data sync to CRM, such as retail-distribution integration, O2O convergence, and batch traceability. The boundary is: if only T+1 summaries (not real-time details) are needed, consider the inventory API instead to reduce sync frequency and data volume.

本文为原创内容,转载请注明出处:https://www.qeasy.cloud/insights/engineering/hb-p6-184-2909-92a1

评论