feat: 代金券增加发放消费卡接口

代金券功能增加发放消费卡接口支持

payment-spring-boot-autoconfigure/src/main/java/cn/felord/payment/wechat/enumeration/WechatPayV3Type.java

@@ -342,6 +342,12 @@ public enum WechatPayV3Type {
      * @since 1.0.0.RELEASE
      */
     MARKETING_FAVOR_CALLBACKS(HttpMethod.POST, "%s/v3/marketing/favor/callbacks"),
+    /**
+     * 发放代金券消费卡API.
+     *
+     * @since 1.0.4.RELEASES
+     */
+    MARKETING_FAVOR_COUPONS_SEND(HttpMethod.POST, "%s/v3/marketing/busifavor/coupons/{card_id}/send"),
     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
     /**

payment-spring-boot-autoconfigure/src/main/java/cn/felord/payment/wechat/v3/WechatMarketingFavorApi.java

@@ -92,7 +92,7 @@ public class WechatMarketingFavorApi extends AbstractApi {
         URI uri = UriComponentsBuilder.fromHttpUrl(type.uri(WeChatServer.CHINA))
                 .build()
                 .toUri();
-        if (!StringUtils.hasText(params.getBelongMerchant())){
+        if (!StringUtils.hasText(params.getBelongMerchant())) {
             WechatPayProperties.V3 v3 = this.wechatMetaBean().getV3();
             String mchId = v3.getMchId();
             params.setBelongMerchant(mchId);
@@ -491,7 +491,7 @@ public class WechatMarketingFavorApi extends AbstractApi {
      *
      * @param stockId the stock id
      * @return the wechat response entity
-     * @see AbstractApi#billDownload(String) 对账单下载api
+     * @see AbstractApi#billDownload(String) AbstractApi#billDownload(String)对账单下载api
      */
     public WechatResponseEntity<ObjectNode> downloadStockUseFlow(String stockId) {
         WechatResponseEntity<ObjectNode> wechatResponseEntity = new WechatResponseEntity<>();
@@ -513,7 +513,7 @@ public class WechatMarketingFavorApi extends AbstractApi {
      *
      * @param stockId the stock id
      * @return the wechat response entity
-     * @see AbstractApi#billDownload(String) 对账单下载api
+     * @see AbstractApi#billDownload(String) AbstractApi#billDownload(String)对账单下载api
      */
     public WechatResponseEntity<ObjectNode> downloadStockRefundFlow(String stockId) {
         WechatResponseEntity<ObjectNode> wechatResponseEntity = new WechatResponseEntity<>();
@@ -602,7 +602,7 @@ public class WechatMarketingFavorApi extends AbstractApi {
      *
      * @param notifyUrl the notify url
      * @return the wechat response entity
-     * @see WechatPayCallback#couponCallback(ResponseSignVerifyParams, Consumer) 核销回调
+     * @see WechatPayCallback#couponCallback(ResponseSignVerifyParams, Consumer) WechatPayCallback#couponCallback(ResponseSignVerifyParams, Consumer)核销回调
      */
     public WechatResponseEntity<ObjectNode> setMarketingFavorCallback(String notifyUrl) {
         WechatResponseEntity<ObjectNode> wechatResponseEntity = new WechatResponseEntity<>();
@@ -632,6 +632,40 @@ public class WechatMarketingFavorApi extends AbstractApi {
                 .toUri();
         return Post(uri, body);
     }
+
+    /**
+     * 发放消费卡API
+     * <p>
+     * 商户通过调用本接口向用户发放消费卡，用户领到卡的同时会领取到一批代金券，消费卡会自动放入卡包中。
+     * <p>
+     * 注意：
+     * <ul>
+     *     <li>调用该接口前，需要在微信支付商户平台创建“消费卡”，获得card_id。</li>
+     *     <li>此功能仅向指定邀约商户开放，如有需要请联系微信支付运营经理。</li>
+     * </ul>
+     *
+     * @param params the params
+     * @return wechat response entity
+     */
+    public WechatResponseEntity<ObjectNode> sendCouponsCard(CouponsCardSendParams params) {
+        WechatResponseEntity<ObjectNode> wechatResponseEntity = new WechatResponseEntity<>();
+        this.client().withType(WechatPayV3Type.MARKETING_FAVOR_COUPONS_SEND, params)
+                .function((type, sendParams) -> {
+                    URI uri = UriComponentsBuilder.fromHttpUrl(type.uri(WeChatServer.CHINA))
+                            .build()
+                            .expand(sendParams.getCardId())
+                            .toUri();
+                    sendParams.setCardId(null);
+                    if (!StringUtils.hasText(sendParams.getAppid())) {
+                        WechatPayProperties.V3 v3 = this.wechatMetaBean().getV3();
+                        sendParams.setAppid(v3.getAppId());
+                    }
+                    return Post(uri, sendParams);
+                })
+                .consumer(wechatResponseEntity::convert)
+                .request();
+        return wechatResponseEntity;
+    }
 }
 
 

payment-spring-boot-autoconfigure/src/main/java/cn/felord/payment/wechat/v3/model/CouponsCardSendParams.java

@@ -0,0 +1,58 @@
+/*
+ *  Copyright 2019-2021 felord.cn
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *       https://www.apache.org/licenses/LICENSE-2.0
+ *  Website:
+ *       https://felord.cn
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package cn.felord.payment.wechat.v3.model;
+
+import com.fasterxml.jackson.annotation.JsonFormat;
+import lombok.Data;
+
+import java.time.OffsetDateTime;
+
+/**
+ * 发放代金券消费卡API请求参数
+ *
+ * @author felord.cn
+ * @since 1.0.4.RELEASE
+ */
+@Data
+public class CouponsCardSendParams {
+
+    /**
+     * 消费卡ID
+     * <p>
+     * 获取方法请参见<a target= "_blank" href= "https://pay.weixin.qq.com/wiki/doc/apiv3/wxpay/marketing/coupons/chapter2_2.shtml">《接入流程》</a>中的创建消费卡。
+     */
+    private String cardId;
+    /**
+     * 消费卡归属appid
+     */
+    private String appid;
+    /**
+     * 需为消费卡归属appid生成的openid。
+     */
+    private String openid;
+    /**
+     * 商户此次发放凭据号。
+     * <p>
+     * 推荐使用大小写字母和数字，不同添加请求发放凭据号不同，商户侧需保证同一发券请求的out_request_no和send_time的唯一性。
+     */
+    private String outRequestNo;
+    /**
+     * 请求发卡时间,由于系统限制，暂不支持传入早于当前时间24小时以上的时间进行发券请求。
+     */
+    @JsonFormat(pattern = "yyyy-MM-dd'T'HH:mm:ss.SSSXXX", timezone = "GMT+8")
+    private OffsetDateTime sendTime;
+}