一、产品对接背景

修改地址是客服常见操作，而现实中很多商家由于业务不断扩大使用了ERP等软件，修改地址往往需要登录ERP后台进行操作，费时费力而且影响了消费者顺畅体验。
由此我们设计了整个开发链路：

当消费者购买下单并付款后，由【千牛】的【客户服务平台】可以自动触发核对订单卡片以及【订单详情页】等地方支持买家进行修改地址，买家可以点击确认或者修改。

ERP打通后可以使买家修改的新地址通过奇门API接口传输给ERP进行直接修改，修改后再同步修改卖家中心的地址，两步都完成后算作链路完成并返回给买家已完成修改的消息。中间如果其中一环失败则定义为修改失败，并通知告知让客服人工帮助修改。

 

二、产品对接介绍

 

 

当消费者点击新的地址后，则传输给ERP进行判断是否能修改，如果能修改则进行修改过程。修改成功与否在进行返回。
如果ERP没有进行打通绑定，则直接出文案转告给在线客服，告知消费者需要修改地址（不会真正的触发修改流程）。
*自助修改地址接口不做修改判断，所有修改逻辑由ERP进行完成，erp返回修改成功并且商家同步去触发修改卖家中心地址成功后才认为是成功，否则都提示修改失败，请联系客服进行修改。

修改成功：消费者会收到系统消息提示【修改成功】，更新原有修改的卡片按钮变成【修改成功】，并下发一张新地址的卡片
修改失败：消费者会收到系统消息提示【修改失败】，并会更新原修改的卡片告知提示【修改失败】。

【修改失败】的会根据最近联系人原则或者指定账号发消息给到客服，告知客服需要人工帮助修改地址。

整体过程消费者修改地址效率增强，客服服务压力降低，实现良好的用户体验升级。

三、开发对接说明

1. 视频说明（视频教程+时间段落）

直播地址：点击查看直播视频

https://h5.m.taobao.com/qn/pc/niuba-interview.html#!/interview/10508874

2. 对接流程图

 

1）对接流程说明：

在奇门（qimen.taobao.com）内确认是否获得【官方场景】-【商业IM自助修改地址】的选项（如果没有，请联系婉清wanjie.ywj@alibaba-inc.com），如图：

*如果没有奇门账号需要点击申请创建：

使用自己需要使用的erp的appkey

③开始对接官方场景

奇门对接官方场景的方法：//open.taobao.com/doc.htm?docId=106849&docType=1

④对接改地址接口（如下接口流程）

⑤测试发布接口

常见接口自测的错误排查：

*奇门对接中的排查错误手册：//open.taobao.com/doc.htm?docId=108961&docType=1

详细对接中错误码排查：

http://qndoc.taobao.com/docs/doc.htm.htm?spm=0.7629140.0.0.7641Q55XQ55XSO&articleId=101645&docType=1&treeId=1

 ⑥绑定官方的appkey; 23647480

如果涉及路由需要单独设置，并且需要区分组合授权的方式，（配置一样的，只会调用第一个）

⑦测试完成，发布接口 

 

3. 接口流程图

1)改地址产品实现主流程

• 当买家付款完，开启自动化任务核单功能的商家，系统自动发送一张核对地址卡片 其中功能按钮包括：【确认】【修改】；或者通过订单详情页入口进行修改；
• 买家点击【确认】即两个按钮变成文案【订单已确认】
• 如果点击【修改】发送抽屉卡片，用户可以选择自己地址库的地址
• 选择更换的地址后，客户端发送富文本点击CAS协议消息
• CEP服务端收到修改地址请求后，通过TOP提供的SPI接口，调用ERP系统实现的修改地址接口进行该订单地址的修改
• 修改成功下发一张新卡片，底部的按钮变成文本【地址已修改成功】并且原卡片两个按钮显示更新成文本【已操作修改】
• 修改失败原卡片两个按钮变成文本【地址修改失败，请联系客服进行帮助】

2)改地址接口文档

• 自助修改地址接口名：taobao.qianniu.cloudkefu.address.self.modify
• API接口入参说明

l   属性	l   子属性	l   类型	l   描述	l   是否必填
l   buyerNick	l   -	l   String	l   买家Nick	l   是
l   sellerNick	l   -	l   String	l   卖家Nick	l   是
l   bizOrderId	l   -	l   String	l   交易订单ID	l   是
l   modifiedAddress	l   country	l   String	l   国家（没填默认表示中国）	l   否
l   -	l   province	l   String	l   省份	l   是
l   -	l   city	l   String	l   城市	l   是
l   -	l   area	l   String	l   区	l   是
l   -	l   town	l   String	l   街道	l   否
l   -	l   addressDetail	l   String	l   详细地址	l   否
l   -	l   postCode	l   String	l   邮编	l   否
l   -	l   name	l   String	l   收货人姓名（不填表示收货人和原来一致）	l   否
l   -	l   phone	l   String	l   收货人手机号（不填表示收货人和原来一直）	l   否
l   originalAddress	l   country	l   String	l   国家（没填默认表示中国）	l   否
l   -	l   province	l   String	l   省份	l   是
l   -	l   city	l   String	l   城市	l   是
l   -	l   area	l   String	l   区	l   是
l   -	l   town	l   String	l   街道	l   否
l   -	l   addressDetail	l   String	l   详细地址	l   否
l   -	l   postCode	l   String	l   邮编	l   否
l   -	l   name	l   String	l   收货人姓名（不填表示收货人和原来一致）	l   否
l   -	l   phone	l   String	l   收货人手机号（不填表示收货人和原来一直）	l   否

• API接口返回结果其中3种示例：
• {
              "result": {
                "success": true
              }
          }
  
          {
              "result": {
                "errorCode": "sign-check-failure",
                "errorMsg": "Illegal request",
                "success": false
              }
          }
          
          {
              "result": {
                "errorCode": "modify-address-forbid",
                "errorMsg": "......detail reason",
                "success": false
              }
          }

说明：success返回修改成功或失败，目前业务上失败主要定义， success必填，success为false时，errorCode和errorMsg必填，开放平台规定签名校验失败必须返回如下值。

• error_code: sign-check-failure               error_msg：Illegal request    

3）自助修改地址接口的这边实现的demo（仅供参考）

* @author xiang

 * @version $Id: AddressModifyControl.java, v 0.1 2017-06-26 下午8:53 xiang Exp

 */

@Controller

@RequestMapping("/external/bots")

public class AddressModifyDemo {

  

 private static final Logger logger = LoggerFactory.getLogger(AddressModifyDemo.class);

 @RequestMapping(value = "/address/modify/{env}")

 @ResponseBody

  

 public JSONObject addressModifyDemo(HttpServletRequest request, @PathVariable String env) {

 JSONObject jsonObject = new JSONObject();

 String targetAppSecret = "b5de21xxxxxxxxxxxxxxxxxxxxxxxxxxx"; // 自己应用的appkey对应的appSecret

 JSONObject result = new JSONObject();

 try {

 if (StringUtils.equals(env, "daily")) { // 自己简单测试便于控制的参数，外部实现时请忽略

 result.put("success", true);

 }

 else {

 CheckResult checkResult = SpiUtils.checkSign(request, targetAppSecret);

 if (checkResult.isSuccess()) {

 // 业务逻辑 地址修改。。

 // do modify address

 String requestParam = checkResult.getRequestBody();

 JSONObject paramsObject = JSON.parseObject(requestParam);

 // ............获取paramsObject中的参数, 进行业务处理，成功返回如下，失败返回错误信息和错误码

 result.put("success", true);

 } else { // 验签失败固定返回格式

 result.put("success", false);

 result.put("errorCode", "sign-check-failure");

 result.put("errorMsg", "Illegal request");

 }

 // 日志信息

 }

 } catch (Exception e) {

 // 异常日志处理，返回错误信息

 result.put("success", false);

 result.put("errorCode", "XXXXXXX");

 result.put("errorMsg", "XXXXXXX");

 }

 jsonObject.put("result", result);

 return jsonObject;

 }

}

4）自助修改地址接口统一返回的错误码（注意：需要统一一致错误码）

匹配实际含义情况下直接选取需要返回的错误码进行返回，用于帮助商家和消费者查询错误原因。

错误码和错误描述需要统一，方便进行统计和识别。

接口是POST请求，数据提交方式为：application/json ，上面示例中也有签名校验后获取数据的方法，接口返回格式必须json，如务必如上面描述的返回结果json示例，其他如xml方式返回测试都会失败4. 注意事项

• 在奇门应用控制台接入时，请先提交要开发测试的appkey给到接口定义者，这边需要先进行授权，否则奇门控制台找不到需要实现的接口
• 接口实现好后，发布上线，先在奇门控制台自己进行自测，自测通过后，在控制台进行发布
• 奇门控制台自测，如果过程出现出现如下常见错误，基本是接口返回格式不正确，没有严格按照接口定义的json数据返回，请先核对字段及格式是否符合要求
• 测试后发布，奇门平台会进行验签调用，务必按如上接口说明，签名失败的返回数据格式：{"result":{"errorCode":"sign-check-failure","errorMsg":"Illegal request","success":false}}
• 发布通过后，请在奇门控制台上对应实现接口下‘授权配置’页面给appkey为：23647480进行授权，这个appkey是这边发起请求的appkey，授权后这边就可以发起测试和联调（奇门文档有说明如何授权）
• 关于最后的整个过程的联调测试问题，请先确定自己对应的商家开通了自动化核单任务，并且先提供要测试的买家账号和应用实现方的appkey，这边对买家账号进行白名单控制以及该测试账号与应用方的路由绑定，从而不会影响商家的自动化任务核单的整体功能，接口实现方可以考虑在短期内发布一个测试商品进行下单付款后的整体流程测试。
• 更新同步地址接口：taobao.trade.shippingaddress.update；用于更改后进行同步地址。此接口是为了保证发货地址与消费者在订单详情页看到的地址保持一致性，如果是消费者自助发起改地址（通过奇门API与三方订单软件交互）则不需要调用此接口，平台侧会更新交易订单上的地址；如果是ERP内部提供改地址的功能给到商家使用，则必须要调用 taobao.trade.shippingaddress.update 将地址同步给平台侧。当前如果已经对接了该接口同步地址的服务商暂时保持现状接口。

 

错误文档手册排查问题：

奇门对接中的排查错误手册：//open.taobao.com/doc.htm?docId=108961&docType=1

详细对接中错误码排查：http://qndoc.taobao.com/docs/doc.htm.htm?spm=0.7629140.0.0.7641Q55XQ55XSO&articleId=101645&docType=1&treeId=1

 

四、改地址订单未下发问题说明&优化方案

1.背景说明：

   目前在自助改地址功能接入和实际业务数据处理过程中，存在部分消费者发起自助改地址申请的失败的情况，目前此类数据在系统交互上是返回失败处理。经分析调研，部分是由于订单处理系统未获取到订单或未及时转单导致的(大促期间这类问题影响将被急剧放大)。这类数据的存在会一定程度影响到自助改地址功能的数据处理成功率，影响最终订单发货履约的准确性，对服务体验有直观的影响。因此我们需要针对这些已经明确的异常情况进行优化处理，以达到提升功能的准确率以及服务体验优化的目的。

2.问题场景枚举说明：

    经分析判定，目前已经明确定义识别出，会导致订单改地址数据处理失败的问题原因有2个。本次方案将重点解决如下这2个场景的问题数据。

  问题原因场景1:

   平台已推送订单，但是ERP系统未及时完成转单同步订单，导致无法处理

  问题原因场景2:

   平台未正常推送订单，ERP系统无法获取订单数据，导致无法处理

3.链路优化解决方案：

    从整体产品流程上，如下图标注出问题发生的环节场景，对整个数据处理链路流程做了表达提供参考。

 

1）问题原因场景1具体优化调整方案：

当ERP系统接收到改地址请求，在系统内部获取不到订单，可能是由于未及时完成转单。需要服务商按以下方案处理：

      步骤一：同步针对该订单完成一次转单，如果在订单RDS库未查询到该订单则需要按问题场景2处理，如果查询到了该订单则正常完成后续改地址链路处理。

      步骤二：转单加上改地址处理如果能在3秒内完成，则可以同步将结果返回给平台，如果无法在3秒内完成，则可以触发一个转单的异步任务，通过标准化异常信息(参见下文：调整环节1)，并通过奇门接口返回告知平台侧订单未推送处理异常。

      步骤三：平台侧针对出现“订单未推送”的异常返回，页面提示用户改地址申请等待商家处理中，并根据响应策略进行重试直至成功，具体重试策略（参见下文：调整环节2）

步骤四（可选）：订单软件对步骤二中返回2001的订单做延迟发货处理（理论上延迟发货时长不超过30分钟）。

调整环节1.服务商通过奇门接口规范返回此问题的错误码和原因描述的实现：

通过taobao.qianniu.cloudkefu.address.self.modify接口回传异常结果，大家针对此场景统一返回错误码：2001，错误信息描述统一：订单未接收。具体的返回形式如下。平台以此为标准异常信息进行识别及推进后续的处理，请服务商侧务必遵循标准化返回。

 

  {            

     "result": {              

     "errorCode": "2001",              

     "errorMsg": "订单未接收",              

     "success": false     }        

  }

调整环节2.平台侧针对出现“订单未推送”的异常的申请单进行轮询，直到ERP返回明确的成功或失败的结果[目前指定的重试策略为最长重试时长不超过30分钟，最多重试次数为5次，最小重试间隔为60秒]

 

2）问题原因场景2具体优化调整方案：

当订单软件返回2001错误码时，平台如果检测到该订单未推送到推送库，则会开启一条直推通道，及时将该订单进行推送处理，并做改地址重试。

      步骤一：订单软件查询推送库无此订单，通过标准化异常信息(参见下文：调整环节1)，并通过奇门接口返回告知平台侧订单未推送处理异常。

      步骤二：平台侧针对出现“订单未推送”的异常返回，页面提示用户改地址申请等待商家处理中，同时针对该订单做一次直推动作，并根据响应策略进行重试直至成功，具体重试策略（参见下文：调整环节2）

      步骤三：订单软件接收到改地址请求后，按照场景1中的方案做处理即可。

步骤四（可选）：订单软件对步骤二中返回2001的订单做延迟发货处理（理论上延迟发货时长不超过30分钟）。

调整环节1.服务商通过奇门接口规范返回此问题的错误码和原因描述的实现：

通过taobao.qianniu.cloudkefu.address.self.modify接口回传异常结果，大家针对此场景统一返回错误码：2001，错误信息描述统一：订单未接收。具体的返回形式如下。平台以此为标准异常信息进行识别及推进后续的处理，请服务商侧务必遵循标准化返回。

  {            

     "result": {              

     "errorCode": "2001",              

     "errorMsg": "订单未接收",              

     "success": false     }        

  }

调整环节2.平台侧针对出现“订单未推送”的异常的申请单进行轮询，直到ERP返回明确的成功或失败的结果[目前指定的重试策略为 最长重试时长不超过30分钟，最多重试次数为5次，最小重试间隔为60秒]

 

FAQ

关于此文档暂时还没有FAQ