营销活动快速接入

更新时间：2017/06/08 访问次数：44781

第一步：创建应用
第二步：配置密钥
第三步：搭建和配置开发环境
第四步：调用接口
接口调用结果码说明
关于沙箱

第一步：创建应用

要在您的应用中使用支付宝开放产品的接口能力，您需要先去蚂蚁金服开放平台（open.alipay.com），在开发者中心创建登记您的应用，并提交审核，审核通过后会为您生成应用唯一标识（APPID），并且可以申请开通开放产品使用权限，通过APPID您的应用才能调用开放产品的接口能力。需要详细了解开放平台创建应用步骤请参考《开放平台应用创建指南》。

第二步：配置密钥

开发者调用接口前需要先生成RSA密钥，RSA密钥包含应用私钥(APP_PRIVATE_KEY)、应用公钥(APP_PUBLIC_KEY）。生成密钥后在开放平台开发者中心进行密钥配置，配置完成后可以获取支付宝公钥(ALIPAY_PUBLIC_KEY)。详情请参考《配置应用环境》。

第三步：搭建和配置开发环境

1. 下载服务端SDK

为了帮助开发者调用开放接口，我们提供了开放平台服务端SDK，包含JAVA、PHP和.NET三个语言版本，封装了签名&验签、HTTP接口请求等基础功能。请先下载对应语言版本的SDK并引入您的开发工程。

各语言版本服务端SDK详细使用说明，请参考《服务端SDK说明》。

2. 接口调用配置

在SDK调用前需要进行初始化，以Java代码为示例如下：

AlipayClient alipayClient = new DefaultAlipayClient(URL, APP_ID, APP_PRIVATE_KEY, FORMAT, CHARSET, ALIPAY_PUBLIC_KEY, SIGN_TYPE);

关键参数说明:

配置参数	示例值解释	获取方式/示例值
URL	支付宝网关（固定）	https://openapi.alipay.com/gateway.do
APPID	APPID 即创建应用后生成	获取见上面创建应用并获取APPID
APP_PRIVATE_KEY	开发者私钥，由开发者自己生成	获取详见上面配置密钥
FORMAT	参数返回格式，只支持json	json（固定）
CHARSET	编码集，支持GBK/UTF-8	开发者根据实际工程编码配置
ALIPAY_PUBLIC_KEY	支付宝公钥，由支付宝生成	获取详见上面配置密钥
SIGN_TYPE	商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2	RSA2

第四步：调用接口

活动管理产品包含以下接口：

接口英文名	接口中文名	接口描述
koubei.marketing.campaign.activity.create	创建营销活动	创建口碑营销活动
koubei.marketing.campaign.activity.modify	修改营销活动	修改已创建的营销活动
koubei.marketing.campaign.activity.offline	下架营销活动	将已创建的活动进行下架操作
koubei.marketing.campaign.activity.query	查询营销活动	查询已创建的营销活动详情
koubei.marketing.campaign.activity.batchquery	口碑营销活动列表查询	批量查询对应APPID商家下的营销活动
koubei.marketing.campaign.recruit.shop.query	招商门店分页查询接口	在邀约阶段查询招商活动各商家确认状态

接口调用示例大致分为3步：

拼装业务参数
将参数发送给开放平台服务端
获取开放平台服务端返回值，并进行具体业务处理

TIPS：ISV/开发者可以通过“第三方应用授权”得到商家授权令牌（app_auth_token）作为请求参数传入，实现代商家发起请求的能力；具体方法请参考《第三方应用授权》。

下面用“消费后送1分钱代金券”的营销活动场景来快速帮助你理解如何使用营销活动管理产品的接口。

1. 创建营销活动（koubei.marketing.campaign.activity.create）

首先我们通过创建营销活动接口，活动定义主要由活动基本信息，预算信息，活动约束信息，优惠券工具，投放渠道和招商工具信息组成，为了演示简单，我们仅用必要的配置来创建一个“消费后送1分钱代金券”的活动，如需了解更详细的活动创建配置说明，可参阅进阶说明。

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
KoubeiMarketingCampaignActivityCreateRequest alipayRequest = new KoubeiMarketingCampaignActivityCreateRequest();
      
String bizContent = "{"
    +   "\"out_biz_no\":\"20160715000001\","  //外部业务流水号，不可重复
    +   "\"name\":\"消费后送1分钱代金券\","
    +   "\"start_time\":\"2016-07-11 00:00:00\","  
    +   "\"end_time\":\"2017-07-10 23:59:59\","
    +   "\"type\":\"CONSUME_SEND\"," //消费送类型
    +   "\"promo_tools\":[{" //定义优惠券
    +     "\"voucher\":{"
    +       "\"type\":\"MONEY\","
    +       "\"name\":\"代金券\","
    +       "\"brand_name\":\"口碑\","
    +       "\"logo\":\"VRszjvC5Qg2GgdfYB_6QcAAAACMAAQED\","
              //logo需要通过图片资料上传接口获取图片ID
    +       "\"worth_value\":\"0.01\","
    +       "\"validate_type\":\"RELATIVE\","
    +       "\"relative_time\":\"1\","
    +       "\"effect_type\":\"IMMEDIATELY\","
    +       "\"use_rule\":{"
    +         "\"suit_shops\":["
    +           "\"2016052300077000000015587332\""
    +         "]"
    +       "}"
    +     "},"
    +     "\"send_rule\":{"
    +       "\"min_cost\":\"0.01\""
    +     "}"
    +   "}],"
    +   "\"constraint_info\":{"
    +     "\"suit_shops\":["
    +       "\"2016052300077000000015587332\""
    +     "]"
    +   "}"
    + "}";
    
alipayRequest.setBizContent(bizContent);
KoubeiMarketingCampaignActivityCreateResponse alipayResponse = alipayClient.execute(alipayRequest);
//处理接口返回消息alipayResponse

TIPS：如果创建成功 alipayResponse.getCode() 可以获取结果码10000，结果码和错误码请参考本文结果码说明章节。alipayResponse.getCampId() 可以获取营销活动ID，后面会用到。

TIPS：此处bizContent中的logo参数，需要使用图片资源ID，可以通过“ 图片资料上传接口”上传图片资料并得到图片资源ID。

2. 查询营销活动（koubei.marketing.campaign.activity.query）

营销活动创建完成后，可以通过营销活动ID来查询活动信息。

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
KoubeiMarketingCampaignActivityQueryRequest alipayRequest = new KoubeiMarketingCampaignActivityQueryRequest();
String bizContent = "{"
    +   "\"camp_id\":\"20160715000000000056518000151415\""
    //camp_id为创建营销活动成功后获取的营销活动ID
    + "}";
alipayRequest.setBizContent(bizContent);
KoubeiMarketingCampaignActivityQueryResponse alipayResponse = alipayClient.execute(alipayRequest);
//处理接口返回消息alipayResponse

开发者可以通过两种方法处理返回结果，一个通过alipayResponse.getBody()方法获取营销活动信息JSON串进行处理，一个是通过alipayResponse.getCampDetail()方法获取SDK封装好的CampDetail对象进行处理。要了解返回活动信息结构可以参考API列表。

3. 修改营销活动（koubei.marketing.campaign.activity.modify）

开发者可以通过修改营销活动接口修改营销活动配置信息，不过需要注意的是当前接口只能针对“已启动(STARTED)”的活动，修改特定的属性。例如，追加活动预算，延长活动时间，追加门店和放宽活动约束。但在组装修改活动信息报文时，为了保证开发者修改意图的信息正确性，修改接口要求开发者还是将活动完整信息拼装成报文，所以建议在调用修改营销活动接口前调用查询营销活动接口。下面以修改营销活动延期1个月为例演示如何使用接口。

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
KoubeiMarketingCampaignActivityModifyRequest alipayRequest = new KoubeiMarketingCampaignActivityModifyRequest();

String bizContent = "{"
    +   "\"out_biz_no\":\"20160715000001\","
    +   "\"camp_id\":\"20160715000000000056518000151415\","
    +   "\"name\":\"消费后送1分钱代金券\","
    +   "\"start_time\":\"2016-07-11 00:00:00\","  
    +   "\"end_time\":\"2017-08-10 23:59:59\","
    +   "\"type\":\"CONSUME_SEND\","
    +   "\"promo_tools\":[{"
    +     "\"voucher_no\":\"39dfba279ec445ce9ad4e8960ba70540\","
          //voucher_no由支付宝生成，可以通过查询营销活动接口获取
    +     "\"voucher\":{"
    +       "\"type\":\"MONEY\","
    +       "\"name\":\"代金券\","
    +       "\"brand_name\":\"口碑\","
    +       "\"worth_value\":\"0.01\","
    +       "\"validate_type\":\"RELATIVE\","
    +       "\"relative_time\":\"1\","
    +       "\"effect_type\":\"IMMEDIATELY\","
    +       "\"use_rule\":{"
    +         "\"suit_shops\":["
    +           "\"2016052300077000000015587332\""
    +         "]"
    +       "}"
    +     "},"
    +     "\"send_rule\":{"
    +       "\"min_cost\":\"0.01\""
    +     "}"
    +   "}],"
    +   "\"constraint_info\":{"
    +     "\"suit_shops\":["
    +       "\"2016052300077000000015587332\""
    +     "]"
    +   "}"
    + "}";
alipayRequest.setBizContent(bizContent);

KoubeiMarketingCampaignActivityModifyResponse alipayResponse = alipayClient.execute(alipayRequest);
//处理接口返回消息alipayResponse

4. 下架营销活动（koubei.marketing.campaign.activity.offline）

对于需要提前停止的活动，可以通过下架营销活动接口下架活动。

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
KoubeiMarketingCampaignActivityOfflineRequest alipayRequest = new KoubeiMarketingCampaignActivityOfflineRequest();
String bizContent = "{"
    +   "\"out_biz_no\":\"20160715000001\","
    +   "\"camp_id\":\"20160715000000000056518000151415\""
    + "}";
alipayRequest.setBizContent(bizContent);
KoubeiMarketingCampaignActivityOfflineResponse alipayResponse = alipayClient.execute(alipayRequest);
//处理接口返回消息alipayResponse

5. 口碑营销活动列表查询（koubei.marketing.campaign.activity.batchquery）

当开发者需要提供按一定条件批量查询功能时，可以使用口碑营销活动列表查询接口，下面以活动起止时间为例批量查询活动。

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
KoubeiMarketingCampaignActivityBatchqueryRequest alipayRequest = new KoubeiMarketingCampaignActivityBatchqueryRequest();

String bizContent = "{"
    +   "\"query_criterias\":[{"
    +     "\"field_name\":\"startTime\","
    +     "\"field_value\":\"2016-07-10 00:00:00\","
    +     "\"operator\":\"EQUAL\","
    +   "}]"
    + "}";
alipayRequest.setBizContent(bizContent);
KoubeiMarketingCampaignActivityBatchqueryResponse alipayResponse = alipayClient.execute(alipayRequest);
//处理接口返回消息alipayResponse

6. 招商门店分页查询接口（koubei.marketing.campaign.recruit.shop.query）

在活动需要招商的时候，开发者需要提供按照活动编号查询对应参与门店或者适用门店响应结果，可以使用招商门店分页查询接口。

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
KoubeiMarketingCampaignRecruitShopQueryRequest request = new KoubeiMarketingCampaignRecruitShopQueryRequest();
request.setBizContent("{" +
"    \"camp_id\":\"1232433452\"," +
"    \"page_size\":\"100\"," +
"    \"page_num\":\"1\"," +
"    \"invitee\":\"20888\"," +
"    \"operator_id\":\"208843244324\"," +
"    \"operator_type\":\"MER\"" +
"  }");
KoubeiMarketingCampaignRecruitShopQueryResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

接口调用结果码说明

获取接口处理结果代码示例

System.out.println(alipayResponse.getCode()); // 获取接口结果码
System.out.println(alipayResponse.getSubCode()); // 当接口调用失败后，获取子错误码
System.out.println(alipayResponse.getMsg()); // 获取子错误描述
System.out.println(alipayResponse.getBody()); // 获取完整的返回报文

同步返回结果码	含义	说明
10000	业务处理成功
40001～40006	业务处理失败	具体失败原因请参考公共错误码。其它请参考API文档。
20000	业务出现未知错误或者系统异常	业务出现未知错误或者系统异常（请一定要在确定本次调用结果后，再发起重试），可调用查询接口发起查询确定结果。

关于沙箱

如何接入沙箱

沙箱是开放平台提供给开发者用户调试接口的环境，具体操作步骤见沙箱接入指南。

营销活动沙箱接入注意点

1、营销活动支持沙箱接入；在沙箱调通接口后，必须在线上进行测试与验收，所有返回码及业务逻辑以线上为准；

2、可使用门店二维码生成器，通过沙箱钱包的扫一扫功能，进入商家详情页，查看活动效果；

3、沙箱不支持领券、送券和核销动作；

FAQ

关于此文档暂时还没有FAQ

有用(15) 我要提问