开放平台
口碑开店快速接入
更新时间：2017/06/08
访问次数：89249
第一步：创建应用
要在您的应用中使用支付宝开放产品的接口能力，您需要先去蚂蚁金服开放平台（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")
//Windows请填写绝对路径，不支持相对路径；Linux支持相对路径
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、沙箱测试创建门店，推荐使用北京、上海、杭州三个城市在
国家统计局中有的区域进行测试，如遇到区域不存在的情况，请更换区域调试；
