文档中心 > 开放平台

第一步:创建应用并获取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,即为该接口请求参数中需要填写的price_id。

第五步:创建服务

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

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

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

 

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

FAQ

关于此文档暂时还没有FAQ
返回
顶部