该文档主要面向需要入驻蚂蚁开放平台的产品、架构、开发等相关人员, 需要有基本的程序开发背景。通过该文档能够快速集成(店铺数据)功能,接入前需要入驻开放平台并创建了应用,应用已申请该接口权限并配置RSA密钥。
要在您的应用中使用支付宝开放产品的接口能力,您需要先去蚂蚁金服开放平台(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调用前需要进行初始化,以Java代码为示例如下:
1 | AlipayClient alipayClient = new DefaultAlipayClient(URL, APP_ID, ALIPAY_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 |
支付宝店铺数据包含以下接口:
接口名称 | 接口描述 |
---|---|
商户行为数据上传接口 alipay.offline.provider.shopaction.record |
上传商户行为数据,现在包括的商户行为(商户营业状态、菜品变更、餐桌变更) |
用户行为数据上传接口 alipay.offline.provider.useraction.record |
上传用户行为数据,现在包括的用户行为(用户点菜订单、预定订单、排号订单) |
接口调用示例大致分为3步:
1.商户行为接口代码调用示例
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 | AlipayClient alipayClient = new DefaultAlipayClient( "https://openapi.alipay.com/gateway.do" , APP_ID, APP_PRIVATE_KEY, "json" , CHARSET, ALIPAY_PUBLIC_KEY, "RSA2" ); JSONObject object = new JSONObject(); object.put( "action_type" , "insert_table" ); //插入座位的action_type object.put( "entity" , "shop" ); //店铺行为接口这里都是shop object.put( "date_time" , DateUtil.format( new Date(), "yyyy-mm-dd HH:MM:ss" )); object.put( "industry" , "REPAST" ); //行业都是餐饮 //构建action_detail json,本次是店铺插入餐桌 JSONObject detail = new JSONObject(); detail.put( "tableId" , "你的桌子ID主键" ); detail.put( "max" , 10 ); //最大人数 detail.put( "min" , 1 ); //最小人数 detail.put( "tableName" , 1 + "_" + 10 + " 人" ); detail.put( "tableType" , 0 ); //0普通 1 包厢 detail.put( "tableNum" , "A01" ); detail.put( "status" , 0 ); //0空闲 1 占用 2 不可知 -1 删除 默认空闲 object.put( "action_detail" , detail); //设置到data中 key是action_detail //构建店铺映射关系json JSONObject shopDoJson = new JSONObject(); shopDoJson.put( "shop_id" , "口碑店铺ID" ); shopDoJson.put( "outer_id" , "你的店铺ID" ); shopDoJson.put( "type" , "mike" ); object.put( "outer_shop_do" , shopDoJson); //设置店铺 object.put( "action_outer_id" , "你的action_detail实体主键,本次是tableId的value" ); AlipayOfflineProviderShopactionRecordRequest request = new AlipayOfflineProviderShopactionRecordRequest(); request.setBizContent(object.toJSONString()); AlipayOfflineProviderShopactionRecordResponse response = alipayClient.execute(request); //判断response 执行你的业务逻辑 ==========插入菜品demo======= AlipayClient alipayClient = new DefaultAlipayClient( "https://openapi.alipay.com/gateway.do" , APP_ID, APP_PRIVATE_KEY, "json" , CHARSET, ALIPAY_PUBLIC_KEY, "RSA2" ); JSONObject object = new JSONObject(); object.put( "action_type" , "insert_dish" ); //插入菜品的action_type object.put( "entity" , "shop" ); //店铺行为接口这里都是shop object.put( "date_time" , DateUtil.format( new Date(), "yyyy-mm-dd HH:MM:ss" )); object.put( "industry" , "REPAST" ); //行业都是餐饮 object.put( "action_outer_id" , "你的action_detail实体主键,本次是菜品的value" ); //构建action_detail json,本次是店铺插入菜品 JSONObject detail = new JSONObject(); detail.put( "outerDishId" , "你的菜品ID" ); detail.put( "name" , "菜品名称" ); detail.put( "price" , 10 ); //菜品价格 单位分 detail.put( "soldout" , 0 ); //是不是已经售卖完成 0正常,1估清,默认0 detail.put( "quantity" , 100 ); //库存数量(不传 代表没有意义) List pict = new ArrayList(); pict.add( "http://alipay.dl.django.t.taobao.com/rest/1.0/image?fileIds=x_DNt-sAQqCCs4QdRdd40wAAACMAAQED&zoom=original" ); pict.add( "http://alipay.dl.django.t.taobao.com/rest/1.0/image?fileIds=x_DNt-sAQqCCs4QdRdd40wAAACMAAQED&zoom=original" ); detail.put( "pict" , pict); //商品图片(只支持http的图片) detail.put( "status" , 0 ); // 0 上架(可点) 1 不在线(不可点) 默认0 detail.put( "desc" , "我是菜品描述" ); detail.put( "sort" , 1 ); //排序 detail.put( "unit" , "份" ); detail.put( "dishTypeID" , ShopMappingDAOTest.getUUID()); detail.put( "dishTypeName" , "冷菜区" ); JSONArray array = new JSONArray(); JSONObject sku = new JSONObject(); sku.put( "property" , "规格:大份" ); //都是K:V 每一对KV一种价格。 sku.put( "quantity" , 10 ); sku.put( "price" , 15 ); sku.put( "id" , "111122" ); //代表当前skuId JSONObject small = new JSONObject(); small.put( "property" , "规格:小份" ); small.put( "quantity" , "10" ); small.put( "price" , "5" ); small.put( "id" , "111123" ); array.add(sku); array.add(small); detail.put( "dishSkuList" , array.toJSONString()); object.put( "action_detail" , detail); //构建店铺映射关系json JSONObject shopDoJson = new JSONObject(); shopDoJson.put( "shop_id" , "口碑店铺ID" ); shopDoJson.put( "outer_id" , "你的店铺ID" ); shopDoJson.put( "type" , "mike" ); object.put( "outer_shop_do" , shopDoJson); //设置店铺 AlipayOfflineProviderShopactionRecordRequest request = new AlipayOfflineProviderShopactionRecordRequest(); request.setBizContent(object.toJSONString()); AlipayOfflineProviderShopactionRecordResponse response = alipayClient.execute(request); |
2.用户行为接口代码调用示例
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | AlipayClient alipayClient = new DefaultAlipayClient( "https://openapi.alipay.com/gateway.do" , APP_ID, APP_PRIVATE_KEY, "json" , CHARSET, ALIPAY_PUBLIC_KEY, "RSA2" ); JSONObject object = new JSONObject(); object.put( "action_type" , "order_num" ); //设置排号的具体action_type,每种行为都不一样 object.put( "entity" , "user" ); //用户行为都是设置user object.put( "user_id" , "2088324313131" ); //支付宝用户ID,没有可以不用设置,具体是不是必须参见文档说明 object.put( "platform_user_id" , "123245675" ); //外部平台自己的用户ID object.put( "mobile" , "156XXXXXXXX" ); //用户的手机号码 object.put( "source" , "koube.com" ); //来源域名 object.put( "alipay_app_id" , "服务插件ID" ); //服务插件ID object.put( "date_time" , DateUtil.format( new Date(), "yyyy-mm-dd HH:MM:ss" )); object.put( "industry" , "REPAST" ); //行业都是餐饮 //构建action_detail json,本次是排号订单 JSONObject detail = new JSONObject(); detail.put( "source " , "koube.com" ); detail.put( "outOrderId" , "你的订单主键" ); detail.put( "mobile" , "15626225236" ); //领取排队的手机号码 detail.put( "shopName" , "店铺名称" ); detail.put( "num" , "A0001" ); //领取的编号 detail.put( "qname" , "小桌" ); //座位类型 detail.put( "qattr" , "1-2人" ); detail.put( "type" , "0,1,2" ); detail.put( "people" , 6 ); //几个人 detail.put( "credit" , 10 ); //信誉值 detail.put( "desc" , "变更内容" ); detail.put( "wait" , new Random().nextInt( 10 )); //前面等待的人数 detail.put( "waitTime" , "5分钟" ); //预计等待时间 detail.put( "passNumType" , 1 ); //过号后的处理类型(-1:不可知 0 顺延 1:不可顺延) detail.put( "passNumDesc" , "过号顺延" ); //商家设置的过号后的处理文案 detail.put( "status" , 2 ); //状态2 取号成功4 叫号 5 就餐 6 过号 7 取消 object.put( "action_detail" , detail); //设置到data中 key是action_detail //构建店铺映射关系json JSONObject shopDoJson = new JSONObject(); shopDoJson.put( "shop_id" , "口碑店铺ID" ); shopDoJson.put( "outer_id" , "你的店铺ID" ); shopDoJson.put( "type" , "mike" ); object.put( "outer_shop_do" , shopDoJson); //设置店铺 object.put( "action_outer_id" , "你的action_detail实体主键,本次是outOrderId的value" ); AlipayOfflineProviderUseractionRecordRequest request = new AlipayOfflineProviderUseractionRecordRequest(); request.setBizContent(object.toJSONString()); AlipayOfflineProviderUseractionRecordResponse response = alipayClient.execute(request); //判断response 执行你的业务逻辑 |
同步返回结果码 | 含义 | 说明 |
---|---|---|
10000 | 业务处理成功 | |
40001~40006 | 业务处理失败 | 具体失败原因请参考公共错误码。其它请参考API文档。 |
20000 | 业务出现未知错误或者系统异常 | 业务出现未知错误或者系统异常(请一定在确定本次调用结果后,发起重试),可调用查询接口发起查询确定结果。 |