商家/服务商接入 优惠券 并完成接入准备后，可以使用支付宝提供的推广功能将 优惠券 推广至支付宝对外开放的相关曝光渠道。

说明：引流转化 支持自研商家/服务商通过自研、代开发、代运营模式调用 API 接入，各模式配置详情可查看接入准备。

接入代运营授权

**适用商家：**直连商家。

服务商代商家进行推广操作前，需根据商家身份确定是否进行代运营授权，自研商家无需关注。

服务商需向商家发起营销代运营授权申请，并获得商家在支付宝上的授权后，服务商才能代商家进行创建营销活动等操作，详情可查看服务商代运营基础。

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

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

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

接入引流转化

接口调用时序图

**说明：**其中商家与服务商的交互流程仅为示意，具体交互方式以服务商实际使用场景为准。

推广计划状态流转图

注意：

创建推广之后进入审核中状态，审核结果通过异步消息通知到服务商。

已过期的推广计划会被定期清理进入已失效状态。

第一步：上传图片资料

商家/服务商调用 alipay.marketing.material.image.upload（营销图片资源上传接口），将优惠券的配图上传至支付宝获取 resource_id（图片唯一资源 ID）用于后续创建推广。

注意：

本接口需使用最新版服务端 SDK，如 Java 4.10.1 及以上版本。

上传图片资料时 file_key 固定为PUBLIC_UNION_CHANNEL_PIC。

上传图片尺寸 600 * 600，支持格式：PNG、JPG、JPEG、BMP，大小不超过 200 KB。更多图片上传要求可查看素材规范。

请求示例

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.AlipayMarketingMaterialImageApi;
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 AlipayMarketingMaterialImageApiUpload {

    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);
        AlipayMarketingMaterialImageApi api = new AlipayMarketingMaterialImageApi();
        AlipayMarketingMaterialImageUploadModel data = new AlipayMarketingMaterialImageUploadModel();
        BelongMerchantInfo belongMerchantInfo = new BelongMerchantInfo();
        belongMerchantInfo.setMerchantIdType("SMID");
        belongMerchantInfo.setMerchantId("2088202967380463");
        belongMerchantInfo.setBusinessType("ISV_FOR_MERCHANT");
        data.setBelongMerchantInfo(belongMerchantInfo);
        data.setFileKey("PROMO_VOUCHER_IMAGE");
        data.setMerchantAccessMode("SELF_MODE");
        File fileContent = new File("文件路径");
        try {
            AlipayMarketingMaterialImageUploadResponseModel response = api.upload(data, fileContent);
        } catch (ApiException e) {
            AlipayMarketingMaterialImageUploadDefaultResponse errorObject = (AlipayMarketingMaterialImageUploadDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

第二步：创建推广计划

商家/服务商调用 alipay.marketing.activity.delivery.create（创建推广计划），将商家/服务商系统中创建好的商家券推广至指定渠道。

注意：

推广活动 ID，一个活动 ID 同一时间仅可创建一个推广计划

活动 ID 为优惠券创建时返回的 activityid

目前支持商家支付券、商家券

用户领券链接
商家/服务商调用 delivery_guide_url（用户领券链接）来控制用户在支付宝领券时，跳转到商家小程序的页面。delivery_guide_url 必须为创建推广对应商家账号下的小程序 URL，且必须符合小程序scheme链接规范。

推广目的
商家支付宝做推广时，支持两种推广方式：

附近发券：根据商户门店位置发券（门店附近 3km），适用于到店点餐、自提、超市等线下场景。
注意：配置附近发券模式优惠券上必须配置门店。

全城发券：指定发券城市，适用于电商、外卖、同城闪送等线上场景。

推广成功后约有半小时延迟才会生效。

本接口仅提交推广计划创建申请，计划创建结果，以 alipay.marketing.activity.delivery.changed（推广计划状态变更消息）为准，可查看变更推广状态通知；还可通过 alipay.marketing.activity.delivery.query（查询推广计划），传入delivery_id（推广计划 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.AlipayMarketingActivityDeliveryApi;
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 AlipayMarketingActivityDeliveryApiCreate {

    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);
        AlipayMarketingActivityDeliveryApi api = new AlipayMarketingActivityDeliveryApi();
        AlipayMarketingActivityDeliveryCreateModel data = new AlipayMarketingActivityDeliveryCreateModel();
        data.setDeliveryBoothCode("PUBLIC_UNION");
        data.setOutBizNo("20170101000001654bb46ba");
        DeliveryPlayConfig deliveryPlayConfig = new DeliveryPlayConfig();
        DeliverySingleSendConfig deliverySingleSendConfig = new DeliverySingleSendConfig();
        DeliveryContentConfig deliveryContentConfig = new DeliveryContentConfig();
        DeliverySendGuide deliverySendGuide = new DeliverySendGuide();
        deliverySendGuide.setDeliveryGuideUrl("alipays://platformapi/startapp?appId=xxxx");
        deliveryContentConfig.setDeliverySendGuide(deliverySendGuide);
        deliverySingleSendConfig.setDeliveryContentConfig(deliveryContentConfig);
        DeliveryContentInfo deliveryContentInfo = new DeliveryContentInfo();
        DeliveryActivityContentInfo deliveryActivityContent = new DeliveryActivityContentInfo();
        deliveryActivityContent.setActivityId("20122131234434557567");
        deliveryContentInfo.setDeliveryActivityContent(deliveryActivityContent);
        deliveryContentInfo.setDeliveryContentType("ACTIVITY");
        deliverySingleSendConfig.setDeliveryContentInfo(deliveryContentInfo);
        deliveryPlayConfig.setDeliverySingleSendConfig(deliverySingleSendConfig);
        data.setDeliveryPlayConfig(deliveryPlayConfig);
        DeliveryBaseInfo deliveryBaseInfo = new DeliveryBaseInfo();
        DeliveryMaterial deliveryMaterial = new DeliveryMaterial();
        DeliverySingleMaterial deliverySingleMaterial = new DeliverySingleMaterial();
        deliverySingleMaterial.setDeliveryImage("A*WXYTAswgww");
        deliveryMaterial.setDeliverySingleMaterial(deliverySingleMaterial);
        deliveryBaseInfo.setDeliveryMaterial(deliveryMaterial);
        deliveryBaseInfo.setDeliveryName("第十期投放计划");
        deliveryBaseInfo.setDeliveryBeginTime("2017-01-01 00:00:01");
        deliveryBaseInfo.setDeliveryEndTime("2017-01-01 00:00:01");
        data.setDeliveryBaseInfo(deliveryBaseInfo);
        DeliveryTargetRule deliveryTargetRule = new DeliveryTargetRule();
        DeliveryCityCodeRule deliveryCityCodeRule = new DeliveryCityCodeRule();
        deliveryCityCodeRule.setAllCity(true);
        List<String> cityCodes = new ArrayList<String>();
        cityCodes.add("100100");
        deliveryCityCodeRule.setCityCodes(cityCodes);
        deliveryTargetRule.setDeliveryCityCodeRule(deliveryCityCodeRule);
        data.setDeliveryTargetRule(deliveryTargetRule);
        data.setMerchantAccessMode("SELF_MODE");
        try {
            AlipayMarketingActivityDeliveryCreateResponseModel response = api.create(data);
        } catch (ApiException e) {
            AlipayMarketingActivityDeliveryCreateDefaultResponse errorObject = (AlipayMarketingActivityDeliveryCreateDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

第三步：查询推广计划

商家/服务商可以调用 alipay.marketing.activity.delivery.query（查询推广计划），查询推广计划的详情信息。

请求示例

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.AlipayMarketingActivityDeliveryApi;
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 AlipayMarketingActivityDeliveryApiQuery {

    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);
        AlipayMarketingActivityDeliveryApi api = new AlipayMarketingActivityDeliveryApi();
        String deliveryId = "20121231231242353";
        AlipayMarketingActivityDeliveryQueryModel data = new AlipayMarketingActivityDeliveryQueryModel();
        data.setMerchantAccessMode("AGENCY_MODE");
        try {
            AlipayMarketingActivityDeliveryQueryResponseModel response = api.query(deliveryId, data);
        } catch (ApiException e) {
            AlipayMarketingActivityDeliveryQueryDefaultResponse errorObject = (AlipayMarketingActivityDeliveryQueryDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

第四步：停止推广计划

商家/服务商可调用 alipay.marketing.activity.delivery.stop（停止推广计划），停止已经推广到指定渠道的推广计划。

注意：

调用接口停止推广后，存在 5 ~ 10 分钟延迟才会生效。

已经停止的推广，可以使用 alipay.marketing.activity.delivery.create（创建推广计划）再次将推广生效。

请求示例

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.AlipayMarketingActivityDeliveryApi;
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 AlipayMarketingActivityDeliveryApiStop {

    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);
        AlipayMarketingActivityDeliveryApi api = new AlipayMarketingActivityDeliveryApi();
        String deliveryId = "20121231231242353";
        AlipayMarketingActivityDeliveryStopModel data = new AlipayMarketingActivityDeliveryStopModel();
        data.setOutBizNo("20170101000001654bb46ba");
        data.setMerchantAccessMode("SELF_MODE");
        try {
            AlipayMarketingActivityDeliveryStopResponseModel response = api.stop(deliveryId, data);
        } catch (ApiException e) {
            AlipayMarketingActivityDeliveryStopDefaultResponse errorObject = (AlipayMarketingActivityDeliveryStopDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

消息通知

商家/服务商创建的审核中推广计划在审核后，支付宝都将通过 alipay.marketing.activity.delivery.changed（推广计划状态变更消息）向商家应用或第三方应用应用网关推送异步通知消息，同步审核结果。

说明：

更多支付宝异步消息通知详情可查看From 蚂蚁消息服务使用。

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

第一步：订阅消息

商家/服务商需根据订阅消息指引，为接入商家自运营推广的商家应用或第三方应用订阅 alipay.marketing.activity.delivery.changed（推广计划状态变更消息）。

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

第二步：验签

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

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

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

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

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

变更推广状态通知

商家/服务商可以监听 alipay.marketing.activity.delivery.changed（推广计划状态变更消息），感知推广计划信息的变更。创建推广的推广计划会进入生效中或者审核中状态，审核中的推广计划在审核之后会通过 alipay.marketing.activity.delivery.changed（推广计划状态变更消息）触达到服务商。

注意：

变更推广计划通知会在推广计划变更存在变更时发出，包括创建、审核、停止、信息变更等操作生效之后发出。

变更推广计划通知仅包含简单的推广计划变更通知信息，更多推广计划信息需通过 alipay.marketing.activity.delivery.query（查询推广计划）获取。

消息示例

ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"out_biz_no":"abscd123341",
"event_time":"12342425435232423",
"delivery_id":"20121231231242353",
"delivery_status":"ACTIVE",
"delivery_error_msg":"素材不合格",
"delivery_booth_code":"PAYMENT_RESULT"
&msg_method=alipay.marketing.activity.delivery.changed&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2&notify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==

开发接入

接入代运营授权#

接入引流转化#

接口调用时序图#

推广计划状态流转图#

第一步：上传图片资料#

请求示例#

第二步：创建推广计划#

请求示例#

第三步：查询推广计划#

请求示例#

第四步：停止推广计划#

请求示例#

消息通知#

第一步：订阅消息#

第二步：验签#

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

变更推广状态通知#

消息示例#

接入代运营授权

接入引流转化

接口调用时序图

推广计划状态流转图

第一步：上传图片资料

请求示例

第二步：创建推广计划

请求示例

第三步：查询推广计划

请求示例

第四步：停止推广计划

请求示例

消息通知

第一步：订阅消息

第二步：验签

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

变更推广状态通知

消息示例