仓储WMS对接淘宝奇门详细说明【亲测可用】

简介

• 淘宝奇门项目支持 ERP、WMS 之间的系统标准化对接，通过构建 ERP、WMS 系统之间标准通信协议来实现不同系统之间的打通；对商家来说，省去了更换系统软件所带来的额外开发成本；对 ISV(独立软件开发商) 来说，省去了与多家 ERP、WMS 系统对接难的问题，ERP 通过一次对接奇门项目，打通与所有 WMS 之间的通信，WMS 通过一次对接奇门项目，可以适配所有 ERP 软件；后期也将加入更多系统的支持，例如 CRM 与 ERP 的标准化对接，CRM 与在线订购类营销工具的标准化对接；

名词解释

奇门对接方案

无奇门的情况

• 目前商家使用的各个业务系统之间依靠 ISV 帮助实现 ERP 到 WMS 的对接，如果有多仓需求的商家还需要使用到 2 套以上的第三方仓储服务所提供的WMS 软件，ERP、WMS 各自对接，对接的总工作量为 N*N 倍，不但给 ISV的开发带来了极大的成本，对于后期维护，也将是一项艰巨的任务，如下图所示：
  

有奇门的情况

• 通过奇门项目后可使原有的网状对接结构变为一对一的对接方式，ERP、WMS 只需要与奇门数据总线对接一次即可完成所有系统的适配（特殊场景可能采用扩展字段的方式给与支持），如下图：
  

前期准备

• 首先要在淘宝开放平台上线对应的服务。
  
• 具体上线申请参考：应用接入流程 , 奇门仓储接入说明，奇门仓储标准白皮书
• 上线完成后，拿到对应开发语言的sdk，appkey，secret。
  
• 创建一个场景
  
  
• 点击进入。
  
• 然后就可以开始开发了。

系统调用流程

• 正向调用：前端 ERP 系统通过 TOP 接口与奇门项目应用进行交互，对于想要发送到 WMS 的请求首先发送到奇门应用，由奇门负责数据的解析、字段映射、数据翻译，再将处理后的数据通过 ERP 系统所请求的目的地发送至 WMS系统；WMS 系统收到请求后，将返回结果送回至奇门应用，由奇门应用统一返回至 ERP 系统；
• 反向调用：WMS 系统主动向 ERP 系统发出状态更新请求也是类似以上的访问步骤；

软件流程图：

代码实现思路

1. 接收奇门主动请求接口收到的XML类型的参数，将XML转换为奇门定义的对象，然后将奇门对象转换为我们自己系统的对象。
2. 判断请求的奇门接口名称走不同的业务实现方法，接口返回数据请参照淘宝奇门接口API文档
3. 各实现方法返回Map格式数据，转换为xml格式返回。

关键点(个人观点)

1. xml转为对象
2. 对象转为xml
3. 封装统一的接口响应
4. 对应各个接口的实现和数据返回

奇门对接关键代码

@RestController
@RequestMapping("/qiMen")
@RequiredArgsConstructor
@Slf4j
public class QiMenController {private final QiMenService qiMenService;@ApiModelProperty("奇门调用WMS数据")@RequestMapping(value="/apiRealization",produces="text/xml;charset=UTF-8")public byte[] apiRealization(HttpServletRequest request, HttpServletResponse response) throws IOException {byte[] result;Map<String, Object> resultMap = new HashMap<>();// API接口名称String methodVal = request.getParameter("method");// 验签CheckResult checkResult = QiMenUtils.checkSign(request);log.info("验签:{}",checkResult.isSuccess());if(!checkResult.isSuccess()) {resultMap.put("sub_code","sign-check-failure");resultMap.put("sub_message","Illegal request");resultMap.put("flag","failure");result = QiMenUtils.multilayerMapToXml(resultMap, false).getBytes(StandardCharsets.UTF_8);return result;}try {// 解析xml参数log.info("xml参数:{}", checkResult.getRequestBody());JSONObject jsonObject = JSONUtil.xmlToJson(checkResult.getRequestBody());log.info("jsonObject:{}", jsonObject);if(Objects.nonNull(jsonObject)) {if(!StringUtils.isBlank(methodVal)) {switch (methodVal) {case "entryorder.create":// 入库单创建接口resultMap = qiMenService.entryorderCreate(jsonObject);break;case "stockout.create":// 出库单创建接口resultMap = qiMenService.stockoutCreate(jsonObject);break;default:resultMap = RCode.failure(RCode.FAILURE,"接口名称method填写有误");break;}}else {resultMap = RCode.failure(RCode.FAILURE,"接口名称method不能为空");}result = QiMenUtils.multilayerMapToXml(resultMap, false).getBytes("UTF-8");}else {result = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>".getBytes("UTF-8");}} catch (BizException e) {resultMap = RCode.failure(RCode.FAILURE,e.getMessage());try {result = QiMenUtils.multilayerMapToXml(resultMap, false).getBytes("UTF-8");} catch (UnsupportedEncodingException e1) {return null;}} catch (Exception e) {log.error("操作失败:" + e + "-----" + e.getMessage());resultMap = RCode.failure(RCode.FAILURE,"操作失败");try {result = QiMenUtils.multilayerMapToXml(resultMap, false).getBytes("UTF-8");} catch (UnsupportedEncodingException e1) {return null;}}log.info("ERP调用响应结果 resultMap:{}",resultMap);return result;}@ApiModelProperty("WMS主动推送奇门数据")@PostMapping("/push/{method}")public Result pushQiMen(@PathVariable String method,@RequestBody JSONObject jsonObject) {QimenResponse response = null;switch (method) {case "entryorder.confirm":// 入库单确认response = qiMenService.entryorderConfirm(jsonObject);break;case "stockout.confirm":// 出库单确认response = qiMenService.stockoutConfirm(jsonObject);break;default:break;}return RCode.result(response);}
}

@RequiredArgsConstructor
@Slf4j
@Service
public class QiMenServiceImpl implements QiMenService {public static final String XML_KEY = "request";/*** 入库单创建** @param jsonObject* @return*/@Overridepublic Map<String, Object> entryorderCreate(JSONObject jsonObject) {// 将请求头的数据转换为当前系统对应的dto类EntryorderCreateRequest bean = jsonObject.getBean(XML_KEY, EntryorderCreateRequest.class);List<JSONObject> list = jsonObject.getByPath("request.orderLines.orderLine", List.class);if (CollUtil.isEmpty(list)) {throw new BizException("入库单详情列表为空!");}List<EntryorderCreateRequest.OrderLine> orderLines = new ArrayList<>();for (JSONObject object : list) {orderLines.add(object.toBean(EntryorderCreateRequest.OrderLine.class));}bean.setOrderLines(orderLines);QiMenReceiptOrderDTO receiptOrderDTO = QiMenConvert.entryorderCreate(bean);// 远程调用创建入库单Result result = qiMenRequestInBound.qiMenRequestInBound(receiptOrderDTO);// 包装响应结果return RCode.result(result);}/*** WMS调用接口，回传入库单信息;** @param jsonObject* @return*/@Overridepublic QimenResponse entryorderConfirm(JSONObject jsonObject) {// wms dto 转换为 EntryorderConfirmRequestQiMenInboundAckVO bean = JSONUtil.toBean(jsonObject, QiMenInboundAckVO.class);EntryorderConfirmRequest req = QiMenConvert.entryorderConfirm(bean);req.setVersion("2.0");req.setCustomerId("mockCustomerId");  // mockCustomerId 挡板测试的客户idQimenClient client = getClient();EntryorderConfirmResponse rsp = new EntryorderConfirmResponse();try {rsp = client.execute(req);} catch (ApiException e) {log.error("调用奇门异常:",e);rsp.setMessage(e.getMessage());}return rsp;}

public class QiMenUtils {private final static String secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxx";private final static String appkey = "xxxx";// 联调地址 http://qimen.api.taobao.com/router/qmtest// 正式地址 https://qimen.api.taobao.com/router/qimen/serviceprivate final static String url = "https://qimen.api.taobao.com/router/qimen/service";/*** wms主动发起请求奇门的接口  创建一个连接* @return*/public static QimenClient getClient() {return new DefaultQimenClient(url, appkey, secret);}/*** 验签 调用sdk中的签名验证方法* @param request* @return*/@SneakyThrowspublic static CheckResult checkSign(HttpServletRequest request) {return SpiUtils.checkSign(request, secret);}/*** (多层)map转换为xml格式字符串** @param map 需要转换为xml的map* @param isCDATA 是否加入CDATA标识符 true:加入 false:不加入* @return xml字符串* @throws UnsupportedEncodingException*/public static String multilayerMapToXml(Map<String, Object> map, boolean isCDATA) throws UnsupportedEncodingException{String parentName = "response";Document doc = DocumentHelper.createDocument();doc.addElement(parentName);String xml = recursionMapToXml(doc.getRootElement(), parentName, map, isCDATA);return formatXML(xml);}/*** multilayerMapToXml核心方法，递归调用** @param element 节点元素* @param parentName 根元素属性名* @param map 需要转换为xml的map* @param isCDATA 是否加入CDATA标识符 true:加入 false:不加入* @return xml字符串*/@SuppressWarnings("unchecked")private static String recursionMapToXml(Element element, String parentName, Map<String, Object> map, boolean isCDATA) {Element xmlElement = element.addElement(parentName);map.keySet().forEach(key -> {Object obj = map.get(key);if (obj instanceof Map) {recursionMapToXml(xmlElement, key, (Map<String, Object>)obj, isCDATA);} else {String value = obj == null ? "" : obj.toString();if (isCDATA) {xmlElement.addElement(key).addCDATA(value);} else {xmlElement.addElement(key).addText(value);}}});return xmlElement.asXML();}/*** 格式化xml,显示为容易看的XML格式** @param xml 需要格式化的xml字符串* @return*/public static String formatXML(String xml) {String requestXML = null;try {// 解析器SAXReader reader = new SAXReader();Document document = reader.read(new StringReader(xml));if (null != document) {StringWriter stringWriter = new StringWriter();// 格式化,每一级前的空格OutputFormat format = new OutputFormat("", true);// xml声明与内容是否添加空行format.setNewLineAfterDeclaration(false);// 是否设置xml声明头部format.setSuppressDeclaration(false);// 是否分行format.setNewlines(true);XMLWriter writer = new XMLWriter(stringWriter, format);writer.write(document);writer.flush();writer.close();requestXML = stringWriter.getBuffer().toString();}return requestXML;} catch (Exception e) {e.printStackTrace();return null;}}
}

可能遇到的问题

xml转换为对象

对象list转换为xml

你知道的越多，你不知道的越多。