起点:一个典型的“Excel 邮件”流程

很多品牌商的真实现状是:经销商把订单填在 Excel 里,邮件发给销售内勤;内勤汇总、改格式、录入 ERP;ERP 审完再电话或微信通知经销商发货时间。一单流转半天起步,错行、漏单、重复录入时有发生。

本教程的目标:把这个流程改造成——经销商(或其 ERP)把订单以 API / 文件投递到集成平台,平台自动完成清洗、映射、查重,写入金蝶云星空生成销售订单,并把单据状态回传给经销商。

总体链路

采集:经销商 ERP 通过 Webhook 推送,或定时上传订单文件到约定目录;平台统一解析为标准订单结构。
清洗与映射:经销商料号 → 品牌商物料编码;换算单位;校验价格与信用额度。
写入 ERP:调用金蝶云星空 WebAPI 生成销售订单(Save → Submit → Audit)。
状态回传:定时查询 ERP 单据状态,推送给经销商或其中台。

第一步:定义标准订单模型

不管上游是 API 还是 Excel,先归一到统一模型:

json

{
  "externalOrderNo": "DIST-20260410-0001",
  "distributorCode": "D310058",
  "orderDate": "2026-04-10",
  "lines": [
    { "distributorSku": "A1001", "qty": 120, "unit": "箱", "price": 58.5 }
  ]
}

externalOrderNo + distributorCode 是全链路的幂等键,任何环节重试都必须带上它。

第二步:字段映射与编码转换

经销商侧	标准模型	金蝶云星空字段	转换规则
客户编码	distributorCode	FCustId	按映射表转 FNumber
经销商料号	distributorSku	FMaterialId	料号映射表 → 物料编码
数量	qty	FQty	单位换算(箱 → 最小单位)
单价	price	FPrice	校验是否在价目表浮动区间内
外部单号	externalOrderNo	自定义字段 / 备注	幂等查重依据

编码映射表建议放在集成平台里维护,经销商新增料号时走映射补录流程,而不是改代码。

第三步:写入金蝶云星空

金蝶云星空 WebAPI 的标准写入顺序是保存、提交、审核三步:

登录:AuthService.ValidateUser 获取会话(或由集成平台托管凭证)。
保存:DynamicFormService.Save,FormId 为 SAL_SaleOrder,请求体按上表映射组装。
提交:DynamicFormService.Submit。
审核:DynamicFormService.Audit。

写入前必须做幂等查重:用 ExecuteBillQuery 按外部单号过滤查询,已存在则跳过写入并返回原单号。

json

{
  "FormId": "SAL_SaleOrder",
  "FieldKeys": "FBillNo,FId",
  "FilterString": "F_QEZ_ExternalNo = 'DIST-20260410-0001'",
  "Limit": 1
}

第四步:增量调度与状态回传

订单采集:Webhook 优先;文件投递则每 5 分钟扫描一次,处理完归档并记录水位。
状态回传:每 10-15 分钟用 ExecuteBillQuery 以审核时间增量拉取已变更单据,推送给经销商侧;推送失败进重试队列,指数退避,超过上限进人工工单。
对账兜底:每日凌晨跑一次 T+0 全量比对,经销商当日订单数 vs ERP 生成单据数,不一致自动告警。

验收清单

同一外部单号重复推送 10 次,ERP 只生成一张销售订单。
经销商料号错填时,平台产生可读的异常记录并可人工修正后重放,而不是静默丢单。
ERP 审核完成后 15 分钟内,经销商侧能查到单据号与状态。
全程无人工导表,内勤只处理异常工单。

走到这一步,订单回传就从“邮件 + 人肉”变成了可监控、可重放、可扩展的数据链路。

经销商订单回传自动化:从 Excel 邮件到 API 直连