🆕 #2574 【小程序】物流服务增加即时配送查询相关接口

weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/WxMaExpressService.java

@@ -136,4 +136,7 @@ public interface WxMaExpressService {
    * @throws WxErrorException 模拟更新订单状态失败时返回
    */
   void testUpdateOrder(WxMaExpressTestUpdateOrderRequest wxMaExpressTestUpdateOrderRequest) throws WxErrorException;
+
+
+
 }

weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/WxMaImmediateDeliveryService.java

@@ -11,6 +11,10 @@ import cn.binarywang.wx.miniapp.bean.delivery.GetOrderRequest;
 import cn.binarywang.wx.miniapp.bean.delivery.GetOrderResponse;
 import cn.binarywang.wx.miniapp.bean.delivery.MockUpdateOrderRequest;
 import cn.binarywang.wx.miniapp.bean.delivery.MockUpdateOrderResponse;
+import cn.binarywang.wx.miniapp.bean.delivery.QueryWaybillTraceRequest;
+import cn.binarywang.wx.miniapp.bean.delivery.QueryWaybillTraceResponse;
+import cn.binarywang.wx.miniapp.bean.delivery.TraceWaybillRequest;
+import cn.binarywang.wx.miniapp.bean.delivery.TraceWaybillResponse;
 import me.chanjar.weixin.common.error.WxErrorException;
 
 /**
@@ -25,76 +29,104 @@ import me.chanjar.weixin.common.error.WxErrorException;
  */
 public interface WxMaImmediateDeliveryService {
 
-    /**
-     * 拉取已绑定账号.
-     * <pre>
-     * 文档地址：https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/immediate-delivery/by-business/immediateDelivery.getBindAccount.html
-     * </pre>
-     *
-     * @return 响应
-     * @throws WxErrorException 异常
-     */
-    BindAccountResponse getBindAccount() throws WxErrorException;
+  /**
+   * 拉取已绑定账号.
+   * <pre>
+   * 文档地址：https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/immediate-delivery/by-business/immediateDelivery.getBindAccount.html
+   * </pre>
+   *
+   * @return 响应
+   * @throws WxErrorException 异常
+   */
+  BindAccountResponse getBindAccount() throws WxErrorException;
 
-    /**
-     * 下配送单接口.
-     * <pre>
-     * 文档地址：https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/immediate-delivery/by-business/immediateDelivery.addOrder.html
-     * </pre>
-     *
-     * @param request request
-     * @return 响应
-     * @throws WxErrorException 异常
-     */
-    AddOrderResponse addOrder(AddOrderRequest request) throws WxErrorException;
+  /**
+   * 下配送单接口.
+   * <pre>
+   * 文档地址：https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/immediate-delivery/by-business/immediateDelivery.addOrder.html
+   * </pre>
+   *
+   * @param request request
+   * @return 响应
+   * @throws WxErrorException 异常
+   */
+  AddOrderResponse addOrder(AddOrderRequest request) throws WxErrorException;
 
-    /**
-     * 拉取配送单信息.
-     * <pre>
-     * 商家可使用本接口查询某一配送单的配送状态，便于商家掌握配送情况。
-     * 文档地址：https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/immediate-delivery/by-business/immediateDelivery.getOrder.html
-     * </pre>
-     *
-     * @param request request
-     * @return 响应
-     * @throws WxErrorException 异常
-     */
-    GetOrderResponse getOrder(GetOrderRequest request) throws WxErrorException;
+  /**
+   * 拉取配送单信息.
+   * <pre>
+   * 商家可使用本接口查询某一配送单的配送状态，便于商家掌握配送情况。
+   * 文档地址：https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/immediate-delivery/by-business/immediateDelivery.getOrder.html
+   * </pre>
+   *
+   * @param request request
+   * @return 响应
+   * @throws WxErrorException 异常
+   */
+  GetOrderResponse getOrder(GetOrderRequest request) throws WxErrorException;
 
-    /**
-     * 取消配送单接口.
-     * <pre>
-     * 文档地址：https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/immediate-delivery/by-business/immediateDelivery.cancelOrder.html
-     * </pre>
-     *
-     * @param request request
-     * @return 响应
-     * @throws WxErrorException 异常
-     */
-    CancelOrderResponse cancelOrder(CancelOrderRequest request) throws WxErrorException;
+  /**
+   * 取消配送单接口.
+   * <pre>
+   * 文档地址：https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/immediate-delivery/by-business/immediateDelivery.cancelOrder.html
+   * </pre>
+   *
+   * @param request request
+   * @return 响应
+   * @throws WxErrorException 异常
+   */
+  CancelOrderResponse cancelOrder(CancelOrderRequest request) throws WxErrorException;
 
-    /**
-     * 异常件退回商家商家确认收货接口.
-     * <pre>
-     * 文档地址：https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/immediate-delivery/by-business/immediateDelivery.abnormalConfirm.html
-     * </pre>
-     *
-     * @param request request
-     * @return 响应
-     * @throws WxErrorException 异常
-     */
-    AbnormalConfirmResponse abnormalConfirm(AbnormalConfirmRequest request) throws WxErrorException;
+  /**
+   * 异常件退回商家商家确认收货接口.
+   * <pre>
+   * 文档地址：https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/immediate-delivery/by-business/immediateDelivery.abnormalConfirm.html
+   * </pre>
+   *
+   * @param request request
+   * @return 响应
+   * @throws WxErrorException 异常
+   */
+  AbnormalConfirmResponse abnormalConfirm(AbnormalConfirmRequest request) throws WxErrorException;
+
+  /**
+   * 模拟配送公司更新配送单状态, 该接口只用于沙盒环境，即订单并没有真实流转到运力方.
+   * <pre>
+   * 文档地址：https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/immediate-delivery/by-business/immediateDelivery.mockUpdateOrder.html
+   * </pre>
+   *
+   * @param request request
+   * @return 响应
+   * @throws WxErrorException 异常
+   */
+  MockUpdateOrderResponse mockUpdateOrder(MockUpdateOrderRequest request) throws WxErrorException;
+
+
+  /**
+   * 商户使用此接口向微信提供某交易单号对应的运单号。微信后台会跟踪运单的状态变化
+   * <pre>
+   * 文档地址：https://developers.weixin.qq.com/miniprogram/dev/platform-capabilities/industry/express/express_search.html
+   * </pre>
+   *
+   * @param request request
+   * @return 响应
+   * @throws WxErrorException 异常
+   */
+  TraceWaybillResponse traceWaybill(TraceWaybillRequest request) throws WxErrorException;
+
+
+  /**
+   * 商户在调用完trace_waybill接口后，可以使用本接口查询到对应运单的详情信息
+   * <pre>
+   * 文档地址：https://developers.weixin.qq.com/miniprogram/dev/platform-capabilities/industry/express/express_search.html
+   * </pre>
+   *
+   * @param request request
+   * @return 响应
+   * @throws WxErrorException 异常
+   */
+  QueryWaybillTraceResponse queryWaybillTrace(QueryWaybillTraceRequest request)
+    throws WxErrorException;
 
-    /**
-     * 模拟配送公司更新配送单状态, 该接口只用于沙盒环境，即订单并没有真实流转到运力方.
-     * <pre>
-     * 文档地址：https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/immediate-delivery/by-business/immediateDelivery.mockUpdateOrder.html
-     * </pre>
-     *
-     * @param request request
-     * @return 响应
-     * @throws WxErrorException 异常
-     */
-    MockUpdateOrderResponse mockUpdateOrder(MockUpdateOrderRequest request) throws WxErrorException;
 
 }

weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/impl/WxMaImmediateDeliveryServiceImpl.java

@@ -13,8 +13,14 @@ import cn.binarywang.wx.miniapp.bean.delivery.GetOrderRequest;
 import cn.binarywang.wx.miniapp.bean.delivery.GetOrderResponse;
 import cn.binarywang.wx.miniapp.bean.delivery.MockUpdateOrderRequest;
 import cn.binarywang.wx.miniapp.bean.delivery.MockUpdateOrderResponse;
+import cn.binarywang.wx.miniapp.bean.delivery.QueryWaybillTraceRequest;
+import cn.binarywang.wx.miniapp.bean.delivery.QueryWaybillTraceResponse;
+import cn.binarywang.wx.miniapp.bean.delivery.TraceWaybillRequest;
+import cn.binarywang.wx.miniapp.bean.delivery.TraceWaybillResponse;
 import cn.binarywang.wx.miniapp.bean.delivery.base.WxMaDeliveryBaseResponse;
 import cn.binarywang.wx.miniapp.constant.WxMaApiUrlConstants;
+import cn.binarywang.wx.miniapp.constant.WxMaApiUrlConstants.InstantDelivery;
+import cn.binarywang.wx.miniapp.constant.WxMaConstants;
 import com.google.gson.JsonElement;
 import com.google.gson.JsonObject;
 import javassist.bytecode.ConstPool;
@@ -157,6 +163,29 @@ public class WxMaImmediateDeliveryServiceImpl implements WxMaImmediateDeliverySe
       MockUpdateOrderResponse.class);
   }
 
+  @Override
+  public TraceWaybillResponse traceWaybill(
+    TraceWaybillRequest request) throws WxErrorException {
+    String responseContent = this.wxMaService.post(InstantDelivery.TRACE_WAYBILL_URL, request);
+    TraceWaybillResponse response = TraceWaybillResponse.fromJson(responseContent);
+    if (response.getErrcode() == -1) {
+      throw new WxErrorException(WxError.fromJson(responseContent, WxType.MiniApp));
+    }
+    return response;
+
+  }
+
+  @Override
+  public QueryWaybillTraceResponse queryWaybillTrace(
+    QueryWaybillTraceRequest request) throws WxErrorException {
+    String responseContent = this.wxMaService.post(InstantDelivery.QUERY_WAYBILL_TRACE_URL, request);
+    QueryWaybillTraceResponse response = QueryWaybillTraceResponse.fromJson(responseContent);
+    if (response.getErrcode() == -1) {
+      throw new WxErrorException(WxError.fromJson(responseContent, WxType.MiniApp));
+    }
+    return response;
+  }
+
   /**
    * 解析响应.
    *

weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/bean/delivery/QueryWaybillTraceRequest.java

@@ -0,0 +1,46 @@
+package cn.binarywang.wx.miniapp.bean.delivery;
+
+
+import cn.binarywang.wx.miniapp.json.WxMaGsonBuilder;
+import com.google.gson.annotations.SerializedName;
+import java.io.Serializable;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+import lombok.experimental.Accessors;
+
+/**
+ * <pre>
+ * 查询运单接口 query_trace
+ *
+ * 商户在调用完trace_waybill接口后，可以使用本接口查询到对应运单的详情信息
+ * </pre>
+ *
+ * @author boris
+ * @since 2022-04-01
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+@Accessors(chain = true)
+public class QueryWaybillTraceRequest implements Serializable {
+
+  private static final long serialVersionUID = -7538739003766268386L;
+
+
+  /**
+   * 查询id
+   * <pre>
+   * 是否必填： 是
+   * 描述： 可以从 传运单接口 trace_waybill 取数据
+   * </pre>
+   */
+  @SerializedName("waybill_token")
+  private String waybillToken;
+
+  public String toJson() {
+    return WxMaGsonBuilder.create().toJson(this);
+  }
+}

weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/bean/delivery/QueryWaybillTraceResponse.java

@@ -0,0 +1,123 @@
+package cn.binarywang.wx.miniapp.bean.delivery;
+
+import cn.binarywang.wx.miniapp.bean.WxMaBaseResponse;
+import cn.binarywang.wx.miniapp.json.WxMaGsonBuilder;
+import com.google.gson.annotations.SerializedName;
+import java.io.Serializable;
+import lombok.Data;
+import lombok.experimental.Accessors;
+
+/**
+ * <pre>
+ * 查询运单接口 query_trace 响应参数
+ *
+ * 商户在调用完trace_waybill接口后，可以使用本接口查询到对应运单的详情信息
+ * </pre>
+ *
+ * @author boris
+ * @since 2022-04-01
+ */
+@Data
+@Accessors(chain = true)
+public class QueryWaybillTraceResponse extends WxMaBaseResponse implements Serializable {
+
+  private static final long serialVersionUID = 3773007367000633663L;
+
+  /**
+   * 运单信息.
+   */
+  @SerializedName("waybill_info")
+  private WaybillInfo waybillInfo;
+
+  /**
+   * 商品信息
+   */
+  @SerializedName("shop_info")
+  private ShopInfo shopInfo;
+
+  /**
+   * 运力信息.
+   */
+  @SerializedName("delivery_info")
+  private DeliveryInfo deliveryInfo;
+
+
+  public static QueryWaybillTraceResponse fromJson(String json) {
+    return WxMaGsonBuilder.create().fromJson(json, QueryWaybillTraceResponse.class);
+  }
+
+  /**
+   * 运单信息.
+   */
+  @Data
+  @Accessors(chain = true)
+  public static class WaybillInfo implements Serializable {
+
+    private static final long serialVersionUID = -3759074878713856529L;
+
+    /**
+     * 运单状态	释义
+     * <pre>
+     *
+     * 0	运单不存在或者未揽收
+     * 1	已揽件
+     * 2	运输中
+     * 3	派件中
+     * 4	已签收
+     * 5	异常
+     * 6	代签收
+     *
+     * </pre>
+     */
+    @SerializedName("status")
+    private Integer status;
+
+    /**
+     * 查询id.
+     */
+    @SerializedName("waybill_token")
+    private String waybillToken;
+  }
+
+  /**
+   * 商品信息.
+   */
+  @Data
+  @Accessors(chain = true)
+  public static class ShopInfo implements Serializable {
+
+    private static final long serialVersionUID = -3759074878713856529L;
+
+    /**
+     * 配送公司Id.
+     */
+    @SerializedName("goods_info")
+    private WaybillGoodsInfo goodsInfo;
+
+
+  }
+
+
+  /**
+   * 运力信息.
+   */
+  @Data
+  @Accessors(chain = true)
+  public static class DeliveryInfo implements Serializable {
+
+    private static final long serialVersionUID = -3759074878713856529L;
+
+    /**
+     * 配送公司Id.
+     */
+    @SerializedName("delivery_id")
+    private String deliveryId;
+
+    /**
+     * 运力公司名称.
+     */
+    @SerializedName("delivery_name")
+    private String deliveryName;
+
+  }
+}

weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/bean/delivery/TraceWaybillRequest.java

@@ -0,0 +1,101 @@
+package cn.binarywang.wx.miniapp.bean.delivery;
+
+
+import cn.binarywang.wx.miniapp.json.WxMaGsonBuilder;
+import com.google.gson.annotations.SerializedName;
+import java.io.Serializable;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+import lombok.experimental.Accessors;
+
+/**
+ * <pre>
+ * 传运单接口 trace_waybill
+ * </pre>
+ *
+ * @author boris
+ * @since 2022-04-01
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+@Accessors(chain = true)
+public class TraceWaybillRequest implements Serializable {
+
+  private static final long serialVersionUID = -7538739003766268386L;
+
+
+  /**
+   * 用户openid
+   * <pre>
+   * 是否必填： 是
+   * 描述： 用户openid
+   * </pre>
+   */
+  @SerializedName("openid")
+  private String openid;
+
+  /**
+   * 寄件人手机号
+   * <pre>
+   * 是否必填： 否
+   * 描述：
+   * </pre>
+   */
+  @SerializedName("sender_phone")
+  private String senderPhone;
+
+  /**
+   * 收件人手机号
+   * <pre>
+   * 是否必填： 否
+   * 描述：部分运力需要用户手机号作为查单依据
+   * </pre>
+   */
+  @SerializedName("receiver_phone")
+  private String receiverPhone;
+
+  /**
+   * 运单ID
+   * <pre>
+   * 是否必填： 是
+   * </pre>
+   */
+  @SerializedName("waybill_id")
+  private String waybillId;
+
+  /**
+   * 交易单号（微信支付生成的交易单号，一般以420开头）
+   * <pre>
+   * 是否必填： 是
+   * </pre>
+   */
+  @SerializedName("trans_id")
+  private String transId;
+
+
+  /**
+   * 点击落地页商品卡片跳转路径（建议为订单详情页path），不传默认跳转小程序首页。
+   * <pre>
+   * 是否必填： 否
+   * </pre>
+   */
+  @SerializedName("order_detail_path")
+  private String orderDetailPath;
+
+  /**
+   * 商品信息
+   * <pre>
+   * 是否必填： 是
+   * </pre>
+   */
+  @SerializedName("goods_info")
+  private WaybillGoodsInfo goodsInfo;
+
+  public String toJson() {
+    return WxMaGsonBuilder.create().toJson(this);
+  }
+}

weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/bean/delivery/TraceWaybillResponse.java

@@ -0,0 +1,34 @@
+package cn.binarywang.wx.miniapp.bean.delivery;
+
+import cn.binarywang.wx.miniapp.bean.WxMaBaseResponse;
+import cn.binarywang.wx.miniapp.json.WxMaGsonBuilder;
+import com.google.gson.annotations.SerializedName;
+import java.io.Serializable;
+import lombok.Data;
+import lombok.experimental.Accessors;
+
+/**
+ * <pre>
+ * 传运单接口 trace_waybill 响应参数
+ * </pre>
+ *
+ * @author boris
+ * @since 2022-04-01
+ */
+@Data
+@Accessors(chain = true)
+public class TraceWaybillResponse extends WxMaBaseResponse implements Serializable {
+
+  private static final long serialVersionUID = 3773007367000633663L;
+
+  /**
+   * 查询id.
+   */
+  @SerializedName("waybill_token")
+  private String waybillToken;
+
+
+  public static TraceWaybillResponse fromJson(String json) {
+    return WxMaGsonBuilder.create().fromJson(json, TraceWaybillResponse.class);
+  }
+}

weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/bean/delivery/WaybillGoodsInfo.java

@@ -0,0 +1,59 @@
+package cn.binarywang.wx.miniapp.bean.delivery;
+
+import cn.binarywang.wx.miniapp.json.WxMaGsonBuilder;
+import com.google.gson.annotations.SerializedName;
+import java.io.Serializable;
+import java.util.List;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * 运单商品信息
+ *
+ * @author boris
+ * @since 2022-04-01
+ */
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class WaybillGoodsInfo implements Serializable {
+
+  private static final long serialVersionUID = 5643624677715536605L;
+
+
+
+  /**
+   * 商品信息
+   */
+  @SerializedName("detail_list")
+  private List<GoodsItem> goodsItemList;
+
+  public static WaybillGoodsInfo fromJson(String json) {
+    return WxMaGsonBuilder.create().fromJson(json, WaybillGoodsInfo.class);
+  }
+
+  @Data
+  public static class GoodsItem {
+
+    /**
+     * 商品名称
+     * <pre>
+     * 是否必填： 是
+     * </pre>
+     */
+    @SerializedName("goods_name")
+    private Long goodsName;
+
+    /**
+     * 商品图片URL
+     * <pre>
+     * 是否必填： 是
+     * </pre>
+     */
+    @SerializedName("goods_img_url")
+    private Integer goodsImgUrl;
+
+
+  }
+}

weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/constant/WxMaApiUrlConstants.java

@@ -529,6 +529,20 @@ public class WxMaApiUrlConstants {
      */
     String MOCK_UPDATE_ORDER = "https://api.weixin.qq.com/cgi-bin/express/local/business/test_update_order";
 
+    /**
+     * 物流服务-查询组件-跟踪物流面单
+     * 商户使用此接口向微信提供某交易单号对应的运单号。微信后台会跟踪运单的状态变化
+     */
+    String TRACE_WAYBILL_URL = "https://api.weixin.qq.com/cgi-bin/express/delivery/open_msg/trace_waybill";
+
+
+    /**
+     * 物流服务-查询组件-查询运单接口 query_trace
+     * 商户在调用完trace_waybill接口后，可以使用本接口查询到对应运单的详情信息
+     */
+    String QUERY_WAYBILL_TRACE_URL = "https://api.weixin.qq.com/cgi-bin/express/delivery/open_msg/query_trace";
+
+
     /**
      * 下单接口.
      */