会员集点快速接入

更新时间：2017/05/22 访问次数：28994

第一步：创建应用并获取APPID
第二步：配置密钥
第三步：搭建和配置开发环境
第四步：接口调用
第五步：创建服务

第一步：创建应用并获取APPID

要在您的应用中使用支付宝开放产品的接口能力，您需要先去蚂蚁金服开放平台（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调用前需要进行初始化，代码如下：

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

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

第四步：接口调用

接口调用流程

会员集点主要分成：交易集点和集点兑换活动创建、用户集点累加、集点兑换优惠券三部分构成。

1. 交易集点&集点兑换活动创建与管理

2. 交易集点

系统商根据支付宝收单的交易信息进行集点计算，并调用集点接口修改用户账户中的集点数。

3. 集点兑换

用户使用集点兑换优惠券，开发者预先冻结对应集点，同时调用发券授权接口换取Token，然后使用Token拼接口碑领券页供用户访问。用户领券成功后口碑通知开发者，开发者调用更新卡集点接口扣除用户已冻结的集点。

调用更新卡集点接口(koubei.marketing.tool.points.update)时，trans_type选择consume即为直接扣减集点；选择freeze为预先冻结集点使用户暂时不可使用，用户领券后口碑向商户发放领券成功通知，商户接到通知后再调用该接口，trans_type选择commit即可扣除冻结的集点。

H5领券页链接示例：

https://render.alipay.com/p/z/pointset/index.html?itemId=2016091820076000000005569798&token=5b78189e931a415f8c9b9df248a597a9&outBizNo=20160918182411699345&buyerId=2088202920045392&shopId=2016090900077000000003410021&type=pointcard

其中参数释义：

参数	释义
itemId	活动查询接口查询发放渠道为URL_WITH_TOKEN的活动时，响应参数publish_channels-config中含有领券页地址，该地址中自带item_id
token	用户领券令牌，详见发券授权接口(koubei.marketing.tool.prizesend.auth)
outBizNo	外部交易流水号
buyerId	用户UserId（非必填）
shopId	该优惠券适用的附近距离最近的商家口碑店铺ID（非必填）
type	领券页类型pointcard（必填）

请开发者依照当前页面访问用户实际情况拼接参数生成最终链接。

TIPS：用户在口碑领券页领券成功后，口碑将会向开发者创建活动时录入的notify_url发送发券成功异步通知。为避免用户在数据不同步时重复领券，建议开发者在接收到成功通知前暂时冻结集点，接到发券成功通知后再行扣除；若超过1小时未接到发券成功通知，则视为发券失败，口碑会作废领券Token令牌，开发者可解冻用户对应冻结的集点。

使用SDK快速接入

1. 活动创建接口(koubei.marketing.campaign.activity.create)

JAVA请求源码示例：

/**
 * 创建营销活动
 * @param appAuthToken如ISV代替商家调用接口，需将商户授权后获取的app_auth_token带上；如商家自己调用，则传null。
 * @param bizContent 因该接口业务参数复杂，请详见接口文档
 * @return
 * @throws AlipayApiException 请处理异常
 */
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
KoubeiMarketingCampaignActivityCreateRequest request = new KoubeiMarketingCampaignActivityCreateRequest();
request.putOtherTextParam("app_auth_token", appAuthToken);
request.setBizContent(bizContent); //详见"交易集点活动示例请求报文"和"集点兑换活动示例请求报文"
request.setNotifyUrl(notifyUrl);    //外部商户通知地址，用于接收与活动相关支付成功通知和发券成功通知
if(response.isSuccess()){
  System.out.println("调用成功");
} else {
  System.out.println("调用失败");
}

交易集点活动请求报文示例：

{
    "biz_content":{
      "out_biz_no":"adfasasdfexfesadsaxxd",
      "name":"集点活动测试-yuchi",
      "start_time":"2016-08-02 00:00:00",
      "end_time":"2016-09-31 00:00:00",
      "type":"POINT_SEND",
      "desc":"集点活动测试",
      "constraint_info":{
          "suit_shops":["2015121600077000000002388200"]
      },
      "promo_tools":[{
          "point_card":{
                    "name":"集点卡-yuchi",
                    "desc":"活动规则简述（16字）",
                    "start_time":"2016-08-01 00:00:00",
                    "end_time":"2016-12-01 00:00:00",
                    "logo":"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC"
                }
      }]
    }
}

集点兑换活动请求报文示例：

{
    "biz_content":{
        "out_biz_no":"hhe12312312312312348",
        "budget_info":{
            "budget_total":"10453",
            "budget_type":"QUANTITY"
        },
        "constraint_info":{
            "suit_shops":[
                "2015122900077000000002409504"
            ]
        },
        "start_time":"2016-08-01 00:00:00",
        "end_time":"2016-09-30 00:00:00",
        "name":"全场代金+不含人群",
        "type":"DIRECT_SEND",
        "desc":"test",
        "promo_tools":[
            {
                "voucher":{
                    "brand_name":"8个集点兑换",
                    "desc":"券的详细描述",
                    "effect_type":"IMMEDIATELY",
                    "start_time":"2016-05-01 00:00:00",
                    "end_time":"2016-10-01 00:00:00",
                    "logo":"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC",
                    "max_amount":"20",
                    "name":"全场代金券",
                    "start_time":"2016-05-01 00:00:00",
                    "type":"MONEY",
                    "use_rule":{
                        "min_consume":"10",
                        "suit_shops":[
                            "2015122900077000000002409504"
                        ]
                    },
                    "validate_type":"FIXED",
                    "voucher_img":"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC",
                    "worth_value":"20"
                },
                "send_rule":{
                   "allow_repeat_send":"true"
                }
            }
        ],       
        "publish_channels":[
            {
                "name":"URL_WITH_TOKEN",
                "type":"URL_WITH_TOKEN"
            }
        ]
    }
}

发券成功通知示例：

http://[ISV_NOTIFY_URL]?buyer_id=2088202920045392&merchant_uid=2088201914979011&notify_time=2016-09-19 22:35:10&isv_out_biz_id=hhe-test1-210600000101537&sign_type=RSA2&charset=UTF-8&auth_app_id=2016090501238677&notify_type=koubei_receive_coupon_notify&business_order=2088202920045392|20160917000000000862132000151011&version=1.0&sign=gbfFwWC82iHPK82gE2hJz/ZhzLFnBpVXud5aBxZDbSmW+vVCIhazBNlti3M2ZSYzQYGGY5S1CRe1iym37sbPY/DpS5yVLB+L443PgKU9su7QLFyPRQINbsRoRb5QMgSJrdepgoHhdiZ/tZpqMrRsJcOAMS4lcxo8fGCsxZaB9+A=&event_code=EC-promocore-prize-notice&app_id=2016090501239018&notify_id=79d7029ea9e41120614dfb33bb4d7e9gum

字段名	字段描述	示例	说明
id	集点卡活动ID	20160924000000000194482000151966	口碑的活动ID
auth_app_id	开放平台权限ID	2014010400002530
event_code	事件类型	EC-promocore-prize-notice
isv_out_biz_id	外部流水号	20160918182411699345	ISV跳转领券页时传入
buyer_id	发券用户ID	2088212047701226
merchant_uid	发券商户ID	2088111867109963
notify_id	通知消息ID	c0201fb4218d38eb29758190b3e8dfcmhe	支付宝mnotify消息ID
business_order	业务单号		由通知发送方自定义，用于问题定位，消息接收方原样返回

2. 更新卡集点接口(koubei.marketing.tool.points.update)

JAVA请求源码示例：

/**
 * 集点更新接口
 * @param appAuthToken如ISV代替商家调用接口，需将商家授权后获取的app_auth_token带上；如商家自己调用，则传null。
 * @param bizContent 因该接口业务参数复杂，请详见接口文档
 * @return
 * @throws AlipayApiException 请处理异常
 */
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do",APP_ID,APP_PRIVATE_KEY,
  "json","GBK",ALIPAY_PUBLIC_KEY);
KoubeiMarketingToolPointsUpdateRequest request = new KoubeiMarketingToolPointsUpdateRequest();
request.setBizContent("{" +
"    \"req_id\":\"778712860805461247257\"," +
"    \"user_id\":\"2088123412341234\"," +
"    \"activity_account\":\"39201608190015500100016011040139\"," +
"    \"trans_type\":\"DEPOSIT\"," +
"    \"trans_amount\":\"10\"," +
"    \"shop_id\":\"2016041200077000000003277104\"," +
"    \"biz_no\":\"2016082221001004150200139999\"," +
"    \"memo\":\"积分扣减用于兑换奖品\"," +
"    \"ext_info\":\"{'EXTRA_INFO_KEY':'SAMPLE_VALUE'}\"" +
"  }");
KoubeiMarketingToolPointsUpdateResponse response = alipayClient.execute(request);
if(response.isSuccess()){
  System.out.println("调用成功");
} else {
  System.out.println("调用失败");
}

3. 集点查询接口(koubei.marketing.tool.points.query)

JAVA请求源码示例：

/**
 * 集点查询接口
 * @param appAuthToken如ISV代替商家调用接口，需将商家授权后获取的app_auth_token带上；如商家自己调用，则传null。
 * @param bizContent 因该接口业务参数复杂，请详见接口文档
 * @return
 * @throws AlipayApiException 请处理异常
 */
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do",APP_ID,APP_PRIVATE_KEY,"json","GBK",ALIPAY_PUBLIC_KEY);
KoubeiMarketingToolPointsQueryRequest request = new KoubeiMarketingToolPointsQueryRequest();
request.setBizContent("{" +
"    \"activity_account\":\"39201608190015500100016011040139\"," +
"    \"user_id\":\"2088123412341234\"" +
"  }");
KoubeiMarketingToolPointsQueryResponse response = alipayClient.execute(request);
if(response.isSuccess()){
  System.out.println("调用成功");
} else {
  System.out.println("调用失败");
}

4. 发券授权接口(koubei.marketing.tool.prizesend.auth)

JAVA请求源码示例：

/**
 * 发券授权接口
 * @param appAuthToken如ISV代替商家调用接口，需将商家授权后获取的app_auth_token带上；如商家自己调用，则传null。
 * @param bizContent 因该接口业务参数复杂，请详见接口文档
 * @return
 * @throws AlipayApiException 请处理异常
 */
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do",APP_ID,APP_PRIVATE_KEY,"json","GBK",ALIPAY_PUBLIC_KEY);
KoubeiMarketingToolPrizesendAuthRequest request = new KoubeiMarketingToolPrizesendAuthRequest();
request.setBizContent("{" +
"    \"req_id\":\"43242389432475452321\"," +
"    \"prize_id\":\"20160527000000000682853000153366\"," +
"    \"user_id\":\"2088123412341234\"" +
"  }");
KoubeiMarketingToolPrizesendAuthResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

TIPS：活动查询接口查询发放渠道为URL_WITH_TOKEN的活动时，响应参数publish_channels-config中的领券页地址中的item_id，即为该接口请求参数中需要填写的prize_id。

第五步：创建服务

服务创建请参考“服务创建及发布流程”。

注意：应用类型请选择“会员集点”。

服务订购请参考“商家订购服务流程”。

TIPS：支付宝客户端会在进行集点活动的门店支付成功页，投放集点提示广告。用户点击广告后会进入集点详情页。因此，请在集点服务的用户访问地址和商家移动端访问地址中，填写集点详情页URL，且该URL必须为https链接协议。
集点详情页由于需要展示该用户在当前门店的对应集点，与当前门店的对应活动。建议开发者利用OAuth2.0授权，scope选择auth_base，在不干扰用户的情况下自动获取用户UserId，同时利用UserId查询最近一笔有集点交易的ShopId和对应商户PID，以便进行数据渲染。

FAQ

关于此文档暂时还没有FAQ

有用(11) 我要提问