CardApi (wemp-sdk 1.2.0 API)

```
public interface CardApi
```
微信卡券

Since:

2023 /8/18 11:41

Author:

dax

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`MpResponse`	`activateMemberCard(MemberCardActivateRequest request)` Activate member card mp response.
`PayGiftRulesResponse`	`addPayGiftCard(PayGiftRulesRequest request)` 设置支付后投放卡券接口
`BatchCardResponse`	`batchGetCard(BatchCardRequest request)` 批量查询卡券列表
`UserCardResponse`	`consumeUserCard(UserCardInfo request)` 核销Code接口，用于线下核销
`GenericMpResponse<String>`	`createCard(CardRequest<AbstractCard> request)` 创建卡券
`CardQrcodeResponse`	`createQrcode(CardQrcodeRequest request)` 创建二维码接口
`GenericMpResponse<String>`	`decryptCode(DecryptCodeRequest request)` Code解码接口
`MpResponse`	`deleteCard(CardId request)` 删除卡券接口
`MpResponse`	`deletePayGiftCard(PayGiftRuleId request)` 删除支付后投放卡券规则接口
`GenericMpResponse<AbstractCard>`	`getCard(CardId request)` 查看卡券详情
`CardDataList<CardBiz>`	`getCardBizuinInfo(CardBizRequest request)` 拉取卡券概况数据接口
`CardDataList<FreeCardBiz>`	`getCardCardInfo(CardInfoRequest request)` 获取免费券数据接口
`CardDataList<MemberCardBiz>`	`getCardMemberCardInfo(CardBizRequest request)` 拉取会员卡概况数据接口
`CardDataList<MemberCardDetail>`	`getCardMemberCardInfo(MemberCardDetailRequest request)` 拉取单张会员卡数据接口
`UserCardResponse`	`getUserCard(UserCardRequest request)` 查询Code接口，用于线下核销
`CardListResponse`	`getUserCardList(OpenUserCard request)` 获取用户已领取卡券接口
`CardUserInfoResponse`	`getUserinfo(UserCardInfo request)` 步骤五：拉取会员信息接口
`CardLandingResponse`	`landingpage(CardLandingRequest request)` 创建货架接口
`MpResponse`	`modifyStock(ModifyStockRequest request)` 修改库存接口
`MpResponse`	`setActivateForm(MemberCardActivateForm request)` 设置开卡字段接口
`MpResponse`	`setPayCell(CardPaySettingRequest request)` 设置微信买单接口
`MpResponse`	`setSelfConsumeCell(CardPaySettingRequest request)` 设置自助核销接口
`MpResponse`	`setTestWhitelist(TestWhiteListRequest request)` 设置测试白名单
`MpResponse`	`unavailableCardCode(AbandonCardCodeRequest request)` 设置卡券失效接口
`GenericMpResponse<Boolean>`	`updateCard(UpdateCardRequest request)` 更改卡券信息接口
`MpResponse`	`updateCode(UpdateCodeRequest request)` 更改Code接口
`CardUpdateUserResponse`	`updateUser(CardUpdateUserRequest request)` 更新会员信息

Method Detail

createCard
```
@POST(value="card/create")
GenericMpResponse<String> createCard(@Body
                                                                CardRequest<AbstractCard> request)
                                                         throws WeMpException
```
创建卡券
创建卡券接口是微信卡券的基础接口，用于创建一类新的卡券，获取card_id，创建成功并通过审核后，商家可以通过文档提供的其他接口将卡券下发给用户，每次成功领取，库存数量相应扣除。

Parameters:

request - the request

Returns:

the generic mp response

Throws:

WeMpException - the we mp exception

See Also:

MemberCard

createQrcode

@POST(value="card/qrcode/create")
CardQrcodeResponse createQrcode(@Body
                                                                  CardQrcodeRequest request)
                                                           throws WeMpException

创建二维码接口

开发者可调用该接口生成一张卡券二维码供用户扫码后添加卡券到卡包。

Parameters:: request - the request
Returns:: the response body
Throws:: WeMpException - the we mp exception

setPayCell
```
@POST(value="card/paycell/set")
MpResponse setPayCell(@Body
                                                      CardPaySettingRequest request)
                                               throws WeMpException
```
设置微信买单接口
创建卡券之后，开发者可以通过该接口设置该card_id支持微信买单功能。值得开发者注意的是，设置买单的card_id必须已经配置了门店，否则会报错。

Parameters:

request - the request

Returns:

the pay cell

Throws:

WeMpException - the we mp exception

setSelfConsumeCell
```
@POST(value="card/selfconsumecell/set")
MpResponse setSelfConsumeCell(@Body
                                                                      CardPaySettingRequest request)
                                                               throws WeMpException
```
设置自助核销接口
创建卡券之后，开发者可以通过设置微信买单接口设置该card_id支持自助核销功能。值得开发者注意的是，设置自助核销的card_id必须已经配置了门店，否则会报错。

Parameters:

request - the request

Returns:

the self consume cell

Throws:

WeMpException - the we mp exception

setTestWhitelist

@POST(value="card/testwhitelist/set")
MpResponse setTestWhitelist(@Body
                                                                  TestWhiteListRequest request)
                                                           throws WeMpException

设置测试白名单

由于卡券有审核要求，为方便公众号调试，可以设置一些测试账号，这些账号可领取未通过审核的卡券，体验整个流程。

Parameters:: request - the request
Returns:: the test whitelist
Throws:: WeMpException - the we mp exception

landingpage

@POST(value="card/landingpage/create")
CardLandingResponse landingpage(@Body
                                                                       CardLandingRequest request)
                                                                throws WeMpException

创建货架接口

开发者需调用该接口创建货架链接，用于卡券投放。创建货架时需填写投放路径的场景字段。

Parameters:: request - the request
Returns:: the card landing response
Throws:: WeMpException - the we mp exception

getUserCard
```
@POST(value="card/code/get")
UserCardResponse getUserCard(@Body
                                                          UserCardRequest request)
                                                   throws WeMpException
```
查询Code接口，用于线下核销
我们强烈建议开发者在调用核销code接口之前调用查询code接口，并在核销之前对非法状态的code(如转赠中、已删除、已核销等)做出处理。
注意事项：
1. 固定时长有效期会根据用户实际领取时间转换，如用户2013年10月1日领取，固定时长有效期为90天，即有效时间为2013年10月1日-12月29日有效。
2. 无论check_consume填写的是true还是false,当code未被添加或者code被转赠领取是统一报错：invalid serial code
Parameters:

request - the request

Returns:

the user card response

Throws:

WeMpException - the we mp exception

consumeUserCard
```
@POST(value="card/code/consume")
UserCardResponse consumeUserCard(@Body
                                                                  UserCardInfo request)
                                                           throws WeMpException
```
核销Code接口，用于线下核销
消耗code接口是核销卡券的唯一接口,开发者可以调用当前接口将用户的优惠券进行核销，该过程不可逆
注意事项：
1. 仅支持核销有效状态的卡券，若卡券处于异常状态，均不可核销。（异常状态包括：卡券删除、未生效、过期、转赠中、转赠退回、失效）
2. 自定义Code码（use_custom_code为true）的优惠券，在code被核销时，必须调用此接口。用于将用户客户端的code状态变更。自定义code的卡券调用接口时， post数据中需包含card_id，否则报invalid serial code，非自定义code不需上报。
Parameters:

request - the request

Returns:

the user card response

Throws:

WeMpException - the we mp exception

decryptCode
```
@POST(value="card/code/decrypt")
GenericMpResponse<String> decryptCode(@Body
                                                                       DecryptCodeRequest request)
                                                                throws WeMpException
```
Code解码接口
code解码接口支持两种场景：
1. 商家获取choos_card_info后，将card_id和encrypt_code字段通过解码接口，获取真实code。
2. 卡券内跳转外链的签名中会对code进行加密处理，通过调用解码接口获取真实code。
Parameters:

request - the request

Returns:

the generic mp response

Throws:

WeMpException - the we mp exception

getUserCardList

@POST(value="card/user/getcardlist")
CardListResponse getUserCardList(@Body
                                                                      OpenUserCard request)
                                                               throws WeMpException

获取用户已领取卡券接口

用于获取用户卡包里的，属于该appid下所有可用卡券，包括正常状态和异常状态。

Parameters:: request - the request
Returns:: the card list
Throws:: WeMpException - the we mp exception

getCard

@POST(value="card/get")
GenericMpResponse<AbstractCard> getCard(@Body
                                                                CardId request)
                                                         throws WeMpException

查看卡券详情

开发者可以调用该接口查询某个card_id的创建信息、审核状态以及库存数量。

Parameters:: request - the request
Returns:: the card
Throws:: WeMpException - the we mp exception

deleteCard
```
@POST(value="card/delete")
MpResponse deleteCard(@Body
                                                 CardId request)
                                          throws WeMpException
```
删除卡券接口
删除卡券接口允许商户删除任意一类卡券。删除卡券后，该卡券对应已生成的领取用二维码、添加到卡包JS API均会失效。
注意：如用户在商家删除卡券前已领取一张或多张该卡券依旧有效。即删除卡券不能删除已被用户领取，保存在微信客户端中的卡券。

Parameters:

request - the request

Returns:

the mp response

Throws:

WeMpException - the we mp exception

unavailableCardCode

@POST(value="card/code/unavailable")
MpResponse unavailableCardCode(@Body
                                                                    AbandonCardCodeRequest request)
                                                             throws WeMpException

设置卡券失效接口

为满足改票、退款等异常情况，可调用卡券失效接口将用户的卡券设置为失效状态。

Parameters:: request - the request
Returns:: the mp response
Throws:: WeMpException - the we mp exception

batchGetCard

@POST(value="card/batchget")
BatchCardResponse batchGetCard(@Body
                                                            BatchCardRequest request)
                                                     throws WeMpException

批量查询卡券列表

Parameters:: request - the request
Returns:: the batch card response
Throws:: WeMpException - the we mp exception

updateCard

@POST(value="card/update")
GenericMpResponse<Boolean> updateCard(@Body
                                                                 UpdateCardRequest request)
                                                          throws WeMpException

更改卡券信息接口

支持更新所有卡券类型的部分通用字段及特殊卡券（会员卡、飞机票、电影票、会议门票）中特定字段的信息。

Parameters:: request - the request
Returns:: the generic mp response
Throws:: WeMpException - the we mp exception

modifyStock

@POST(value="card/modifystock")
MpResponse modifyStock(@Body
                                                       ModifyStockRequest request)
                                                throws WeMpException

修改库存接口

调用修改库存接口增减某张卡券的库存。

Parameters:: request - the request
Returns:: the mp response
Throws:: WeMpException - the we mp exception

activateMemberCard

@POST(value="card/membercard/activate")
MpResponse activateMemberCard(@Body
                                                                      MemberCardActivateRequest request)
                                                               throws WeMpException

Activate member card mp response.

Parameters:: request - the request
Returns:: the mp response
Throws:: WeMpException - the we mp exception

setActivateForm

@POST(value="card/membercard/activateuserform/set")
MpResponse setActivateForm(@Body
                                                                               MemberCardActivateForm request)
                                                                        throws WeMpException

设置开卡字段接口

开发者在创建时填入wx_activate字段后，需要调用该接口设置用户激活时需要填写的选项，否则一键开卡设置不生效。

参见 ...

Parameters:: request - the request
Returns:: the activate form
Throws:: WeMpException - the we mp exception UserCardInfo

getUserinfo

@POST(value="card/membercard/userinfo/get")
CardUserInfoResponse getUserinfo(@Body
                                                                             UserCardInfo request)
                                                                      throws WeMpException

步骤五：拉取会员信息接口

支持开发者根据CardID和Code查询会员信息。

Parameters:: request - the request
Returns:: userinfo userinfo
Throws:: WeMpException - the we mp exception

updateUser

@POST(value="card/membercard/updateuser")
CardUpdateUserResponse updateUser(@Body
                                                                            CardUpdateUserRequest request)
                                                                     throws WeMpException

更新会员信息

当会员持卡消费后，支持开发者调用该接口更新会员信息。会员卡交易后的每次信息变更需通过该接口通知微信，便于后续消息通知及其他扩展功能。

Parameters:: request - the request
Returns:: the card landing response
Throws:: WeMpException - the we mp exception

updateCode
```
@POST(value="card/code/update")
MpResponse updateCode(@Body
                                                      UpdateCodeRequest request)
                                               throws WeMpException
```
更改Code接口
为确保转赠后的安全性，微信允许自定义Code的商户对已下发的code进行更改。
注：为避免用户疑惑，建议仅在发生转赠行为后（发生转赠后，微信会通过事件推送的方式告知商户被转赠的卡券Code）对用户的Code进行更改。

Parameters:

request - the request

Returns:

the mp response

Throws:

WeMpException - the we mp exception

addPayGiftCard
```
@POST(value="card/paygiftcard/add")
PayGiftRulesResponse addPayGiftCard(@Body
                                                                        PayGiftRulesRequest request)
                                                                 throws WeMpException
```
设置支付后投放卡券接口
开通微信支付的商户可以设置在用户微信支付后自动为用户发送一条领卡消息，用户点击消息即可领取会员卡/优惠券。目前该功能仅支持微信支付商户号主体和制作会员卡公众号主体一致的情况下配置，否则报错。

Parameters:

request - the request

Returns:

the mp response

Throws:

WeMpException - the we mp exception

deletePayGiftCard

@POST(value="card/paygiftcard/delete")
MpResponse deletePayGiftCard(@Body
                                                                    PayGiftRuleId request)
                                                             throws WeMpException

删除支付后投放卡券规则接口

删除之前已经设置的支付即会员规则。

Parameters:: request - the request
Returns:: the mp response
Throws:: WeMpException - the we mp exception

getCardBizuinInfo

@POST(value="datacube/getcardbizuininfo")
CardDataList<CardBiz> getCardBizuinInfo(@Body
                                                                                  CardBizRequest request)
                                                                           throws WeMpException

拉取卡券概况数据接口

支持调用该接口拉取本商户的总体数据情况，包括时间区间内的各指标总量。

Parameters:: request - the request
Returns:: the card bizuin info
Throws:: WeMpException - the we mp exception

getCardCardInfo

@POST(value="datacube/getcardcardinfo")
CardDataList<FreeCardBiz> getCardCardInfo(@Body
                                                                                  CardInfoRequest request)
                                                                           throws WeMpException

获取免费券数据接口

支持开发者调用该接口拉取免费券（优惠券、团购券、折扣券、礼品券）在固定时间区间内的相关数据。

Parameters:: request - the request
Returns:: the card card info
Throws:: WeMpException - the we mp exception

getCardMemberCardInfo

@POST(value="datacube/getcardmembercardinfo")
CardDataList<MemberCardBiz> getCardMemberCardInfo(@Body
                                                                                                CardBizRequest request)
                                                                                         throws WeMpException

拉取会员卡概况数据接口

支持开发者调用该接口拉取公众平台创建的会员卡相关数据。

Parameters:: request - the request
Returns:: the card member card info
Throws:: WeMpException - the we mp exception

getCardMemberCardInfo

@POST(value="datacube/getcardmembercarddetail")
CardDataList<MemberCardDetail> getCardMemberCardInfo(@Body
                                                                                                     MemberCardDetailRequest request)
                                                                                              throws WeMpException

拉取单张会员卡数据接口

支持开发者调用该接口拉取API创建的会员卡数据情况

Parameters:: request - the request
Returns:: the card member card info
Throws:: WeMpException - the we mp exception

Interface CardApi

Method Summary

Method Detail

createCard

createQrcode

setPayCell

setSelfConsumeCell

setTestWhitelist

landingpage

getUserCard

consumeUserCard

decryptCode

getUserCardList

getCard

deleteCard

unavailableCardCode

batchGetCard

updateCard

modifyStock

activateMemberCard

setActivateForm

getUserinfo

updateUser

updateCode

addPayGiftCard

deletePayGiftCard

getCardBizuinInfo

getCardCardInfo

getCardMemberCardInfo

getCardMemberCardInfo