注意:以下文档只适用于TOP接口,请谨慎使用!

消费者自助修改地址开发对接手册

更新时间:2019/05/15 访问次数:5125

 

一、产品对接背景

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

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

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

 

二、产品对接介绍

 

 

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

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

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

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

三、开发对接说明

1. 视频说明(视频教程+时间段落)

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

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

2. 对接流程图

1)重点事项:

  • 申报功能接入白名单:

将erp/oms/wms/内部系统的appkey要第一步报给小二

审批小二人联系邮箱:

摘星(zhaixing.ljp@alibaba-inc.com);白名单erp开启人

秦思(qinsi.sj@taobao.com);审批开通商家授权人

枫眠(xiaoxing.zxx@alibaba-inc.com);商家名单收集人

 

2)对接流程说明:

①将自己erp的appkey申报给:龙正、秦思、枫眠

②授权后将在奇门(qimen.taobao.com)内获得【官方场景】-【商业IM自助修改地址】的选项,如图:

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

使用自己需要使用的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

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

⑥修改完成后,需要调用官方更新地址接口:taobao.trade.shippingaddress.update(调用此接口进行更新交易显示地址,防止再次拉下来的地址是旧地址)

⑦测试完成,发布接口

⑧按照邮件格式发布给:秦思、枫眠进行申请测试商家线上绑定测试

例如:

12405954

百草味旗舰店

优可力旗舰店

元逸专卖店

三只松鼠

回复完成即绑定完成(为什么要让erp发送:商家自己并不知道自己的erp是哪个appkey,多数erp有多个appkey)

⑧商家在【千牛】-【客户服务平台】-【自动化任务】内开启自助核单功能-【选择自助修改地址选项】即可

客户服务平台设置教程:https://kehufuwu.bbs.taobao.com/detail.html?postId=8830606

 

 

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    
  • error_code: modify-address-forbid        error_msg:表示不允许修改,附上更详细的说明
  • error_code: modify-address-failed        error_msg:表示业务上修改地址失败, 比如ERP系统自身在修改的过程中产生的其他错误导致修改失败,附上更详细的说明
  • error_code: part-sub-order-failed        error_msg:有些在修改订单下所有子订单的地址,部分成功部分失败时的返回, 这种情况下返回的错误原因,今后可以考虑增加透出给买家

 

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自助修改地址接口统一返回的错误码(注意:需要统一一致错误errorcode)

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

errormsg字段继续可以填写erp内部信息,只是errorcode需要统一,方便进行统计和识别。

自助修改地址错误码集合
errorcode 错误透出信息(给消费者) 实际含义
1101 商家未开启该功能,请联系商家修改 商家erp没有开启这个功能
1102 订单商家审核中无法修改,请联系商家修改 订单进入审单环节/已过审核状态
1103 订单已安排发货无法修改,请联系商家客服修改 订单已进入拣货环节
1104 订单已安排发货无法修改,请联系商家修改 订单已进入配货环节
1105 订单已安排发货无法修改,请联系商家修改 订单已进入仓库环节/预约库存单
1106 订单已安排发货无法修改,请联系商家修改 订单已进入出库环节
1107 订单已安排发货无法修改,请联系商家修改 订单已进入发货环节
1108 库存占用失败无法修改,请联系商家修改 订单商品修改占用库存失败
1109 商家改地址功能过期无法修改,请联系商家修改 店铺erp授权过期/店铺授权token过期
1110 地址格式有误,请联系商家修改 无法解析订单地址/地址识别错误/地址信息缺失
1111 订单处于异常状态无法修改,请联系商家修改 订单无法识别/未下载订单/识别订单有误
1112 新地址会导致发货仓变更,请联系商家修改 跨仓修改失败/不允许跨仓修改
1113 订单处理中不支持修改,请联系商家修改 订单已拆单不支持修改
1114 订单类型不支持修改,请联系商家修改 分销订单不支持修改
1115 修改失败,请联系商家修改 修改失败/修改中失败
1116 付款后地址只允许修改一次,请勿重复操作! 多次请求并且失败/HAS_MODIFIED_ADDRESS
1117 商家系统超时,请联系商家确认修改情况 3S还未返回修改结果导致修改超时
1118 街道地址填写信息有误,请联系商家修改 四级地址(town)识别有误造成错误
1119 订单已申请退款,无法修改 退款订单无法修改/HAS_REFUND
1000 订单修改处理失败,请联系商家修改 无法识别erp的返回信息

 

4. 注意事项

  • 接口是POST请求,数据提交方式为:application/json ,上面示例中也有签名校验后获取数据的方法,接口返回格式必须json,如务必如上面描述的返回结果json示例,其他如xml方式返回测试都会失败
  • 在奇门应用控制台接入时,请先提交要开发测试的appkey给到接口定义者,这边需要先进行授权,否则奇门控制台找不到需要实现的接口
  • 接口实现好后,发布上线,先在奇门控制台自己进行自测,自测通过后,在控制台进行发布
  • 奇门控制台自测,如果过程出现出现如下常见错误,基本是接口返回格式不正确,没有严格按照接口定义的json数据返回,请先核对字段及格式是否符合要求
  • 测试后发布,奇门平台会进行验签调用,务必按如上接口说明,签名失败的返回数据格式:{"result":{"errorCode":"sign-check-failure","errorMsg":"Illegal request","success":false}}
  • 发布通过后,请在奇门控制台上对应实现接口下‘授权配置’页面给appkey为:23647480进行授权,这个appkey是这边发起请求的appkey,授权后这边就可以发起测试和联调(奇门文档有说明如何授权)
  • 关于最后的整个过程的联调测试问题,请先确定自己对应的商家开通了自动化核单任务,并且先提供要测试的买家账号和应用实现方的appkey,这边对买家账号进行白名单控制以及该测试账号与应用方的路由绑定,从而不会影响商家的自动化任务核单的整体功能,接口实现方可以考虑在短期内发布一个测试商品进行下单付款后的整体流程测试。
  • 更新同步地址接口: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

 

 

 

FAQ

关于此文档暂时还没有FAQ
返回
顶部