完成接入准备后，商家/服务商可根据本文指引快速接入 私域营销。

说明：

私域营销 支持自研商家/ISV 通过自研应用或第三方应用自调用（不传 app_auth_token）或代调用（传 app_auth_token）方式，调用 API 接入。

私域营销 暂不支持沙箱调试。

私域营销 仅支持 2021 年 12 月 1 日后创建的支付券或商家券活动。

完整接口时序图

接入代运营授权

服务商代商家接入 私域营销 前，需根据商家身份确定是否进行代运营授权。

**注意：**自研商家无需进行代运营授权。

代运营授权

适用商家: 间连商家、直连商家

服务商需向商家发起营销代运营授权，商家在支付宝上授权后，服务商能代商家进行券发放等营销活动操作，详情可查看接口代运营授权。

**注意：**代运营授权：

支持服务商使用自研应用及第三方应用自调用（即无需传入 app_auth_token）方式进行接入。

alipay.open.sp.operation.apply（向商户发起代运营操作接口） operate_type（操作类型）参数需传入 OPERATION_AUTH（授权操作）类型。

接入私域营销

查询营销活动

商家/服务商可按如下指引调用接口，接入活动批量查询、参与咨询、详情查询等接口。

条件查询活动列表

商家/服务商需调用 alipay.marketing.activity.batchquery（条件查询活动列表接口）批量查询营销活动（支持商家券、支付券），获取活动列表。

注意：

该接口为准实时接口，变更活动后到该接口可以查询出变更后的活动数据中间存在一定延迟，正常情况下平均延迟时间小于 1 分钟，最长不超过 1 小时。商家/服务商在开发时应充分考虑延迟可能带来的问题。

该接口只能查询出有效数据，若商家主动终止活动或者活动已过期则该接口无法查询到该活动，暂停的活动仍然可以查询。

服务商与商家建立代运营授权关系后，可以通过 merchant_id 参数，查询指定商家的活动。

请求示例

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayMarketingActivityApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayMarketingActivityApiBatchquery {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayMarketingActivityApi api = new AlipayMarketingActivityApi();
        AlipayMarketingActivityBatchqueryModel data = new AlipayMarketingActivityBatchqueryModel();
        data.setPageSize(20);
        data.setPageNum(1);
        data.setMerchantId("2088202967380463");
        data.setMerchantAccessMode("SELF_MODE");
        data.setActivityStatus("ACTIVE");
        try {
            AlipayMarketingActivityBatchqueryResponseModel response = api.batchquery(data);
        } catch (ApiException e) {
            AlipayMarketingActivityBatchqueryDefaultResponse errorObject = (AlipayMarketingActivityBatchqueryDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

响应示例

{
    "code":"unknow-error",
    "message":"系统繁忙"
}

活动参与咨询

通过条件查询活动后，商家/服务商可调用 alipay.marketing.activity.consult（商家营销活动咨询接口）判断当前用户是否可以参与此活动。接口根据活动创建时设置的活动参与规则与风控规则判断当前用户是否可以参与活动。

注意：

本接口支持批量传入活动，每次传入数量不得超过 10 个。

调用接口完成后，可以通过返回的结果决定活动是否要展示给当前用户（不可参与的活动展示给用户会影响用户体验）。

请求示例

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayMarketingActivityApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayMarketingActivityApiConsult {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayMarketingActivityApi api = new AlipayMarketingActivityApi();
        AlipayMarketingActivityConsultModel data = new AlipayMarketingActivityConsultModel();
        data.setMerchantId("2088102111111111");
        data.setUserId("2088xxxx");
        data.setMerchantAccessMode("SELF_MODE");
        List<ConsultActivityInfo> consultActivityInfoList = new ArrayList<ConsultActivityInfo>();
        ConsultActivityInfo consultActivityInfoList0 = new ConsultActivityInfo();
        consultActivityInfoList0.setActivityId("201623213214325423");
        consultActivityInfoList.add(consultActivityInfoList0);
        data.setConsultActivityInfoList(consultActivityInfoList);
        try {
            AlipayMarketingActivityConsultResponseModel response = api.consult(data);
        } catch (ApiException e) {
            AlipayMarketingActivityConsultDefaultResponse errorObject = (AlipayMarketingActivityConsultDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

响应示例

{
    "code":"unknow-error",
    "message":"系统繁忙"
}

活动详情查询

商家/服务商需调用 alipay.marketing.activity.query（查询活动详情接口）查询活动详情信息。

**注意：**该接口可以查询出商家/服务商在商家中心、服务商平台或通过 支付券、商家券 API 创建的活动。

请求示例

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayMarketingActivityApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayMarketingActivityApiQuery {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayMarketingActivityApi api = new AlipayMarketingActivityApi();
        String activityId = "2016042700826004508401111111";
        String merchantId = "2088202967380463";
        String merchantAccessMode = "SELF_MODE";
        try {
            AlipayMarketingActivityQueryResponseModel response = api.query(activityId, merchantId, merchantAccessMode);
        } catch (ApiException e) {
            AlipayMarketingActivityQueryDefaultResponse errorObject = (AlipayMarketingActivityQueryDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

响应示例

{
    "code":"unknow-error",
    "message":"系统繁忙"
}

活动适用范围

商家/服务商可按如下指引调用接口，接入私域营销 活动适用商户、活动适用小程序、活动适用门店、活动适用商户 接口，灵活判断指定活动适用范围。

接口调用流程

活动适用商家

商家/服务商可调用 alipay.marketing.activity.merchant.batchquery（查询活动可用商户接口）查询指定活动适用商户范围或判断某活动在商家处是否可用。

注意：

该接口为准实时接口，变更活动适用商家到该接口查询出变更后的适用商家范围中间存在一定延迟，正常情况下平均延迟时间小于 1 分钟，最长不超过 1 小时。商家/服务商在开发时应充分考虑延迟可能带来的问题。

无论间连商户还是直连商户必须有蚂蚁门店该接口才会返回对应的适用商家范围。

商家券场景下只有指定蚂蚁门店可用才会返回对应的适用商家范围。

请求示例

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayMarketingActivityMerchantApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayMarketingActivityMerchantApiBatchquery {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayMarketingActivityMerchantApi api = new AlipayMarketingActivityMerchantApi();
        String activityId = "2016042700826004508401111111";
        String merchantId = "2088202967380463";
        Integer pageNum = 1;
        Integer pageSize = 20;
        String merchantAccessMode = "AGENCY_MODE";
        try {
            AlipayMarketingActivityMerchantBatchqueryResponseModel response = api.batchquery(activityId, merchantId, pageNum, pageSize, merchantAccessMode);
        } catch (ApiException e) {
            AlipayMarketingActivityMerchantBatchqueryDefaultResponse errorObject = (AlipayMarketingActivityMerchantBatchqueryDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

响应示例

{
    "code":"unknow-error",
    "message":"系统繁忙"
}

活动适用小程序

商家/服务商可调用 alipay.marketing.activity.app.batchquery（查询活动可用小程序接口）查询指定活动适用小程序范围或判断某活动在小程序是否可用。

**注意：**该接口为准实时接口，变更活动适用小程序到该接口查询出变更后的适用小程序范围中间存在一定延迟，正常情况下平均延迟时间小于 1 分钟，最长不超过 1 小时。商家/服务商在开发时应充分考虑延迟可能带来的问题。

请求示例

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayMarketingActivityAppApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayMarketingActivityAppApiBatchquery {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayMarketingActivityAppApi api = new AlipayMarketingActivityAppApi();
        String activityId = "2016042700826004508401111111";
        String merchantId = "2088202967380463";
        Integer pageNum = 1;
        String pageSize = "20";
        String merchantAccessMode = "SELF_MODE";
        try {
            AlipayMarketingActivityAppBatchqueryResponseModel response = api.batchquery(activityId, merchantId, pageNum, pageSize, merchantAccessMode);
        } catch (ApiException e) {
            AlipayMarketingActivityAppBatchqueryDefaultResponse errorObject = (AlipayMarketingActivityAppBatchqueryDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

响应示例

{
    "code":"unknow-error",
    "message":"系统繁忙"
}

活动适用门店

商家/服务商可调用 alipay.marketing.activity.shop.batchquery（查询活动可用门店接口）查询指定活动适用门店范围或判断某活动在门店是否可用。

**注意：**该接口为准实时接口，变更活动适用门店到该接口查询出变更后的适用门店范围中间存在一定延迟，正常情况下平均延迟时间 30 分钟，最长不超过 3 小时。商家/服务商在开发时应充分考虑延迟可能带来的问题。

请求示例

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayMarketingActivityShopApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayMarketingActivityShopApiBatchquery {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayMarketingActivityShopApi api = new AlipayMarketingActivityShopApi();
        String activityId = "2016042700826004508401111111";
        String merchantId = "2088202967380463";
        Integer pageNum = 1;
        Integer pageSize = 20;
        String productVersion = null;
        String merchantAccessMode = "SELF_MODE";
        try {
            AlipayMarketingActivityShopBatchqueryResponseModel response = api.batchquery(activityId, merchantId, pageNum, pageSize, productVersion, merchantAccessMode);
        } catch (ApiException e) {
            AlipayMarketingActivityShopBatchqueryDefaultResponse errorObject = (AlipayMarketingActivityShopBatchqueryDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

响应示例

{
    "code":"unknow-error",
    "message":"系统繁忙"
}

活动适用商品

商家/服务商可调用 alipay.marketing.activity.goods.batchquery（查询活动适用商品接口）查询指定活动适用商品范围或判断某活动该商品是否可用。

注意：

该接口为准实时接口，变更活动适用商品到该接口查询出变更后的适用商品范围中间存在一定延迟，正常情况下平均延迟时间30分钟，最长不超过3小时。商家/服务商在开发时应充分考虑延迟可能带来的问题。

因为目前商家券创建未上传商品编码所以该接口暂不支持商家券。

请求示例

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayMarketingActivityGoodsApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayMarketingActivityGoodsApiBatchquery {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayMarketingActivityGoodsApi api = new AlipayMarketingActivityGoodsApi();
        String activityId = "2016042700826004508401111111";
        String merchantId = "2088202967380463";
        String goodsUseType = "AVAILABLE";
        Integer pageNum = 1;
        Integer pageSize = 20;
        String productVersion = null;
        String merchantAccessMode = "SELF_MODE";
        try {
            AlipayMarketingActivityGoodsBatchqueryResponseModel response = api.batchquery(activityId, merchantId, goodsUseType, pageNum, pageSize, productVersion, merchantAccessMode);
        } catch (ApiException e) {
            AlipayMarketingActivityGoodsBatchqueryDefaultResponse errorObject = (AlipayMarketingActivityGoodsBatchqueryDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

响应示例

{
    "code":"unknow-error",
    "message":"系统繁忙"
}

用户领券核销

商家/服务商需要接入私域营销领券插件，用户触发领券操作后商家/服务商小程序前端调用领券插件为用户发券，发券成功后支付宝会发送领券消息给当前发券 APPID。

领券插件

支付宝为商家小程序提供了 领券组件插件 可在小程序内向指定用户发放指定券活动 id 支付宝优惠券。用户通过该插件领取优惠券后，将自动加入支付宝卡包，提升用户领券感知及核销率。接入详情参见领券组件插件接入流程。

用户券核销

用户领券成功后，支付券通过支付宝支付时核销，商家券通过商家/服务商自身系统核销后。支付宝将会发放核销消息给领券时的 appId。

商户卡包

商家/服务商可按如下指引调用接口，接入私域营销 条件查询用户券、查询用户券详情 接口，实现商户自定义卡包。

**注意：**商户卡包相关接口 条件查询用户券、查询用户券详情 目前 不支持三方应用自调用 方式接入。

接口调用流程

用户授权

商家/服务商查询用户券信息需要获取用户授权，用户授权通过后才能调用用户券查询接口查询用户券信息。

**注意：**用户券查询请求授权 scope 为 voucher_query，调用 my.getAuthCode 获取 authCode，更多详情见用户授权流程。

条件查询用户券

商家/服务商可调用 alipay.marketing.activity.user.batchqueryvoucher（条件查询用户券接口）按条件批量查询用户券信息。

**注意：**该接口目前 不支持三方应用自调用 方式接入。

请求示例

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayMarketingActivityUserApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayMarketingActivityUserApiBatchqueryvoucher {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayMarketingActivityUserApi api = new AlipayMarketingActivityUserApi();
        String authToken = null;
        String userId = "2088512417841101";
        String openId = null;
        String activityId = "2016042700826004508401111111";
        String belongMerchantId = "2088202967380463";
        String senderMerchantId = "2088102161342862";
        String voucherStatus = "SENDED";
        Integer pageNum = 1;
        String merchantAccessMode = "SELF_MODE";
        Integer pageSize = 20;
        try {
            AlipayMarketingActivityUserBatchqueryvoucherResponseModel response = api.batchqueryvoucher(authToken, userId, openId, activityId, belongMerchantId, senderMerchantId, voucherStatus, pageNum, merchantAccessMode, pageSize);
        } catch (ApiException e) {
            AlipayMarketingActivityUserBatchqueryvoucherDefaultResponse errorObject = (AlipayMarketingActivityUserBatchqueryvoucherDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

响应示例

{
    "code":"unknow-error",
    "message":"系统繁忙"
}

查询用户券详情

商家/服务商可调用 alipay.marketing.activity.user.queryvoucher（查询用户券详情接口）查询指定用户券详细信息。

**注意：**该接口目前 不支持三方应用自调用 方式接入。

请求示例

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayMarketingActivityUserApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayMarketingActivityUserApiQueryvoucher {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayMarketingActivityUserApi api = new AlipayMarketingActivityUserApi();
        String merchantId = "2088202967380463";
        String userId = "2088512417841101";
        String openId = null;
        String activityId = "2016042700826004508401111111";
        String voucherId = "2021072900073002214009F8QHR3";
        String voucherCode = "ABE44";
        String merchantAccessMode = "SELF_MODE";
        try {
            AlipayMarketingActivityUserQueryvoucherResponseModel response = api.queryvoucher(merchantId, userId, openId, activityId, voucherId, voucherCode, merchantAccessMode);
        } catch (ApiException e) {
            AlipayMarketingActivityUserQueryvoucherDefaultResponse errorObject = (AlipayMarketingActivityUserQueryvoucherDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

响应示例

{
    "code":"unknow-error",
    "message":"系统繁忙"
}

消息通知

用户领券、核销、券过期等场景，支付宝都将通过 From 蚂蚁消息通知向 商家应用 或 第三方应用 应用网关推送异步通知消息，同步对应操作结果。

若商家/服务商网络环境比较复杂，如：通过统一网关间连互联网，推荐使用网络兼容性更好的标准 http(s) 协议进行对接。

第一步：订阅消息

商家/ISV 需根据订阅消息指引，为接入私域营销的 商家应用 或 第三方应用 订阅如下消息接口。

注意：

仅完成订阅后才会收到支付宝发送的对应异步通知消息。

商家/服务商可通过消息通知中 msg_method 参数判断消息类型。

消息接口英文名	消息接口中文名	作用
alipay.marketing.activity.message.received	券领取消息	同步用户领券及对应券信息。
alipay.marketing.activity.message.used	券核销消息	同步用户券核销及对应券信息。
alipay.marketing.activity.message.expired	券过期消息	同步用户券过期及对应券信息。

第二步：验签

商家/服务商可使用支付宝 SDK 可根据使用生成密钥验签指引，使用应用密钥信息验证异步通知消息来源是否为支付宝。

第三步：反馈消息接收结果

收到异步通知后，商家/服务商需返回 success 表示消息获取成功，支付宝就会停止发送异步通知。如果返回 fail 或其他值，表示消息获取失败，支付宝会根据投递重试策略重新发送消息到应用网关地址。

**说明：**在接收异步进行验签，如果验签成功输出 success，验签失败返回 fail，重新接收异步进行处理。

响应值	描述	是否重试
fail	消息获取失败	重试
success	消息获取成功	不重试

用户券消息通知

用户领券通知

无论是PC端或API创建的活动，只要是用户通过私域营销领券插件领取的优惠券，支付宝将通过 alipay.marketing.activity.message.received（商家券领取通知接口）同步领券用户 user_id（支付宝用户 ID）、voucher_code（优惠券码）等信息到领券的 appId。

消息示例

ISV_GATEWAY_URL?charset=GBK&biz_content=
{
  "id":"RECEIVED_2021042400826001508407723739",
  "activity_id":"2016042700826004508401111111",
  "event_time":"1619338271",
  "voucher_code":"voucher_code",
  "receive_user_id":"2088xxxxx"
}&msg_method=alipay.marketing.activity.message.received&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2&notify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==

用户券核销通知

无论是PC端或API创建的活动，只要是用户通过私域营销领券插件领取的优惠券，支付宝将通过 alipay.marketing.activity.message.used（券核销消息接口）同步券核销用户 user_id（支付宝用户 ID）、voucher_code（优惠券码）等信息到领券的 appId。

消息示例

ISV_GATEWAY_URL?charset=GBK&biz_content=
{
  "id":"USED_2021042400826001508407723739",
  "activity_id":"2016042700826004508401111111",
  "event_time":"1619338271",
  "voucher_id":"2021072900073002214009F8QHR3",
  "user_id":"核销的支付宝user_id",
  "trade_no":"2021042322001426261436764012"
}&msg_method=alipay.marketing.activity.message.used&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2&notify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==

用户券过期通知

无论是PC端或API创建的活动，只要是用户通过私域营销领券插件领取的优惠券，支付宝将通过 alipay.marketing.activity.message.expired（券过期消息接口）同步券过期用户 user_id（支付宝用户 ID）、voucher_code（优惠券码）等信息到领券的 appId。

消息示例

ISV_GATEWAY_URL?charset=GBK&biz_content=
{
  "id":"EXPIRED_2021042400826001508407723739",
  "activity_id":"2016042700826004508401111111",
  "event_time":"1619338271",
  "voucher_id":"2021072900073002214009F8QHR3",
  "voucher_code":"voucher_code",
  "user_id":"2088xxxxx"
}&msg_method=alipay.marketing.activity.message.expired&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2&notify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==

沙箱调试

私域营销功能暂时不支持沙箱调试。

开发接入

完整接口时序图#

接入代运营授权#

代运营授权#

接入私域营销#

查询营销活动#

条件查询活动列表#

请求示例#

响应示例#

活动参与咨询#

请求示例#

响应示例#

活动详情查询#

请求示例#

响应示例#

活动适用范围#

接口调用流程#

活动适用商家#

请求示例#

响应示例#

活动适用小程序#

请求示例#

响应示例#

活动适用门店#

请求示例#

响应示例#

活动适用商品#

请求示例#

响应示例#

用户领券核销#

领券插件#

用户券核销#

商户卡包#

接口调用流程#

用户授权#

条件查询用户券#

请求示例#

响应示例#

查询用户券详情#

请求示例#

响应示例#

消息通知#

第一步：订阅消息#

第二步：验签#

第三步：反馈消息接收结果#

用户券消息通知#

用户领券通知#

消息示例#

用户券核销通知#

消息示例#

用户券过期通知#

消息示例#

沙箱调试#

完整接口时序图

接入代运营授权

代运营授权

接入私域营销

查询营销活动

条件查询活动列表

请求示例

响应示例

活动参与咨询

请求示例

响应示例

活动详情查询

请求示例

响应示例

活动适用范围

接口调用流程

活动适用商家

请求示例

响应示例

活动适用小程序

请求示例

响应示例

活动适用门店

请求示例

响应示例

活动适用商品

请求示例

响应示例

用户领券核销

领券插件

用户券核销

商户卡包

接口调用流程

用户授权

条件查询用户券

请求示例

响应示例

查询用户券详情

请求示例

响应示例

消息通知

第一步：订阅消息

第二步：验签

第三步：反馈消息接收结果

用户券消息通知

用户领券通知

消息示例

用户券核销通知

消息示例

用户券过期通知

消息示例

沙箱调试