业务流程图 · 开发参考

京东外仓退货差异核对

获取京东【大件+中小件】退供单据 → 编码映射 → 调用旺店通创建"其他入库单" → 仓库入库时核对应退明细。把京东"应退明细"前置到仓库入库环节,将"收货后反查"变为"收货时核对"。

📁 PRD prd.md v1.0 🏗️ 架构 ROC BFF 外部对接层 ⏱️ 触发 定时轮询 1h 👥 关联方 仓库·京东运营·财务·PM
京东开放平台(数据源)
ROC BFF(调度中枢)
OPS(编码映射配置)
旺店通 ERP(建单+单据管理)
淮安仓 WMS(仓库入库核对)
飞书群(告警)
1

系统全景

6 个系统协作:京东出数据 → ROC BFF 处理 → 旺店通 ERP 建单 → 淮安仓 WMS 核对;OPS 维护映射,飞书群负责告警。

🏬
京东开放平台
退供管理2.0
6 接口出数据
⚙️
ROC BFF
外部对接层
拉单→聚合→建单
📋
旺店通 ERP
建其他入库单
单据管理中枢
🏭
淮安仓 WMS
仓库扫码入库核对
入库后回传 ERP
🔧
OPS 后台
维护 skuId ↔ 商家编码映射
京东运营操作
🔔
飞书群
编码缺失/建单失败告警
@京东运营
2

端到端主流程

5 个阶段:数据拉取 → 明细处理 → 编码映射 → 建单 → 入库核对。每 1h 轮询触发一次。

1数据拉取
中小件运单列表
按发运时间增量拉取
listShippingOrders
大件出库单列表
按创建时间增量拉取
listOutboundOrders
2拉明细
中小件运单明细
skuId / partCode
getShippingOrder
大件出库单明细
skuId / spareCode / packageNo
getOutboundOrder
3聚合+映射
按 skuId 聚合
num = 同 skuId 明细行数
备件条码 → remark
查 OPS 映射
skuId → spec_no
缺失则告警(见§4)
4旺店通ERP建单
建其他入库单
调旺店通 ERP
is_check=1 已审核
createOtherOrder
ERP 推送 WMS
ERP 自动推单
淮安仓 WMS 可见
幂等兜底
status=100 重复
自动跳过
5淮安仓WMS核对
扫码关联
logistics_no
→ 关联 outer_no
逐件核对
实收 vs 应退明细
差异按既定流程上报
WMS 回传 ERP
入库后回传
ERP 更新单据状态
3

中小件 vs 大件 数据线差异

两条数据线建单粒度与字段来源不同,开发需分别处理。

中小件 运单线

  • 建单粒度:运单(shipCode)一单
  • 列表+明细:listShippingOrders → getShippingOrder
  • outer_no(幂等键)= shipCode
  • logistics_no(扫码)= shipCode
  • 备件条码:取 partCode
  • 映射键skuId
  • remark:京东自营-中小件退货

大件 出库单线

  • 建单粒度:出库单(outboundOrderNo)一单
  • 列表+明细:listOutboundOrders → getOutboundOrder
  • outer_no(幂等键)= outboundOrderNo
  • logistics_no(扫码)= packageNo 去后缀(JDG…-1/-2 → JDG…)
  • 备件条码:取 spareCode
  • 映射键skuId
  • remark:京东自营-大件退货
4

异常分支:编码缺失闭环

映射缺失不阻塞流程,留待下次轮询自然重试,形成闭环。

当单据内存在未映射的 skuId 时,整单暂缓建单(不拆单),触发飞书告警:

① 映射缺失
单据暂缓建单,记录缺失 skuId
② 飞书告警
@京东运营 刺梨/沅昕
③ OPS 维护
京东运营补 skuId↔spec_no
④ 下轮重试
1h 后轮询命中并建单
↺ 自然重试,不建队列
5

关键业务规则

📐

建单聚合规则

1 备件条码 = 1 实物,每明细行 = 1 件。单据内按 skuId 聚合:num = 同 skuId 行数,备件条码填 remark(多件逗号隔开)。

🔗

编码铁三角

1 备件条码 = 1 实物商品;1 skuId = 多个备件条码;1 skuId = 1 个旺店通商家编码(spec_no)。

🔑

幂等机制

outer_no 全局唯一(中小件=shipCode、大件=outboundOrderNo)。旺店通 status=100 外部单号重复为天然兜底,重复推送不产生重复单。

🏷️

渠道自动打标

渠道由数据来源接口决定(京东接口→京东自营),BFF 自动打标,零配置。再按中小件/大件拼备注。

🏭

建单与核对链路

ROC BFF 调旺店通 ERP建单 → ERP 推淮安仓 WMS → 仓库扫 logistics_no 关联 outer_no 核对 → WMS 回传 ERP 更新状态(旺店通自身机制,本次不开发)。

⏱️

轮询与重试

1h 轮询一次。编码缺失不建重试队列,下次轮询自然重试。单据级隔离,单据失败不阻塞批次。

6

旺店通建单字段映射速查

开发建单时直接对照此表(createOtherOrder)。

旺店通字段必填中小件来源大件来源
outer_no 外部单号(幂等键)shipCode(运单号)outboundOrderNo(出库单号)
logistics_no 运单号(扫码必填)shipCode(运单号)packageNo 子母单去后缀主号
warehouse_no 仓库编码202201040001 淮安WMS仓同左
remark 单据备注选填京东自营-中小件退货京东自营-大件退货
goods_list[].spec_no 商家编码skuId→OPS映射skuId→OPS映射
goods_list[].num 数量按 skuId 聚合:同 skuId 行数按 skuId 聚合:同 skuId 行数
goods_list[].remark 明细备注选填备件条码 partCode(逗号隔开)备件条码 spareCode(逗号隔开)
is_check 单据状态选填1(已审核)1(已审核)

响应:status=0 成功 / data.message=入库单号;status=100 外部单号重复(幂等);status=20 审核失败。