速卖通开放平台预约交货模块开发指南

2022年10月15日 1998点热度 5人点赞 0条评论

速卖通开放平台，最近新增加一个功能模块，就是：预约交货的功能。简单说，就是让包裹更早的能够上网、可以快速查询什么的，有点像虾皮平台的首公里功能。其实也不算最近，上半年5月份的时候就开始推这个功能了，据说API也是升级了好几个版本，10月19日正式上线。至于能不能顺利上线，不太清楚，但开发过程中确实遇到几个坑，这篇文档就是帮你填上。PS：net或java等任何语言都可以阅读。

填坑之前，必要的API文档是必须要看的。友情提醒：要认真看，不能不信，但也不要全信。推荐：开发过程中，可以借鉴每个API的示例Demo代码

API文档

预约交货的API在这个菜单下面

帮助文档

Table of Contents

1、交接单的创建？

这应该是疑惑最多的API了。速卖通给了2个交接单的API，一个是创建草稿、一个是直接发布。这里其实直接使用发布的API就可以。这里要详细讲解下面这2个参数seller_parcel_order_list和order_code_list

1.1、参数：seller_parcel_order_list

这个参数是给跨店铺用的。也就是说，如果用了这个参数，那1.2的参数是不用传值的，直接null即可。还有这个参数里有seller_id和user_nick。文档说这2个参数只需要传一个就行了，真正含义是不要出现，如下图所示。如果用user_nick但seller_id标记为0，也是不行的。

还有，如果你想使用seller_id的话，是有API[AE商家-aliexpress.merchant.profile.get]可以使用，但你的App必须是商用。如果是自用，是获取不到的。只能通过授权时得到

1.2、参数：order_code_list

这个参数简单，直接传lpNumber的数组就行了。只对同一店铺使用。再强调下，lpNumber这个值是在线上发货->填写发货通知的时候，获取到的。连同下面要讲的ResourceCode，也是这个API里获取

2、小包是自寄或自送

我们在店铺后台的[预约发货]页面里，可以看到小包的信息，正常情况应该是上门揽收。如果是自寄或自送，说明你在创建线上发货订单的时候，参数[addressDtos]里的pickup.address_id这个值没有传。

但是店铺后台的地址管理里，只有发货地址和退货地址。

咨询客服的回复：发货地址的中文格式就是揽收地址。这样，我们调用获取地址的API时，是能返回pickup这个地址列表，保存起来就行了。
所以有个蒙B的事：pickup_info和return_info，这2个参数到底有木有用？

3、ResourceCode

这个参数的含义在帮助文档里有过解释，这里再解释下，加深下印象。它就是交货仓库（或者叫揽收仓库），比如我们有10个小包，5个小包的交货仓库是A、另外5个是B。那么这时候就要创建2个交货单了，相当于一个交货仓库一个交货单。另外，给个提示：这5个小包是可以跨店铺的
这个参数值，是在填写发货通知的API返回的，在Logistics_Service_List的返回值里，找找。以前没保存下来的，现在要保存下来了。

4、打印面单

可以调用[cainiao.global.handover.pdf.get]这个API获取，返回的是base64转码后生成运单标签的pdf字节流。这里给出net版的生成pdf文件代码

FileStream fileStream = new FileStream(pdfFile, FileMode.Create);
byte[] buffer = Convert.FromBase64String(modelRes213.cainiao_global_handover_pdf_get_response.result.data);
fileStream.Write(buffer, 0, buffer.Length);
fileStream.Close();

5、交接单发布后需手动追加

上线后提交发布完交接单后，直接打印发现报错。到店铺后台看，也是不允许打包，只有追加操作。追加完1个包后，才发现可以打印。看来发布成功后，要追加至少1个包才可以。

整个流程走下来，差不多这些疑难问题吧。其实不复杂，但如果你不知道怎么解决，也挺烦人的。尤其是它们API的返回信息，五花八门的，就是没说到点儿上。。。比如：
返回错误1：哎呀，系统被挤爆啦，请过段时间再来试试吧
返回错误2：System is busy now. Please try again later
还有他们的钉钉群回复速度，比蜗牛还慢。。。

其实所有的API文档、帮助文档都不及测试用例来得实在，直接给出下面的代码，不香吗？

//2.1,(没有使用,不需要测试)创建物流订单

////2.2,(ok)异常物流订单查询
//DateTime nowTime = DateTime.Now;
//AliExpress2LogisticsAbnormalorderQueryRootParamModel modelP22 = new AliExpress2LogisticsAbnormalorderQueryRootParamModel();
//modelP22.gmt_create_end = nowTime.ToString(BaseHelper.DateTimeFormat);
//modelP22.gmt_create_start = nowTime.AddDays(-10).ToString(BaseHelper.DateTimeFormat);
//modelP22.page_size = 50;
//var modelRes22 = ali2Service.LogisticsAbnormalorderQuery(loginId, modelP22);

////2.3,(ok)批次追加大包
////{
////  "handover_order_id": 10008493434,
////  "handover_content_code": "LP00537149036503",    //用的是这个。。。
////  "handover_content_id": 10008673784
////}
//AliExpress2CainiaoHandoverContentSubbagAddRootParamModel modelP23 = new AliExpress2CainiaoHandoverContentSubbagAddRootParamModel();
//modelP23.user_info = new AliExpress2CainiaoHandoverContentSubbagAddUserInfoParamModel()
//{
//    top_user_key = loginId,
//};
//modelP23.order_code = "LP00537149036503";
//modelP23.add_subbag_quantity = 5;
//var model23 = ali2Service.CainiaoHandoverContentSubbagAdd(loginId, modelP23);

////2.4,提供给ISV通过该接口修改交接单
//AliExpress2CainiaoHandoverUpdateRootParamModel modelP24 = new AliExpress2CainiaoHandoverUpdateRootParamModel();
//modelP24.weight_unit = "kg";
//modelP24.weight = 20;
//modelP24.handover_order_id = 123456;
//modelP24.user_info = new AliExpress2CainiaoLogisticsUserInfoParamModel() { top_user_key = loginId };
//modelP24.remark = "提交时间：" + DateTime.Now;
//modelP24.return_info = new AliExpress2CainiaoLogisticsAddress2ParamModel();
//modelP24.pickup_info = new AliExpress2CainiaoLogisticsAddress2ParamModel();
//modelP24.order_code_list = new List<string>() { "123455", "123456" };
//modelP24.type = "cainiao_pickup";
//modelP24.client = loginId;
//modelP24.locale = "zh_CN";            
//var modelRes24 = ali2Service.CainiaoHandoverUpdate(loginId, modelP24);

////2.5,(ok3,可以不使用,直接提交发布)提供给ISV通过该接口创建交接单草稿
////注:不是订单号,也不是运单号
//List<string> listLogisticsNo = new List<string>() { lpNumber };
//var modelRes25 = ali2Service.CainiaoHandoverSaveDraft(loginId, listLogisticsNo);

////2.6,(ok)提供给ISV通过该接口取消交接单
//AliExpress2CainiaoHandoverCancelRootParamModel modelP241 = new AliExpress2CainiaoHandoverCancelRootParamModel();
//modelP241.user_info = new AliExpress2CainiaoHandoverCancelUserInfoParamModel() { top_user_key = loginId };
//modelP241.handover_order_id = handoverOrderId.ToString();
//modelP241.handover_content_id = handoverContentId.ToString();
//modelP241.client = loginId;
//var modelRes241 = ali2Service.CainiaoHandoverCancel(loginId, modelP241);

////2.7,(ok)提供给ISV通过该接口提交发布交接单
////注1:handover_order_id,这个参数也不需要,直接生成
//AliExpress2CainiaoHandoverCommitRootParamModel modelP27 = new AliExpress2CainiaoHandoverCommitRootParamModel();

////2.7.1,跨店铺时用seller_parcel_order_list
////注1:seller_id不传的意思是不用出现...
////注1.1:如果这个参数有值,那外部的order_code_list就不需要有值            
//modelP27.seller_parcel_order_list = new List<AliExpress2CainiaoHandoverCommitSellerParcelOrderListParamModel>();

//AliExpress2CainiaoHandoverCommitSellerParcelOrderListParamModel modelT11 = new AliExpress2CainiaoHandoverCommitSellerParcelOrderListParamModel();
//modelT11.user_nick = loginId;
//modelT11.order_code_list = lpNumbers;
//modelP27.seller_parcel_order_list.Add(modelT11);

//AliExpress2CainiaoHandoverCommitSellerParcelOrderListParamModel modelT12 = new AliExpress2CainiaoHandoverCommitSellerParcelOrderListParamModel();
//modelT12.user_nick = loginId119;
//modelT12.order_code_list = lpNumbers119;
//modelP27.seller_parcel_order_list.Add(modelT12);

//////2.7.2,单店铺时用order_code_list
////modelP27.order_code_list = lpNumbers;

//modelP27.remark = "提交时间：" + DateTime.Now;
//modelP27.return_info = new AliExpress2CainiaoLogisticsAddress2ParamModel();
//modelP27.pickup_info = new AliExpress2CainiaoLogisticsAddress2ParamModel();
//modelP27.weight = 20;
//modelP27.user_info = new AliExpress2CainiaoLogisticsUserInfoParamModel() { top_user_key = loginId };
//modelP27.weight_unit = "kg";
//modelP27.type = "cainiao_pickup";
//modelP27.client = loginId;
//modelP27.locale = "zh_CN";
//modelP27.features = new AliExpress2CainiaoHandoverCommitFeatureParamModel();
//modelP27.appointment_type = "batch";
//var modelRes27 = ali2Service.CainiaoHandoverCommit(loginId, modelP27);

////2.8,(ok)提供给ISV通过该接口查询小包信息
//AliExpress2CainiaoHandoverParcelQueryRootParamModel modelP28 = new AliExpress2CainiaoHandoverParcelQueryRootParamModel();
////modelP28.order_code = lpNumber;             //在交货单里的,获取成功
//modelP28.order_code = "LP00536706865277";   //没在交货单里的,获取成功
//modelP28.user_info = new AliExpress2CainiaoLogisticsUserInfoParamModel() { top_user_key = loginId };
//modelP28.client = loginId;
//var modelRes28 = ali2Service.CainiaoHandoverParcelQuery(loginId, modelP28);

//2.9,(暂时不需要,没有调试)提供给ISV通过该接口获取面单云打印数据

////2.10,(ok)查询出所有的实际承运商
//var modelRes28 = ali2Service.CainiaoLogisticsCarrierQueryList(loginId, new AliExpress2CainiaoLogisticsCarrierQueryListRootParamModel());

////2.11,(ok)查询大包详情
//AliExpress2CainiaoHandoverContentQueryRootParamModel modelP211 = new AliExpress2CainiaoHandoverContentQueryRootParamModel();
//modelP211.user_info = new AliExpress2CainiaoLogisticsUserInfoParamModel() { top_user_key = loginId };
//modelP211.order_code = "LP00536791767085";
//modelP211.tracking_number = "";
//modelP211.client = loginId;
//modelP211.locale = "zh_CN";
//var modelRes211 = ali2Service.CainiaoHandoverContentQuery(loginId, modelP211);

////2.12,(ok3)根据交易单号查询可用的解决方案
//var modelRes210 = ali2Service.CainiaoSolutionInquiry(loginId, billNo);

////2.13,(ok3)返回指定大包面单的PDF文件数据
//AliExpress2CainiaoHandoverPdfGetRootParamModel modelP231 = new AliExpress2CainiaoHandoverPdfGetRootParamModel();
//modelP231.user_info = new AliExpress2CainiaoLogisticsUserInfoParamModel() { top_user_key = loginId };
//modelP231.client = loginId;
//modelP231.locale = "zh_CN";
//modelP231.handover_content_id = "10008673784";
//modelP231.type = 4;
//var modelRes213 = ali2Service.CainiaoHandoverPdfGet(loginId, modelP231);

////2.14,(暂时不需要,没有调试)返回直接解决方案的指定物流服务的可用资源列表
//AliExpress2CainiaoSolutionServiceResourceQueryRootParamModel modelP214 = new AliExpress2CainiaoSolutionServiceResourceQueryRootParamModel();
//modelP214.sender_param = new AliExpress2CainiaoSolutionServiceResourceQuerySenderParamModel() { seller_address_id = 112523121 };
//modelP214.seller_param = new AliExpress2CainiaoSolutionServiceResourceQuerySellerParamModel() { top_user_key = loginId };

//AliExpress2CainiaoSolutionServiceResourceQuerySolutionServiceResParamModel modelT11 = new AliExpress2CainiaoSolutionServiceResourceQuerySolutionServiceResParamModel();
//modelT11.service_param = new AliExpress2CainiaoSolutionServiceResourceQuerySolutionServiceResServiceParamModel();

//modelP214.solution_service_res_param = new List<AliExpress2CainiaoSolutionServiceResourceQuerySolutionServiceResParamModel>();
//modelP214.solution_service_res_param.Add(modelT11);

//var modelRes214 = ali2Service.CainiaoSolutionServiceResourceQuery(loginId, modelP214);