文档中心 > 开放平台

第一步:创建应用

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

第二步:配置密钥

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

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

1.下载服务端SDK

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

2.接口调用配置

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

在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 即创建应用后生成 获取见上面创建应用
FORMAT 参数返回格式,只支持json json(固定)
APP_PRIVATE_KEY 开发者私钥,由开发者自己生成 获取详见上面配置密钥
CHARSET 编码集,支持GBK/UTF-8 开发者根据实际工程编码配置
ALIPAY_PUBLIC_KEY 支付宝公钥,由支付宝生成 获取详见上面配置密钥
SIGN_TYPE 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 RSA2

3.第三方应用授权

开店接口是为开发者快速帮商家创建线上门店,门店实际归属为商家,所以开发者在帮助商家创建门店前需要得到商家的授权。商家授权后会返回给开发者一个code,通过code获取app_auth_token,每次帮商家调用接口时都需要传入app_auth_token使用方式请参考第三方应用授权

第四步:接口调用示例

接口列表:创建门店信息(alipay.offline.market.shop.create)

接口交互流程图:

2:接口SDK代码调用示例

接口列表:上传门店照片接口(alipay.offline.material.image.upload)

//实例请求对象
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); 
//初始化请求对象实例
    AlipayOfflineMaterialImageUploadRequest request = new AlipayOfflineMaterialImageUploadRequest();
//AppAuthToken的值获取方式参考第三方应用授权
    request.putOtherTextParam("app_auth_token", AppAuthToken);
//图片格式
    request.setImageType(imgType);
//图片名称
    request.setImageName(imgName);
//图片二进制内容获取方式示例:imgContent = new FileItem("C:/Downloads/ooop6069/测试图片.jpg")
    request.setImageContent(imgContent);         
//初始化返回对象实例并获取返回信息
     AlipayOfflineMaterialImageUploadResponse response = alipayClient.execute(request);      
//输出返回信息,开发者自行处理,此处打印实例为方便调试查看
    System.out.print(response.getBody());

接口列表:创建门店信息接口(alipay.offline.market.shop.create)

//实例请求对象
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); 
//初始化请求对象实例
AlipayOfflineMarketShopCreateRequest request = new AlipayOfflineMarketShopCreateRequest();
//AppAuthToken的值获取方式参考第三方应用授权
request.putOtherTextParam("app_auth_token", AppAuthToken);
//配置创建门店所需的业务参数
request.setBizContent(bizContent);
//初始化返回对象实例并获取返回信息
AlipayOfflineMarketShopCreateResponse response = alipayClient.execute(request);
//输出返回信息,开发者自行处理,此处打印实例为方便调试查看
System.out.print(response.getBody());

bizContent中内容示例:

bizContent="{\"address\":\"卓越路加州城\"," +
 "\"audit_images\":\"fTwPcLSxSa2VdNag2PqeKQAAACMAAQEC,hW4ZKOmpTmWALRI0uz1soQAAACMAAQEC,bGG2pMF-SAGY444rjAEVigAAACMAAQEC\"," +
 "\"category_id\":\"2015050700000010\"," +
"\"biz_version\":\"2.0\","+
"\"operate_notify_url\":\"https://www.example.com\","+ "\"city_code\":\"330100\"," + "\"contact_number\":\"057126788889,18666668880\"," + "\"district_code\":\"320115\"," + "\"is_operating_online\":\"T\"," + "\"isv_uid\":\"2088902135432847\"," + "\"latitude\":\"30.27315218\"," + "\"longitude\":\"120.12476921\"," + "\"main_image\":\"AM-uJRh2SRKz9N0r9zW4wQAAACMAAQEC\"," + "\"main_shop_name\":\"测试示例\"," + "\"online_image\":\"AM-uJRh2SRKz9N0r9zW4wQAAACMAAQEC\"," + "\"province_code\":\"330000\"," + "\"store_id\":\"1866700000630777\"}";

>>以上内容中的参数值均为示例,请开发者根据实际情况配置,参数说明请参考创建门店信息API

>>创建请求提交后,会有个审核过程,审核时间一个工作日。

>>为一次提交能审核通过,请到“参数展示说明及注意事项”中查看相关注意事项。

>>operate_notify_url 门店审核状态会通过此参数值通知给开发者,具体通知内容可点此了解

>>当支付宝或商家修改了开发者创建的门店,修改信息会通过应用网关通知给开发者,通知内容点此了解

TIPS: 商家可在未签约/已签约当面付产品的情况给开发者授权,由开发者帮助商家创建门店。

           开发者只是发起方,开发者代商家做任何操作都需要传入商家授权的token。

           如门店需要做支付,收款方也须为商家,不允许开发者收款再分给商家的形式。

>>门店创建接口中的“category_id”参数,开发者可在口碑开店商家准入条件-口碑类目非口碑类目表格中获取和下载,也可以通过门店类目配置查询接口获取(鉴于此id会跟随业务变动,推荐使用接口方法动态获取)。

接口列表:门店类目配置查询接口(alipay.offline.market.shop.category.query)

//实例请求对象
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
//初始化请求对象实例
AlipayOfflineMarketShopCategoryQueryRequest request = new AlipayOfflineMarketShopCategoryQueryRequest();
//配置创建门店所需的业务参数
request.setBizContent("{" +
"    \"category_id\":\"2015050700000000\"," +
"    \"op_role\":\"ISV\"" +
"  }");
//初始化返回对象实例并获取返回信息
AlipayOfflineMarketShopCategoryQueryResponse response = alipayClient.execute(request);
//输出返回信息,开发者自行处理,此处打印实例为方便调试查看
System.out.print(response.getBody());

接口列表:修改门店信息接口(alipay.offline.market.shop.modify)

接口交互流程:

SDK调用示例:

//实例请求对象
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); 
//初始化请求对象实例 
AlipayOfflineMarketShopModifyRequest request = new AlipayOfflineMarketShopModifyRequest();
//AppAuthToken的值获取方式参考第三方应用授权
request.putOtherTextParam("app_auth_token", AppAuthToken);
//修改哪个参数传入哪个参数,不用修改则不用传递,示例:{\"shop_id\":\"2015052100077000000000120773\",\"brand_name\":\"test2\"}
request.setBizContent(bizContent);
//初始化返回对象实例并获取返回参数
AlipayOfflineMarketShopModifyResponse response = alipayClient.execute(request);
//输出返回信息,开发者自行处理,此处打印实例为方便调试查看
System.out.print(response.getBody());
TIPS1:修改的参数为门店名、品牌名、品牌logo、首图、门店图片、营业执照、营业执照编号、营业执照名称、经营许可证、经营许可证有效期、门店授权函、是否在其它平台开店、在其它平台开店照片,会重新触发门店审核,开发者用operate_notify_url的值进行接收,通知返回详见门店审核状态通知
TIPS2:如开发者需要将门店信息修改为空,可将该参数的参数值配置为“#EMPTY#”如:"avg_price":"#EMPTY#"表示将平均消费设置为空。目前门店接口支持将参数值设置为空的参数见下表格,其他参数暂不支持。
参数名 参数说明
notify_mobile 门店店长电话号码
implement_id 机具号
branch_shop_name 分店名称
value_added 门店其他服务
avg_price 人均消费价格

接口列表:查询单个门店信息(alipay.offline.market.shop.querydetail)

sdk调用示例:

 本接口为查询接口,开发者请求,支付宝同步返回查询结果。

//实例请求对象
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); 
//初始化请求对象实例 
AlipayOfflineMarketShopQuerydetailRequest request = new AlipayOfflineMarketShopQuerydetailRequest();
//AppAuthToken的值获取方式参考第三方应用授权    
request.putOtherTextParam("app_auth_token", appAuthToken);
//bizContent参数示例{\"shop_id\":\"2015052100077000000000120773\",\"op_role\":\"MERCHANT或PROVIDER\"}
request.setBizContent(bizContent); 
//初始化返回对象实例并获取返回信息
AlipayOfflineMarketShopQuerydetailResponse response = alipayClient.execute(request);
//输出返回信息,开发者自行处理,此处打印实例为方便调试查看
System.out.print(response.getBody());

接口列表:查询商户的门店编号列表(alipay.offline.market.shop.batchquery)

sdk调用示例:

//实例请求对象
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); 
//初始化请求对象实例     
AlipayOfflineMarketShopBatchqueryRequest request = new AlipayOfflineMarketShopBatchqueryRequest();
//AppAuthToken的值获取方式参考第三方应用授权    
request.putOtherTextParam("app_auth_token", appAuthToken);
//bizContent示例值:{\"page_no\":\"1\"}
request.setBizContent(bizContent);
//初始化返回对象实例并获取返回信息
AlipayOfflineMarketShopBatchqueryResponse  response = alipayClient.execute(request);
//输出返回信息,开发者自行处理,此处打印实例为方便调试查看
System.out.print(response.getBody());

接口列表:门店摘要信息批量查询(alipay.offline.market.shop.summary.batchquery)

SDK调用示例:

//实例请求对象
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); 
//初始化请求对象实例
AlipayOfflineMarketShopSummaryBatchqueryRequest request = new AlipayOfflineMarketShopSummaryBatchqueryRequest();
//AppAuthToken的值获取方式参考第三方应用授权     
request.putOtherTextParam("app_auth_token", appAuthToken);
//bizContent示例:{\"op_role\":\"ISV\",\"query_type\":\"BRAND_RELATION\"} 
request.setBizContent(bizContent);
//初始化返回对象实例并获取返回信息
AlipayOfflineMarketShopSummaryBatchqueryResponse  response = alipayClient.execute(request);
//输出返回信息,开发者自行处理,此处打印实例为方便调试查看
System.out.print(response.getBody());

接口列表:业务流水批量查询接口(alipay.offline.market.applyorder.batchquery)

//实例请求对象
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); 
//初始化请求对象实例
AlipayOfflineMarketApplyorderBatchqueryRequest request = new AlipayOfflineMarketApplyorderBatchqueryRequest();
//bizContent示例值
request.setBizContent("{\"biz_type\":\"SHOP\"}");
//初始化返回对象并获取参数
AlipayOfflineMarketApplyorderBatchqueryResponse response = alipayClient.execute(request); 
//输出返回信息,开发者自行处理,此处打印实例为方便调试查看
System.out.print(response.getBody()); 

参数展示说明及注意点

品牌

     通过输入品牌名,可以搜索到相关品牌;

     如果搜索不到匹配的品牌,则自动归类为“其它品牌”。

品牌Logo

     品牌Logo的尺寸建议为500px*500px

     相同品牌的门店可以上传同一张品牌Logo图片

      品牌Logo在支付宝钱包客户端的“支付宝”Tab中的卡券中有露出,入口及效果详见下图:

门店名称

       门店名称分为两部分,主店名及分店名,主店名如“海底捞”,分店名如“万塘路店”。对于只有一个门店的商户而言,可以不填写分店名。

       门店名称在支付宝钱包客户端的“口碑”Tab里有多处展现,是一个非常重要的字段,请务必确保填写正确,如下图所示:

门店地址

     含经纬度,高德坐标,经纬度需要开发者帮助商户校准

电话

     该字段在支付宝客户端的“口碑”Tab中的商家详情有所展现,用户点击该按钮后可以拨通电话,如下图所示:

手机号

     内部管理员手机号,不在客户端展示。

品类

    即当前门店属于什么类别,对应创建门店中类目(category_id)

在支付宝客户端“商家”Tab中,品类的“二级类目”将作为一个搜索过滤条件供用户选择,商户在后台为门店选择的品类,如下图所示:

门店首图

     门店首图是至关重要的一张图片,在钱包客户端有大量的展现,可首选优质菜品图、优质门店图作为首图,建议尺寸2000px*1500px,首图会在手机支付宝中重点展示;

     封面照片在支付宝钱包端展现如下:

门店照片

     至少选择三张照片(门头照片及内景照片),建议图片分辨率2000px*1500px及以上,更容易通过审核;

     丽人行业用于审核的图片会展示在商家相册的“环境”相册中。

收款账号

     开发者不能设置商户门店的收款账号,收款账号默认为签约的支付宝账号。

门店编号

      门店编号指该门店在开发者系统中的门店编号,在收单请求中传入该参数用于查询支付宝端对应的门店;

      对于收银系统直接打通的商户,填写门店编号,门店编号支持中文、英文以及其他符号。

营业时间

     选填,支持多个时间段,或者24小时。

提供服务

     选填,支持多选,需要按照商户的实际情况填写。

更多服务

     选填,支持换行,需要按照商户的实际情况填写。

人均价格

     选填,商户填写的人均消费价格,需要尽量准确,只支持整数,最大不超过99999。

接口调用结果码说明

同步返回结果码 含义 说明

10000

业务处理成功  
40001~40006 业务处理失败 具体失败原因请参考公共错误码。其它请参考API文档。
20000 业务出现未知错误或者系统异常 业务出现未知错误或者系统异常(请一定要在确定本次调用结果后,再发起重试),可调用查询接口发起查询确定结果。

关于沙箱

如何接入沙箱

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

口碑开店沙箱接入注意点

      1、口碑开店支持沙箱接入;在沙箱调通接口后,必须在线上进行测试与验收,所有返回码及业务逻辑以线上为准;
      2、业务流水批量查询接口(alipay.offline.market.applyorder.batchquery),请求时带上apply_ids参数;
      3、可使用沙箱环境- 沙箱工具-口碑门店账号&二维码转换工具,通过沙箱钱包的扫一扫功能,进入商家详情页,查看门店效果;
      4、沙箱测试创建门店,推荐使用北京、上海、杭州三个城市在 国家统计局中有的区域进行测试,如遇到区域不存在的情况,请更换区域调试;

FAQ

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