金蝶云星空销售出库单接口实战手册:从字段映射到轻易云配置全攻略
这个接口解决什么问题
金蝶云星空 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'(已审核)。在轻易云里,平台默认封装分页器与游标管理,无需手工维护偏移量。
典型字段映射
| 字段名 | 类型 | 含义 | 实战注意事项 |
|---|---|---|---|
| FBillNo | String | 单据编号 | 发货单唯一标识,传至纷享销客 name 字段 |
| FDate | Date | 出库日期 | 经 TRANSFORM 转为 delivery_date,注意时区对齐 |
| FCustomerID.FNumber | String | 客户编码 | 联查编码映射表转为纷享销客 account_id |
| FReceiveAddress | String | 收货地址 | 原值传递,注意特殊字符转义 |
| FSHRMC | String | 收货人 | 中文字段传输注意编码 |
| FLXDH | String | 联系电话 | 字符串类型,避免数值精度丢失 |
| FCarriageNO | String | 物流单号 | 原值传递 |
| FMaterialId.FNumber | String | 物料编码 | 明细行字段,联查映射表转 product_id |
| FRealQty | Decimal | 实发数量 | 明细行核心字段,直接传递 |
| FPrice | Decimal | 单价 | 注意币种与精度 |
| FDocumentStatus | String | 单据状态 | 仅同步已审核状态 |
| FModifyDate | DateTime | 修改时间 | 增量判断的核心时间戳 |
在轻易云上如何配置
在轻易云数据集成平台中,该接口通常通过金蝶云星空适配器调用,配置路径分为三层:
- 数据源配置:填写账套信息(脱敏后以环境变量注入)、应用 ID 与密钥,选择
SAL_OUTSTOCK单据。 - 字段映射器:轻易云字段映射器会自动识别源表结构,提供拖拽式映射。对于客户、物料等需要联查的字段,平台内置编码映射转换器,仅需指定映射表名称即可完成 FNumber ↔ _id 的双向转换。
- 策略编排:将本策略置于依赖链中(物料→产品、客户→客户、仓库→仓库档案之后),设置调度周期为 10–15 分钟。轻易云的调度器会按依赖关系自动排队,确保主数据先行。
跨方案实战要点
在多个客户项目里,我们沉淀出以下共性经验:
- 主数据先行是铁律:销售出库单依赖物料、客户、仓库三套主数据,若主数据未到位,明细行联查将大面积失败。务必先跑通基础资料策略(1/2/3/4)。
- 增量与全量的切换时机:首次同步必须全量建立映射表,之后切换为增量。轻易云的「首次全量/后续增量」开关可一键切换。
- 状态过滤决定数据质量:仅同步已审核状态可避免下游脏数据,但若业务存在暂存需求,需与客户确认状态语义(部分客户使用 'B' 表示部分审核)。
- 关联回写销售订单:发货单建议关联源销售订单(通过 FBillNo 或扩展字段匹配),CRM 侧可见订单履约进度,提升业务透明度。
- 联查失败的容错:当客户/物料映射缺失时,应记录死信并告警,而非静默跳过。轻易云的告警通道可对接企业微信与钉钉。
- 金额与数量的精度:金蝶使用 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.