文档中心 > 开放平台

开放平台

口碑码战略快速接入

更新时间：2017/08/18 访问次数：26803

第一步：创建应用并获取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并引入您的开发工程。

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

接下来，就可以用alipayClient来调用具体的API了。alipayClient只需要初始化一次，后续调用不同的API都可以使用同一个alipayClient对象。

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

第四步：接口调用流程

4.1 桌码识别与异常信息回流

用户在扫描支付宝桌码,并进入扫码点菜服务时，跳转客户端时，除带上shop_id和merchant_id外，还会带上桌码，ISV需要识别桌码信息，并进入扫码点菜流程

   http://zzcdtc.oicp.net:25345/index.php/dishorder /company?shop_id=2016041800077000000015345841&merchant_pid=2088802532857530&table_num=A2

ISV需要识别桌码信息，并跳转正确的点菜页面。

异常处理：当ISV无法识别口碑传递的桌码信息而无法提供点菜服务时，需要回传异常信息（信息包括门店ID，商家ID，口碑传递的桌码，发生时间，用户ID等）

API接口：alipay.offline.market.reporterror.create   上报线下服务异常

JAVA请求示例

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayOfflineMarketReporterrorCreateRequest request = new AlipayOfflineMarketReporterrorCreateRequest();
request.setBizContent("{" +
"\"shop_id\":\"2016060700077000000003551285\"," +
"\"merchant_id\":\"2088502948051150\"," +
"\"user_id\":\"2088502948051150\"," +
"\"err_time\":812324234243," +
"\"type\":\"tableNum\"," +
"\"feature\":{" +
"\"table_num\":\"A01\"" +
"    }" +
"  }");
AlipayOfflineMarketReporterrorCreateResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败"); 

json响应示例

{
"alipay_offline_market_reporterror_create_response":{
    "code":"10000",
    "msg":"Success"
  }
,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

4.2 信息回流

口碑ISV通过店铺数据产品回流信息，涉及店铺数据回传（店铺信息，桌位信息等）与用户数据回传（点菜订单，排队订单，预订订单等）两个接口。

店铺维度数据回流：alipay.offline.provider.shopaction.record

用户维度数据回流：alipay.offline.provider.useraction.record

口碑码需要ISV回传信息包括桌位信息，菜品信息，用户菜品订单信息

4.2.1 桌位信息回传

接口名称：alipay.offline.provider.shopaction.record

接口描述：商户行为信息，传入商户的所有行为，全部使用JSON表达

ISV回传桌位信息，服务商即可在口碑城市服务商中台直接申请已经绑定桌码的物料，简化服务商实施流程。

更多商户行为请查看店铺行为数据文档

桌位涉及三种行为：插入桌位行为、修改桌位行为、每天全量更新一次桌位数据。

（1）插入桌位信息

1、使用说明

  • 合作商首次需要进行全量插入数据，请使用for_each方式进行调用。
  • 增量需要合作商每次新增餐桌的时候调用。
  • 多次调用插入同一个餐桌，后续插入会执行更新。

2、action_type：insert_table

3、entity：shop

4、action_detail说明

参数名称 参数类型 是否必填 描述
tableId String 是 座位ID，后面通过他更新
max Integer 是 最大容量
min Integer 是 最小容量
tableName String 是 餐桌名称（比如：神龙包厢）如果没有名称可以使直接传入tableNum的值
tableNum String 否 桌位编号（比如：A01）
tableType String 是 餐桌类型（0：普通桌 1：包厢）
status Integer 是 0：空闲；1：占用；2：不可知；-1：删除
默认空闲

（2）修改桌位信息

1、使用说明

  • 在座位变更的时候，比如开桌、名字变更
  • 不传入不更新，如果为null或者该字段没有更新，不用传入当前key

2、action_type：update_table

3、entity：shop

4、action_detail说明

参数名称 参数类型 必填 描述
tableId String 是 座位ID，后面通过他更新
max Integer 否 最大容量
min Integer 否 最小容量
tableName String 否 餐桌名称（比如：神龙包厢）如果没有名称可以使直接传入tableNum的值
tableNum String 否 桌位编号（比如：A01）
tableType String 否 餐桌类型（0：普通桌 1：包厢）
status Integer 否 0：空闲；1：占用；2：不可知；-1：删除
默认空闲

(3)批量更新一个店铺的桌位信息

1、使用说明

  • ISV需要每天全量更新一次桌位数据，每次传入一个店铺的所有座位。
  • 口碑会在一个事务中先删除当前店铺所有数据，然后再次查询所有数据，所以需要保证一次传入给口碑是单个店铺的全部数据。
  • 白天的更新，需要配合update_table、insert_table进行实时传输。

2、action_type：insert_one_shop_all_table

3、entity：shop

4、action_detail说明（json的list结构数据）

参数名称 参数类型 是否必填 描述
tableId String 是 座位ID，后面通过他更新
max Integer 是 最大容量 
min Integer 是 最小容量
tableName String 是 餐桌名称（比如：神龙包厢）如果没有名称可以使直接传入tableNum的值
tableNum String 否 桌位编号（比如：A01）
tableType String 是 餐桌类型（0：普通桌 1：包厢）
status Integer 是 0：空闲； 1：占用；2：不可知；-1：删除
默认空闲

Java请求示例

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayOfflineProviderShopactionRecordRequest request = new AlipayOfflineProviderShopactionRecordRequest();
request.setBizContent("{" +
"\"action_type\":\"insert_table\"," +
"\"entity\":\"shop\"," +
"\"date_time\":\"2016-04-12 11:30:56\"," +
"\"outer_shop_do\":{" +
"\"shop_id\":\"2016062900077000000016003316\"," +
"\"outer_id\":\"2323445656fe234abc33\"," +
"\"type\":\"_2dFire\"" +
"    }," +
"\"action_detail\":\"{\\\"tableId\\\": \\\"20\\\",\\\"max\\\": 8, \\\"min\\\": 2, \\\"table_name\\\": \\\"生楼阁\\\",\\\"tableNum\\\":\\\"A01\\\"}\"," +
"\"industry\":\"REPAST\"," +
"\"action_outer_id\":\"aab66\"" +
"  }");
AlipayOfflineProviderShopactionRecordResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

JSON响应示例

{
"alipay_offline_provider_shopaction_record_response":{
    "code":"10000",
    "msg":"Success"
  }
,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

4.2.2 菜品信息回传

详细参考店铺行为数据文档：店铺菜品

4.2.3 用户点菜信息回流

接口名称：alipay.offline.provider.useraction.record

接口描述：用户行为信息，传入用户的所有行为，全部使用JSON表达

更多关于用户行为信息参数请查看用户行为数据文档

1、使用说明

用户点菜后，每个状态都上传全量的用户的菜品订单信息。（需要实时回传确保服务卡片展示）

用户下单、服务员确认、取消订单、结账都全量上传菜品信息

detailUrl使用说明：传入的URL必须与开放平台后台，应用APPID配置的授权URL的域名相同，保证后续网页授权可以跳转过去。例如：上传的detailUrl=http://XXXXX.com?orderId=1234 会在当前URL上面追加上&openAppId=X&shopId=口碑店铺ID&bizScenario=XX。网页授权成功后跳转到ISV平台，URL会是：http://XXXXX.com?orderId=1234&openAppId=X&shopId=口碑店铺ID&bizScenario=XX&app_id=XXX&source=alipay_wallet&scope=auth_base&auth_code=ca34ea491e7146cc87d25fca24c4cD11 ，后面ISV就可以做自己的业务逻辑，比如解析orderId、auth_token参数 。然后ISV通过接口alipay.system.oauth.token根据auth_code查询支付宝会员信息。详见网页授权文档。

source说明：从第三方平台进入开发者应用，后产生的数据，传入第三方平台域名，比如当前数据是支付宝扫码后产生，传入支付宝域名alipay.com，是在微信打开后产生的数据，传入微信域名weixin.qq.com，如果数据不是从第三方平台进入后产生的数据，设置自己的域名即可，字段内容不做强制校验。

2、action_type：order_dishes

3、entity：user

4、action_detail说明

参数名称 参数类型 必填 描述
totalPrice Long 是 总价（单位分）
discountPrice Long 是 优惠金额（单位分）
realPrice Long 是 实际支付金额（单位分）
source String 是 菜单来源 、参考上面说明
status String 是 11 用户下单、等待商家确认
12 商家已经确认
13 商家确认，等待支付
14 支付完成，结账成功
15 点菜关闭 
payTime Long 否 支付时间
channel String 否 支付来源渠道推荐使用值：alipay(支付宝支付) 、weixin(微信支付)、other(其他支付渠道)。如果是支付宝支付传入alipay，如果是微信传入：weixin  其他的支付都传入：other
payOrderNo String 否 交易流水号，在创建支付宝交易的时候，会拿到一个流水号，一般是以当前年开始，比如：2017XXXXX，如果是支付宝订单请传入，如果不是请不要设置。
outOrderId String 是 外部订单号
tableCode String 是 座位号如果有推荐填写
people  Integer 否 消费人数
description String 否 备注(长度500)
detailUrl String 跳转详情URL 跳转的原始URL
dish JSONArray 是 菜品列表
  1. *String goodsId 菜品ID
  2. String skuId 规格ID
  3. *String goodsName 菜品名称
  4. *long price 价格
  5. *int num 点菜数量
hasClosed int 否

代表是否清桌
1：清桌，代表桌位可以被他人使用
0：占用，代表桌位正在被人使用（比如点菜中、订单没有完结，都认为是占用中，其他人员无法再次下单）
默认0
按照isv实际场景设置
statusDesc String 是 状态的文案说明，上面的status只是描述了主要状态，如果ISV有特殊的状态文案描述，直接传入
actionUrlList JSONArray 否

口碑会在店铺页面显示类似的服务卡片：

行动点对象列表，每次更新全量覆盖，字段key说明如下

String  name   行动名称（比如，买单、加菜）
String actionUrl  跳转URL
String type URL  类型（官方常量  addDish（加菜） pay （去买单），官方会根据类型做业务逻辑，如果不在官方说明，请设置为空）
realtionUserList JSONArray 否

与当前订单有关系的用户，传入json数组，如果不是支付宝用户不需要传入，如果source是alipay，一定要传入。

对象字段key如下：

String userId （支付宝用户ID）

String type （用户ID行为类型）

type各取值说明：

 pay：支付者

 pushOrder：推送订单到厨房的用户

 normal：普通用户，没有做特殊说明的都是普通用户
TIPS：请按照规范回流用户点菜数据!

JAVA请求示例

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayOfflineProviderUseractionRecordRequest request = new AlipayOfflineProviderUseractionRecordRequest();
request.setBizContent("{" +
"\"platform_user_id\":\"2014323100009\"," +
"\"source\":\"koubei.com\"," +
"\"action_type\":\"order_dishes\"," +
"\"mobile\":\"15657153919\"," +
"\"industry\":\"REPAST\"," +
"\"order_type\":\"online_pay\"," +
"\"user_id\":\"2088502948051150\"," +
"\"date_time\":\"2015-12-03 12:34:23\"," +
"\"alipay_app_id\":\"dish-order-app-plug\"," +
"\"action_detail\":\"{\\\"outer_dish_id\\\":\\\"20\\\",\\\"name\\\":\\\"红烧猪蹄\\\",\\\"price\\\":4500,\\\"quantity\\\":222}\"," +
"\"outer_shop_do\":{" +
"\"shop_id\":\"2016062900077000000016003316\"," +
"\"outer_id\":\"2323445656fe234abc33\"," +
"\"type\":\"_2dFire\"" +
"    }," +
"\"entity\":\"user\"," +
"\"action_outer_id\":\"gade3331b\"," +
"\"order_channel\":\"isv\"" +
"  }");
AlipayOfflineProviderUseractionRecordResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

JSON响应示例

{
"alipay_offline_provider_useraction_record_response":{
    "code":"10000",
    "msg":"Success"
  }
,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

4.3 口碑订单预咨询接口

用户在进入ISV码上付订单页面后，由ISV调用口碑订单预咨询接口获取当前用户（UID），根据用户当前订单信息获取当前用户当前订单下可以享受的优惠信息。

交互UI示例：

API接口：koubei.trade.order.consult （口碑订单预咨询）

JAVA请求示例

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
KoubeiTradeOrderConsultRequest request = new KoubeiTradeOrderConsultRequest();
request.setBizContent("{" +
"\"request_id\":\"0ad1e47b1500473065347103327127\"," +
"\"user_id\":\"2088212151390950\"," +
"\"total_amount\":88.88," +
"\"undiscountable_amount\":10.00," +
"\"shop_id\":\"2015051100077000000000000300\"," +
"      \"goods_info\":[{" +
"        \"goods_id\":\"apple-01\"," +
"\"goods_name\":\"苹果手机\"," +
"\"goods_category\":\"201701000\"," +
"\"quantity\":\"2\"," +
"\"price\":10.00" +
"        }]" +
"  }");
KoubeiTradeOrderConsultResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

json响应示例

{
"koubei_trade_order_consult_response":{
    "code":"10000",
    "msg":"Success",
"buyer_pay_amount":10.00,
"request_id":"874JKK4H5J43H3K35J4543K5J3K45J34KJ",
"m_card_detail":{
"name":"商家储值卡",
"available_amount":100000.00,
"pay_amount":1000.00
    },
      "discount_detail":[{
        "id":"2017CVCJD788E889EC",
          "discount_desc":[
            "最高优惠10元；储值卡专属"
          ],
"discount_type":"RT_DISCOUNT",
"is_hit":"true",
"is_purchased":"true",
"name":"5折优惠",
"discount_amount":100.00
        }]
  }
,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
} 

FAQ

关于此文档暂时还没有FAQ
有用(8) 我要提问
返回
顶部
阿里巴巴集团 | 淘宝网 | 天猫 | 聚划算 | 全球速卖通 | 阿里巴巴国际交易市场 | 1688 | 阿里妈妈 | 阿里旅行·去啊 | 阿里云计算 | YunOS | 阿里通信 | 万网 | 高德 | 优视 | 友盟 | 酷盘 | 虾米 | 天天动听 | 来往 | 钉钉 | 11Main | 支付宝
关于淘宝 合作伙伴 营销中心 联系客服 开放平台 诚征英才 联系我们 网站地图 法律声明 © 2016 Taobao.com 版权所有
网络文化经营许可证：文网文[2010]040号 | 增值电信业务经营许可证：浙B2-20080224-1 | 信息网络传播视听节目许可证：1109364号