旺店通WMS对接实战指南：从订单推送到库存回传的完整链路

简介面向旺店通WMS系统对接开发者的完整代码包聚焦WebAPI接口地址、标准定制接口样例与具体调用流程三大实际问题。资源以销售出库单查询接口为实战主线不仅解释了接口调用规范还通过C# HttpClient演示了POST请求、签名构建、URL参数封装等关键环节并附有包含请求地址、方法、密钥及参数设置的完整调用示例适合有一定C#基础、需要快速完成WMS集成的开发人员直接参照编码。包体共32个文件压缩后约380KB以C#源文件.cs、工程文件.csproj、编译生成的DLL与PDB调试文件为主体另含JSON配置、TXT说明及Python辅助脚本覆盖从源码编译、配置读取到运行调试的完整链路目录结构便于按模块检索。已有182人学习下载。通过该包可掌握旺店通WMS接口调用规范、签名算法和标准定制接口的扩展思路同时获得可直接复用的请求示例与调试方法有效减少对接初期的试错成本提升业务接口联调效率。1. 旺店通WMS对接流程在解决什么订单进仓库回执回ERP订单在旺店通ERP里审核完还要人工复制单号去WMS建单这套流程日订单几百单时还能凑合大促一来两个系统的手工操作员先崩溃。旺店通WMS对接流程就是把旺店通ERP的订单、货品、库存通过开放接口同步给仓库侧的WMS系统再把仓库的发货状态、物流单号、库存变动回写ERP两边各自作业账目却对得上。适合自研WMS或上了第三方WMS系统的电商团队。这里有个反直觉的判断对接真正跑通不是“推单成功”而是三件事同时成立——不重复建单、库存两边一致、凌晨出问题时没人盯也能自动回传。你判断一个WMS系统值不值得投入先拿这三条去压一天的线上数据。2. 对接前先理清边界WMS类型、开放平台权限与字段映射2.1 先确认你对的是哪类WMS接口能力差别很大“旺店通WMS”这个说法在从业者嘴里有点含糊一种是指旺店通ERP去对接外部WMS另一种是指旺店通自己的仓内模块。本文讲的是前者也是仓库里最常见的需求ERP在云端WMS在仓内或者由第三方提供中间要有一条数据通道。写代码之前我先确认仓库那边的WMS是什么形态是自研、第三方SaaS还是只有Excel导入能力的库房系统。这三种对接成本从两周到一个小时不等差距比我想象的大得多。如果是自研WMS通常能协商出最顺的接口形态REST/JSON、字段命名都能对齐甚至可以让对方按你的报文开发这是最舒服的情况。第三方SaaS WMS则只能用他开放的OpenAPI字段名固定、回调机制固定你的对接代码反而要做大量适配。最麻烦的是号称有接口实则只能导Excel的WMS几百单时能接受超过一千单后人工成本和误操作率会让你后悔当初没问清楚。这个决定会一路影响第4章的链路设计所以我不建议绕过。所以对接第一步不是写代码是问五个问题能不能查库存能不能接收外部订单生成出库任务能不能回传发货结果能不能按外部单号反查状态接口限流阈值是多少这五个答案直接决定技术方案形态。如果文档里只能找到“订单导入”而找不到“异步回调”或“状态查询”你基本可以判断这个WMS只支持半自动对接后面所有“实时性”要求都得靠你自己轮询找补。2.2 开放平台权限与接口签名AppKey、AppSecret加签是第一步确认WMS能力后另一头是旺店通开放平台的调用权限。常见做法是在旺店通商家后台创建一个开放应用拿到一对AppKey和AppSecret。AppKey在请求里明文传递AppSecret用于计算签名不能出现在前端页面上。放在后端对接服务里虽然看得见但至少别提交到公开代码仓库否则等于把密钥发在朋友圈。我一般会在配置中心里单独存AppSecret代码仓库里只留占位符。旺店通开放平台的调用风格和主流电商开放平台类似一次HTTP POST请求带着method接口名、app_key、timestamp、业务参数和sign。签名规则大多数是把所有参数按字典序ASCII升序排好逐个以“参数名参数值”方式拼接末尾拼上AppSecret取MD5后转大写。各家细节不同有的要求URL编码有的要求跳过空值最终以你手上接口文档里的“签名示例”为准。我习惯把生成签名前的原始字符串打印出来跟文档示例比对签名排错能省一半时间。旺店通开放平台的接口按业务分几类货品、库存、订单、发货、售后。WMS对接通常只需要四类拉待发货订单、查库存、下发发货单、回传发货结果。接口数量越少越好每多接一个接口就多一条链路要维护。我一般会把需要的接口列成一个清单逐个确认是否存在做成下面这样功能接口名示意是否必需查询待发货订单wdt.order.query必需查询实时库存wdt.stock.query必需下发发货单wdt.delivery.create必需回传发货结果wdt.delivery.callback必需查询发货状态wdt.delivery.query强烈建议第五个“查询发货状态”是兜底用的第4章的“先查后建”和“轮询补单”都靠它。如果两边任意一侧没有这个接口你的重试策略就只能盲重试风险显著上升。另外注意timestamp这个参数平台靠它防重放误差通常超过五分钟就会被拒。对接服务器的系统时间如果漂移签名算法写对了也会报错这个细节常在凌晨被线上告警吵醒时才想起来检查。2.3 字段映射表写代码前先把两边字段在纸上对齐WMS对接最容易被低估的是字段映射。旺店通侧的“货号”和WMS的“SKU编码”、旺店通的“仓库”和WMS的“库房”两边“物流公司”编码表经常是两套完全不同的值。不要指望用一堆if/else去转物流公司编码那是给自己埋雷。我一般先画一张映射表让仓库主管确认过再写代码。常见的必备映射方向如下旺店通字段WMS字段示例值备注货号sku_codeSPU0001两边必须完全一致仓库warehouse_noWH-01旺店通仓库编码对应WMS库房店铺shop_noSHOP-001回传时区分渠道物流公司logistics_companySF/ZTO需要独立映射表平台单号platform_order_no202501010001全局唯一幂等键这张表里最容易翻车的是物流公司旺店通用简称SF、ZTOWMS可能是offline_code或者数字编码。常见做法是把映射表外置成配置文件启动时加载别让业务组的人来找你改代码。字段映射确认后再写第一行代码顺序反了仓库团队会觉得你只懂代码不懂业务。还有个容易漏的旺店通的“货品档案”和WMS的“商品档案”是两回事。旺店通叫货品WMS叫SKU连单位都可能不一致。推单前要先确保WMS建好对应货品否则第一张单就报“货品不存在”。这个问题很常见我放到第5章专门讲排查过程。3. 用示例代码跑通旺店通WMS最小链路库存查询、推单与回调3.1 工程结构与最小依赖我不建议一开始上微服务框架对接进程两个礼拜就能写完的东西拆成六个服务只会增加排查成本。我常用的工程结构是三个文件wdt_client.py封装旺店通开放平台调用wms_client.py封装WMS侧接口调用callback_server.py接收WMS回调。定时触发放进cron依赖只有requests和Flask幂等状态先用内存集合演示生产环境换成Redis。示例代码讲解尽量一个易错点对应一行注释。这类项目最重要的思维是“把对接服务当成胶水层而不是业务系统”。它只需要把两边的数据格式翻译正确、状态记录清楚、错误暴露出来不要在胶水层里写复杂业务判断。代码仓库结构如下wdt-wms-bridge/ ├── wdt_client.py # 旺店通开放平台封装 ├── wms_client.py # WMS 出库单创建封装 ├── callback_server.py # 接收 WMS 回调 └── main.py # 定时任务入口3.2 签名与请求封装所有接口共用的入口先把调用旺店通的公共逻辑抽成函数后续每个接口调用都复用。这个函数要干四件事拼公共参数、计算签名、发送POST请求、解析统一返回结构。示例代码如下# wdt_client.py import hashlib import time import requests GATEWAY https://openapi.example.com/gateway # 以旺店通开放平台文档为准 APP_KEY your-app-key APP_SECRET your-app-secret def build_sign(params: dict) - str: # 过滤空值sign 不参与签名 items sorted((k, str(v)) for k, v in params.items() if v is not None and v ! ) raw .join(f{k}{v} for k, v in items) APP_SECRET return hashlib.md5(raw.encode(utf-8)).hexdigest().upper() def call_wdt(method: str, biz_params: dict, timeout: int 8) - dict: params { method: method, app_key: APP_KEY, timestamp: str(int(time.time())), **biz_params, } params[sign] build_sign(params) resp requests.post(GATEWAY, dataparams, timeouttimeout) result resp.json() if result.get(code) ! 0: raise RuntimeError(f{method} error[{result.get(code)}]: {result.get(message)}) return result.get(data) or {}build_sign里最关键的是先过滤空值再排序。某些平台对空字符串和None处理不同多拼一个空参数进去签名就错。raw这里用的是参数名和参数值直接拼接如果你的平台文档要求namevalue这种形式把join一行替换成对应的拼接即可判断依据是文档里给出的待签串示例。timeout参数默认8秒这个值在库存查询场景够用推单场景我会手动调大到10秒。3.3 库存查询先确认仓库有货再推单推送订单给WMS前先查一次库存能避免后续超卖纠纷。这里查的是旺店通侧库存如果两边库存没有实时同步这步应该直接查WMS。我示例里按旺店通库存接口来写逻辑一样# main.py from wdt_client import call_wdt def query_stock(sku: str, warehouse_no: str) - int: data call_wdt( wdt.stock.query, { sku: sku, warehouse_no: warehouse_no, page_no: 1, page_size: 100, }, ) items data.get(stock_list) or [] total 0 for item in items: if item.get(warehouse_no) warehouse_no: # available_qty 是可用库存冻结库存不能算 total int(item.get(available_qty) or 0) return totalsku传旺店通货号warehouse_no传仓库编码page_size控制每页条数。库存接口按仓库加库位维度返回一个SKU可能有多行需要按warehouse_no过滤后累加available_qty。如果返回的列表长度等于page_size说明还有下一页不翻页的话库存数会偏小推单后WMS扣减时才发现超卖比不查库存更被动。这里有个默认前提旺店通库存和WMS库存是同步过的如果你正在做第一次对接两边数可能根本不相等这步查出来只能当参考。3.4 推单把ERP订单变成WMS出库任务库存确认后把订单推给WMS。旺店通侧可以理解成“下发发货单”WMS侧生成出库任务。示例里我直接调用WMS的创建出库单接口# wms_client.py import requests def create_wms_outbound(order_no: str, warehouse_no: str, goods: list) - str: payload { req_id: f{order_no}-{warehouse_no}, # 幂等键WMS 要按它去重 outbound_type: SO, warehouse_no: warehouse_no, order_no: order_no, goods_list: goods, } resp requests.post(https://wms.example.com/api/outbound, jsonpayload, timeout10) result resp.json() if result.get(code) ! 0: raise RuntimeError(fWMS 推单失败: {result.get(message)}) return result[data][wms_order_no]goods列表由旺店通订单明细组装典型结构是这样goods [ {sku: SPU0001, qty: 2}, {sku: SPU0002, qty: 1}, ]req_id是幂等键WMS如果收到相同req_id的请求应该直接返回已有出库单号而不是再建一张。这个字段决定了重复推单会不会把仓库作业池打爆我在第5章还会展开。goods里要不要带batch_no批次号要看WMS支不支持批次库存不知道怎么定就先问仓库主管别替业务做决定。还有order_no这个字段我习惯传旺店通平台单号而不是ERP内部单号两边客服沟通时都是拿着平台单号找单统一口径能少很多扯皮。3.5 接收WMS回调并回写旺店通WMS完成出库后把结果回传。常见做法是对接服务提供一个Webhook地址WMS检测到发货完成就POST过来。这里用Flask写一个最小接收端# callback_server.py from flask import Flask, request, jsonify from wdt_client import call_wdt app Flask(__name__) processed set() # 生产环境请换成 Redis / 数据库 app.post(/wms/callback) def on_wms_callback(): payload request.get_json(forceTrue) cb_id payload.get(callback_id, ) if cb_id in processed: return jsonify({code: 0, message: duplicated}) processed.add(cb_id) if payload.get(status) DONE: call_wdt(wdt.delivery.callback, { order_no: payload[order_no], logistics_no: payload[logistics_no], logistics_company: payload[logistics_company], wms_order_no: payload[wms_order_no], }) return jsonify({code: 0})callback_id是WMS回调序号用它做幂等避免旺店通里重复回传。旺店通回传接口名以你拿到的文档为准这里用wdt.delivery.callback示意。注意一点如果回调处理里调旺店通失败返回给WMS的code要置为非0让WMS按它的策略重试不要自己把异常吞掉只记日志不然发货状态会黑在中间层仓库说发了ERP说没收到两边都在催你。4. 从推单到回传的链路设计轮询、重试与每日对账4.1 主动轮询还是被动回调两种链路怎么选第3章展示的是回调链路但真实项目里没有任何一条链路是单一的。我把数据流拆成两段看旺店通到对接服务这段可以轮询WMS到对接服务这段可以回调。两段的选择标准不一样链路实时性对公网要求对接成本典型场景轮询30秒到数分钟低低WMS没有回调能力回调秒级高需公网可达中WMS支持Webhook轮询回调混合秒级高中高生产环境推荐旺店通侧如果没有稳定的Webhook或者你不想维护一套回调接收端就用轮询。常见做法是每30秒调一次旺店通的待发货订单查询接口新单推给WMS同时处理之前已发货但没回传的单。这种模式的代价是把接口调用频率抬高所以要控制page_size和查询时间窗口别一次性把大促的历史单全部拉出来那会把你自己的队列冲垮。轮询循环的骨架就三行import time while True: try: fetch_and_push_pending() # 拉新单、推WMS、回传状态 except Exception as e: log.error(cycle failed: %s, e) # 别让一次异常打断整个循环 time.sleep(30)这个写法看着简单踩坑点在于异常处理循环里任何一个环节抛异常整个循环就停了后面所有订单全部积压。所以要在这里拦一层记录日志然后继续。从运维角度看这条循环是一个黑匣子只有日志能告诉你它每分钟干了什么。4.2 重试、超时与幂等接口调到一半断了怎么办对接服务调WMS创建出库单超时你无法确认WMS到底建没建单。最怕这时候直接重试WMS可能已经建单并开始拣货再来一发就是重复作业。正确做法是“先查后建”WMS只要有按外部单号查询出库单的接口超时后先查有则用WMS单号继续没有再重试新建。这个原则是WMS对接里最重要的幂等手段没有它线上的重复单会让你被仓库主管拉黑。同理旺店通回传也遵循这个原则。回传超时旺店通里可能已经收到重试前要确认这个order_no没有被回传过。我一般在本地维护一张流水表记录order_no、推单时间、WMS单号、回传状态用order_no做唯一索引。这张表是整个对接的黑匣子出了问题先翻它不要一上来就对着旺店通日志查。流水表结构可以参考CREATE TABLE delivery_bridge_log ( id BIGINT AUTO_INCREMENT PRIMARY KEY, order_no VARCHAR(64) NOT NULL, wms_order_no VARCHAR(64), status TINYINT NOT NULL DEFAULT 0, retry_count TINYINT NOT NULL DEFAULT 0, callback_at DATETIME, created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, UNIQUE KEY uk_order_no (order_no) );status这个字段可以简化定义0代表已推WMS未回传1代表已回传旺店通2代表两边确认异常。每次推单前先查这张表status已经是1或2就跳过。这张表同时也为第4.3节的每日对账提供了数据源一举两得。注意callback_at记录的是回传成功时间而不是WMS发货时间两个时间都可能被问到别只记一个。4.3 每天对账一次把两边的账平掉代码写得再干净两边库存也会因为漏单、重复扣减、人工操作产生偏差。我上线第一天就会加一个每日对账任务它的职责不是修数据是把偏差暴露出来。思路很简单分别从旺店通和WMS拉当天已发货的单号集合求差集。def reconcile_deliveries(date: str): wdt_no query_wdt_delivered(date) # 旺店通当天已发货单号 wms_no query_wms_outbound(date) # WMS 当天已完成出库的来源单号 diff1 wdt_no - wms_no # 旺店通已发WMS 没有回传可能丢了 diff2 wms_no - wdt_no # WMS 已发旺店通没记录漏推或人工建单 print(fdiff1{len(diff1)}, diff2{len(diff2)}) print(diff1 sample:, list(diff1)[:5]) print(diff2 sample:, list(diff2)[:5])对账结果里diff1往往是旺店通回传失败需要重推回传diff2通常是旺店通侧漏推或WMS手工建单需要人工确认。对账脚本放进cron每天早上六点跑一次输出一个文本文件值早班的人扫一眼就能决定要不要处理。不要试图让脚本自动修复数据自动修复在两边系统里是最危险的权限。这里再补一句对账时间窗口选择要注意时区电商仓库常到凌晨一两点还在发货早上六点对账正好把最后一班夜班的发货数据含进去。5. 旺店通WMS对接常见问题排查与避坑清单我在这条对接链路上踩过的坑按“现象、原因、解决”三条写给后来人省点排查时间。这些问题不分先后每一个都真实发生在我自己或身边同事的线上环境里。5.1 签名失败接口报“签名错误”却看不出哪里错现象按文档写了签名接口还是返回“签名错误”。原因通常是三个。第一个签名串里混进了sign本身计算时把上一个请求的sign带进了参数集第二个AppSecret拷贝时带了空格或换行肉眼看不出来第三个参数里有int型但你排序时转成了字符串排序结果和文档示例不一致。解决在build_sign里把raw通过日志打印出来对照文档的待签串示例逐字符比对。确认请求里带上来的params和签名时用的params是同一份不要一边改一边签。这个坑基本是所有开放平台对接的开门砖过了它后面才谈得上业务。5.2 推单报“重复单号”或WMS出现重复作业现象同一张订单被推了两次WMS作业池里出现两个出库任务。原因轮询拉单时状态标记只写在内存里服务一重启内存状态就丢或者超时后直接重试WMS那边其实已经建单。解决推单前先查本地流水表order_no已存在就跳过。超时后用WMS的查询接口先查后建。还有一个兜底做法在流水表的order_no上建唯一索引让数据库拒绝重复订单代码层漏了他还能接住。这个兜底是我被重复作业坑过两次之后才加上的属于典型的后悔药。5.3 库存回传后两边数据对不上现象旺店通库存和WMS库存每天差几个数。原因两边扣减时机不同旺店通常见的是审核即锁库WMS常见的是拣货完成才扣减这个时间差在正常业务里是合理的不算故障。如果差值持续扩大就要查有没有退款单、取消单被漏回传。解决定义清楚以哪边库存为准通常以WMS实物库存为准每天全量同步一次。同步时注意冻结库存和可用库存要分开处理别把冻结库存当可用库存往下发。我见过一个团队因为没区分冻结库存大促期间把预留给售后换货的货全发出去了。5.4 回调丢失WMS发完货ERP一直显示待发货现象仓库已经发货ERP订单状态几个小时不更新。原因WMS的回调URL指向了内网地址或已失效的公网地址回调处理函数抛了异常却返回code 0WMS认为已送达不再重试或者回调报文里字段名和你解析的不一致解析结果为空但没报错。解决回调处理里对旺店通回传失败必须返回非0。同时加一个轮询兜底任务每半小时把“已推WMS但超两小时未回传”的单子捞出来主动向旺店通确认状态。这个兜底是上了生产之后再不敢省的部分也是整个链路里最值得花时间做的功能。5.5 货品档案不一致推单到WMS报“货品不存在”现象订单推过去WMS返回“货品不存在”或“SKU未建档”。原因旺店通货号和WMS的sku_code对不上或者WMS侧的货主没建对货品建到了别的货主下。解决上线前先跑一个货品档案全量同步把旺店通货品列表拉到WMS建档。日常推单前先校验映射表里该货号是否存在。凡是碰到货品层面的错误优先怀疑数据而不是代码先查WMS基础资料再查代码逻辑能少走半天弯路。还有单位问题旺店通按“件”的货品到WMS可能按“个”数量对不上这种问题查日志查不出来只能靠现场盘点发现。6. 验收清单与上线后的运维习惯跑稳比跑通更重要6.1 验收清单把链路钉死再放量我每次上线前都会按下面这张清单过一遍全绿才敢推量验收项操作方法通过标准幂等同一订单连续请求两次WMS只有一个出库单回传在WMS手工标记完成2分钟内旺店通可见物流单号库存对账跑第4.3节脚本差集为空或已被说明容错停掉WMS十分钟再恢复积压单自动补齐无重复单6.2 上线第一周必盯的三个指标第一个指标是旺店通接口返回非0 code的比例超过0.5%就该看日志。第二个是WMS回调成功率直接反映链路通不通。第三个是本地流水表里status2的异常单数量这部分会越积越多必须每天清一次。我习惯用一行命令守夜grep -E error|cannot|timeout /var/log/wdt_bridge.log | awk {print $1} | sort | uniq -c把这条命令挂到服务器终端上早上起来先看一眼计数比盯着面板报表更直接。前两周我会把日志级别调到DEBUG两周后再降回INFODEBUG日志能帮你快速定位字段解析问题但一直开着会占满磁盘。6.3 一个我保留至今的习惯接手这套对接后我养成了一个习惯所有订单号相关的日志一律同时打印订单号和WMS单号方便按任意一边去反向查。血泪经验是去年有一次生产翻车两边客服各自按自己的单号查数据对不上号我只能翻原始请求报文手工拼接那个下午过得非常煎熬。后来我把流水表的主查询从order_no扩展成order_no和wms_order_no双索引再没出现过两边对不上证据的情况。跑稳一个对接方案一半靠代码另一半靠日志和表结构里多想一步。希望帮到你。本文还有配套的精品资源点击获取