MarketingBusiFavorApi (wepay-sdk 1.3.3 API)

```
public interface MarketingBusiFavorApi
```
微信支付商家券

Since:

2024/8/22

Author:

dax

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`AssociateTime`	`associate(FavorAssociateInfo associateInfo)` 商家券关联订单信息API
`FavorBudgetResponse`	`budget(String stockId, FavorBudgetParams params)` 修改批次预算API
`StockResponse`	`createStock(FavorCreateParams params)` 创建商家券券批次API
`GenericPayResponse<OffsetDateTime>`	`deactivate(FavorDeactivateParams params)` 使券失效API
`AssociateTime`	`disassociate(FavorAssociateInfo associateInfo)` 商家券取消关联订单信息API
`FavorCallbackSetting`	`getCallbacks()` 查询调用方商家券事件通知地址API
`FavorCallbackSetting`	`getCallbacks(String mchId)` 获取商家券事件通知地址API
`FavorSubsidyListResponse`	`payMakeup(FavorSubsidyParams params)` 营销补差付款API
`FavorSubsidyResponse`	`queryMakeup(String subsidyReceiptId)` 查询营销补差付款单详情API
`StockDetailResponse`	`queryStockDetail(String stockId)` 查询商家券批次详情API
`UserCouponResponse`	`queryUserCoupon(String openid, String couponCode, String appid)` 查询用户券详情API
`UserCouponsDetailResponse`	`queryUserStocks(String openid, UserFavorQueryParams params)` 根据过滤条件查询用户券API
`GenericPayResponse<OffsetDateTime>`	`refund(FavorRefundParams params)` 申请退券API
`FavorReturnSubsidyResponse`	`returnReceipts(FavorSubsidyReturnParams params)` 营销补差回退API
`FavorCallbackSetting`	`setCallbacks(FavorCallbackSetting setting)` 设置商家券事件通知地址API
`cn.felord.retrofit.VoidResponse`	`updateStock(String stockId, FavorUpdateParams params)` 修改商家券基本信息API
`CodeUploadResponse`	`uploadCouponCodes(CouponCodeUploadParams params)` 上传预存code API
`FavorUseResponse`	`use(FavorUseParams params)` 核销用户券API

Method Detail

createStock

@POST(value="v3/marketing/busifavor/stocks")
StockResponse createStock(@Body
                                                                       FavorCreateParams params)
                                                                throws PayException

创建商家券券批次API

商家券介绍详见微信支付商家券

Parameters:: params - the params
Returns:: the wechat response entity
Throws:: PayException - the pay exception

queryStockDetail

@GET(value="v3/marketing/busifavor/stocks/{stock_id}")
StockDetailResponse queryStockDetail(@Path(value="stock_id")
                                                                                            String stockId)
                                                                                     throws PayException

查询商家券批次详情API

商户可通过该接口查询已创建的商家券批次详情信息。

Parameters:: stockId - the stock id
Returns:: the wechat response entity
Throws:: PayException - the pay exception

use

@POST(value="v3/marketing/busifavor/coupons/use")
FavorUseResponse use(@Body
                                                                       FavorUseParams params)
                                                                throws PayException

核销用户券API

在用户满足优惠门槛后，服务商可通过该接口核销用户微信卡包中具体某一张商家券。

Parameters:: params - the params
Returns:: the wechat response entity
Throws:: PayException - the pay exception

queryUserStocks

@GET(value="v3/marketing/busifavor/users/{openid}/coupons")
UserCouponsDetailResponse queryUserStocks(@Path(value="openid")
                                                                                                      String openid,
                                                                                                      @QueryMap
                                                                                                      UserFavorQueryParams params)
                                                                                               throws PayException

根据过滤条件查询用户券API

商户自定义筛选条件（如创建商户号、归属商户号、发放商户号等），查询指定微信用户卡包中满足对应条件的所有商家券信息。

Parameters:: openid - the openid; params - the params
Returns:: the user coupon detail response
Throws:: PayException - the pay exception

queryUserCoupon

@GET(value="v3/marketing/busifavor/users/{openid}/coupons/{coupon_code}/appids/{appid}")
UserCouponResponse queryUserCoupon(@Path(value="openid")
                                                                                                                            String openid,
                                                                                                                            @Path(value="coupon_code")
                                                                                                                            String couponCode,
                                                                                                                            @Path(value="appid")
                                                                                                                            String appid)
                                                                                                                     throws PayException

查询用户券详情API

服务商可通过该接口查询微信用户卡包中某一张商家券的详情信息。

Parameters:: openid - the openid; couponCode - the coupon code; appid - the appid
Returns:: the wechat response entity
Throws:: PayException - the pay exception

uploadCouponCodes

@POST(value="v3/marketing/busifavor/stocks/{stock_id}/couponcodes")
CodeUploadResponse uploadCouponCodes(@Body
                                                                                                         CouponCodeUploadParams params)
                                                                                                  throws PayException

上传预存code API

商家券的Code码可由微信后台随机分配，同时支持商户自定义。如商家已有自己的优惠券系统，可直接使用自定义模式。即商家预先向微信支付上传券Code，当券在发放时，微信支付自动从已导入的Code中随机取值（不能指定），派发给用户。

Parameters:: params - the params
Returns:: wechat response entity
Throws:: PayException - the pay exception

setCallbacks
```
@POST(value="v3/marketing/busifavor/callbacks")
FavorCallbackSetting setCallbacks(@Body
                                                                                  FavorCallbackSetting setting)
                                                                           throws PayException
```
设置商家券事件通知地址API
用于设置接收商家券相关事件通知的URL，可接收商家券相关的事件通知、包括发放通知等。需要设置接收通知的URL，并在商户平台开通营销事件推送的能力，即可接收到相关通知。
营销事件推送：点击开通产品权限。由商家券批次创建方登录Pay平台，操作开通
注意：
- 仅可以收到由商户自己创建的批次相关的通知
- 需要设置apiv3秘钥，否则无法收到回调。
- 如果需要领券回调中的参数openid。需要创券时候传入 notify_appid参数。
Parameters:

setting - the setting

Returns:

callbacks callbacks

Throws:

PayException - the pay exception

getCallbacks

@GET(value="v3/marketing/busifavor/callbacks")
FavorCallbackSetting getCallbacks(@Query(value="mchid")
                                                                                 String mchId)
                                                                          throws PayException

获取商家券事件通知地址API

通过调用此接口可查询设置的通知URL。

注意：

仅可以查询由请求商户号设置的商家券通知url

Parameters:: mchId - the mch id
Returns:: callbacks callbacks
Throws:: PayException - the pay exception

getCallbacks

@GET(value="v3/marketing/busifavor/callbacks")
FavorCallbackSetting getCallbacks()
                                                                          throws PayException

查询调用方商家券事件通知地址API

Returns:: the callbacks
Throws:: PayException - the pay exception

associate

@POST(value="v3/marketing/busifavor/coupons/associate")
AssociateTime associate(@Body
                                                                                FavorAssociateInfo associateInfo)
                                                                         throws PayException

商家券关联订单信息API

将有效态（未核销）的商家券与订单信息关联，用于后续参与摇奖以及返佣激励等操作的统计。

注意：仅对有关联订单需求的券进行该操作

Parameters:: associateInfo - the associate info
Returns:: the associate time
Throws:: PayException - the pay exception

disassociate

@POST(value="v3/marketing/busifavor/coupons/disassociate")
AssociateTime disassociate(@Body
                                                                                      FavorAssociateInfo associateInfo)
                                                                               throws PayException

商家券取消关联订单信息API

取消商家券与订单信息的关联关系。

注意：建议取消前调用查询接口，查到当前关联的商户单号并确认后，再进行取消操作

Parameters:: associateInfo - the associate info
Returns:: the associate time
Throws:: PayException - the pay exception

budget

@PATCH(value="v3/marketing/busifavor/stocks/{stock_id}/budget")
FavorBudgetResponse budget(@Path(value="stock_id")
                                                                                           String stockId,
                                                                                           @Body
                                                                                           FavorBudgetParams params)
                                                                                    throws PayException

修改批次预算API

商户可以通过该接口修改批次单天发放上限数量或者批次最大发放数量

Parameters:: stockId - the stock id; params - the params
Returns:: wechat response entity
Throws:: PayException - the pay exception

updateStock

@PATCH(value="v3/marketing/busifavor/stocks/{stock_id}")
cn.felord.retrofit.VoidResponse updateStock(@Path(value="stock_id")
                                                                                                     String stockId,
                                                                                                     @Body
                                                                                                     FavorUpdateParams params)
                                                                                              throws PayException

修改商家券基本信息API

商户可以通过该接口修改商家券基本信息，已创建商家券批次，且修改时间位于有效期结束时间前

Parameters:: stockId - the stock id; params - the params
Returns:: wechat response entity
Throws:: PayException - the pay exception

refund

@POST(value="v3/marketing/busifavor/coupons/return")
GenericPayResponse<OffsetDateTime> refund(@Body
                                                                                               FavorRefundParams params)
                                                                                        throws PayException

申请退券API

商户可以通过该接口为已核销的券申请退券

Parameters:: params - the params
Returns:: wechat response entity
Throws:: PayException - the pay exception

deactivate

@POST(value="v3/marketing/busifavor/coupons/deactivate")
GenericPayResponse<OffsetDateTime> deactivate(@Body
                                                                                                       FavorDeactivateParams params)
                                                                                                throws PayException

使券失效API

前置条件：券的状态为CouponState.SENDED

商户可以通过该接口将可用券进行失效处理，券被失效后无法再被核销

Parameters:: params - the params
Returns:: wechat response entity
Throws:: PayException - the pay exception

returnReceipts

@POST(value="v3/marketing/busifavor/subsidy/return-receipts")
FavorReturnSubsidyResponse returnReceipts(@Body
                                                                                                        FavorSubsidyReturnParams params)
                                                                                                 throws PayException

营销补差回退API

商户通过该接口可回退补差款

Parameters:: params - the params
Returns:: wechat response entity
Throws:: PayException - the pay exception

payMakeup

@POST(value="v3/marketing/busifavor/subsidy/pay-receipts")
FavorSubsidyListResponse payMakeup(@Body
                                                                                              FavorSubsidyParams params)
                                                                                       throws PayException

营销补差付款API

该API主要用于商户营销补贴场景，支持基于单张券进行不同商户账户间的资金补差，从而提升财务结算、资金利用效率。具体可参考操作文档

Parameters:: params - the params
Returns:: the wechat response entity
Throws:: PayException - the pay exception
Since:: 1.0.13.RELEASE

queryMakeup

@GET(value="v3/marketing/busifavor/subsidy/pay-receipts/{subsidy_receipt_id}")
FavorSubsidyResponse queryMakeup(@Path(value="subsidy_receipt_id")
                                                                                                                String subsidyReceiptId)
                                                                                                         throws PayException

查询营销补差付款单详情API

查询商家券营销补差付款单详情

Parameters:: subsidyReceiptId - the subsidyReceiptId
Returns:: the wechat response entity
Throws:: PayException - the pay exception
Since:: 1.0.13.RELEASE

Interface MarketingBusiFavorApi

Method Summary

Method Detail

createStock

queryStockDetail

use

queryUserStocks

queryUserCoupon

uploadCouponCodes

setCallbacks

getCallbacks

getCallbacks

associate

disassociate

budget

updateStock

refund

deactivate

returnReceipts

payMakeup

queryMakeup