产品业务逻辑
使用说明
本文档为有开发能力的友朋合作伙伴提供技术对接能力，主要包括了兑换码、抵扣券和第三方支付对接。
对接前提：
需要拥有友朋后台和设备
对接流程：
- 友朋运营商平台【营销中心-开放平台】创建第三方，根据第三方用到的业务勾选允许调用的 API 接口，并且拿到 APPID 和密钥。（若此第三方需要接收友朋异步回调通知，创建时需要填写回调接收地址，回调的密钥为此第三方友朋分配的密钥）
- 根据不同的业务，调用不同的 API 接口，完成相应的业务逻辑。
一、 对接兑换码逻辑
以下图片为下方方案出现的页面的解释
 |
  |
|---|---|
| 【友朋设备兑换码兑换页面】 | 【友朋手机端“闪电换”】 |
案例一
使用场景
- 领取
消费者通过第三方的页面获取到友朋兑换码
- 兑换
消费者在【友朋设备兑换码兑换页面】输入兑换码使设备掉货或者通过【友朋手机端“闪电换”】选择设备出货
实现流程
- 在友朋运营商后台【营销中心-营销活动-兑换码库】创建兑换码库，设置好需要发放的商品和数量，拿到兑换码库的【第三方调用信息】，即兑换码库 ID；
- 调用 activity.voucher.get 接口，获取兑换码库中的商品信息和兑换码剩余数量
- 若在非微信或支付宝客户端页面，调用 activity.voucher.receive.url.inapp，获取一个兑换码的 url 和加密的兑换码；若在微信或支付宝客户端页面，则可调用 activity.voucher.receive.url，获取一个 URL 和明文的兑换码，（此时需要让用户访问此 URL，将兑换码与用户绑定，缺少这一步将导致兑换码无法兑换）
- 在第三方页面保存 URL，用户可以进入 URL 获得明文兑换码；第三方自行做页面展示明文兑换码，此处若获得的是加密的兑换码则需要调用 activity.vouchercode.get 获取明文兑换码
- 用户在设备上点击【礼券兑换】，输入明文兑换码，或者用户点击进入兑换码 URL，点击页面上的“闪电换”，选择兑换的设备，将商品拖入设备，设备掉货（第三方页面需要保存兑换码 URL，方便用户查看）
案例二
使用场景
领取
消费者通过第三方的页面获取到友朋兑换码
兑换
消费者在【第三方闪电换页面】选择设备出货
实现流程
- 在友朋运营商后台【营销中心-营销活动-兑换码库】创建兑换码库，设置好需要发放的商品和数量，拿到兑换码库的【第三方调用信息】，即兑换码库 ID；
- 调用 activity.voucher.get 接口，获取兑换码库中的商品信息和兑换码剩余数量
- 若在非微信或支付宝客户端页面，调用 activity.voucher.receive.url.inapp，获取一个兑换码的 url 和加密的兑换码；
- 微信或支付宝客户端页面，则可调用 activity.voucher.receive.url，获取一个 URL 和明文的兑换码，（此时需要让用户访问此 URL，将兑换码与用户绑定，缺少这一步将导致兑换码无法兑换）
- 此处若获得的是加密的兑换码则需要调用 activity.vouchercode.get 获取明文兑换码。
- 第三方开发者自行做页面展示兑换码，并且在此页面有“闪电换”按钮。
- 点击“闪电换”按钮，调用 activity.voucher.exchange 接口，进行掉货（此处需要用户选择设备，兑换码支持兑换的设备可以通过 activity.vouchercode.get 获取）
案例三（此案例只适用有屏设备）
使用场景
领取
消费者通过第三方的页面获取到友朋兑换码
兑换
消费者在【第三方设备兑换码兑换页面】输入兑换码使设备掉货
实现流程
- 在友朋运营商后台【营销中心-营销活动-兑换码库】创建兑换码库，设置好需要发放的商品和数量，拿到兑换码库的【第三方调用信息】，即兑换码库 ID；
- 调用 activity.voucher.get 接口，获取兑换码库中的商品信息和兑换码剩余数量
- 若在非微信或支付宝客户端页面，调用 activity.voucher.receive.url.inapp，获取一个兑换码的 url 和加密的兑换码；若在微信或支付宝客户端页面，则可调用 activity.voucher.receive.url，获取一个 URL 和明文的兑换码，时需要让用户访问此 URL，将兑换码与用户绑定，缺少这一步将导致兑换码无法兑换）
- 此处若获得的是加密的兑换码则需要调用 activity.vouchercode.get 获取明文兑换码。
- 运营商后台购买【自定义菜单】应用，将自行开发的兑换页面配置到自定义菜单。（每台设备上展示的自定义菜单页面会自动在后面拼接设备 TID）
- 用户在设备的【自定义菜单】页面输入明文兑换码，调用 activity.voucher.exchange 接口，进行掉货。
二、对接第三方支付
对接第三方支付准备工作
- 联系友朋客服将支付方式切换至“第三方支付”
在运营商后台【系统管理-支付配置】中配置第三方支付参数
支付跳转地址： 消费者扫码后友朋系统跳转到第三方开发的页面地址
第三方服务端 API 地址： 友朋主动请求第三方时的请求地址（处理退款逻辑时用到）
签名密钥： 友朋主动请求第三方时会使用此签名
支付渠道： 在设备端展示设备可以支持的支付方式，第三方根据自己的业务选择展示。
以下图片为下方方案出现的页面的解释
 |
 |
 |
 |
|---|---|---|---|
| 【友朋设备商品选购页】 | 【友朋设备商品展示页】 | 【友朋手机商品展示页】 | 【友朋无屏设备手机商品选购页】 |
案例一
使用场景
- 选择商品
消费者在【友朋设备商品选购页】上选择商品进入【友朋设备商品展示页】，扫描二维码，进入【友朋手机商品展示页】或者消费者在友朋的【友朋无屏设备手机商品选购页】上选择商品，进入【友朋手机商品展示页】
- 支付
点击立即支付，友朋携带订单号、支付回调地址和支付后跳转地址信息跳转至第三方开发的页面（因为使用的是【友朋手机商品展示页】，此处的第三方页面只需要一个空白页面可以调起收银台即可），第三方根据此订单号关联创建第三方订单调起收银台，让用户支付。
掉货
完成支付后，回调订单支付成功，设备掉货。
实现流程
- 根据友朋系统传入的订单号，调用 consumer.order.get 获取订单的价格
- 根据订单价格调起收银台，创建关联友朋订单的第三方订单，让用户支付
- 支付完成后，同步跳转至支付后跳转地址，并且根据支付回调的地址回调友朋，友朋会让设备掉货。
案例二
使用场景
- 选择商品
消费者在【友朋设备商品选购页】上选择商品进入【友朋设备商品展示页】，扫描二维码或者消费者在友朋的【友朋无屏设备手机商品选购页】上选择商品，然后友朋携带订单号、支付回调地址和支付后跳转地址信息跳转至【第三方手机商品展示页】，此处的页面需要根据订单信息和第三方业务组一个手机商品展示页面（第三方业务可以包括展示第三方的优惠信息，积分兑换等）
- 支付
用户在【第三方手机商品展示页】点击支付，第三方处理支付逻辑
- 掉货
完成支付后，回调对应订单支付成功，设备掉货。
实现流程
- 联系友朋客服，开启第三方支付“隐藏商品详情页”
- 根据友朋系统传入的订单号和支付回调地址，调用 consumer.order.get 获取订单的信息，根据订单信息，组出手机端商品展示页面。
- 用户选择支付方式（此处的支付方式可以是微信、支付宝、积分甚至是让用户完成一个规定的动作）
- 支付完成后，根据支付回调的地址回调友朋，友朋会让设备掉货。
案例三
使用场景
- 选择商品
消费者在【第三方设备商品选购页】选择商品进入【第三方设备商品展示页】，扫描二维码（此处的码可以是小程序码），进入【第三方手机商品展示页】此处的页面需要根据订单信息和第三方业务组一个手机商品展示页面（第三方业务可以包括展示第三方的优惠信息，积分兑换等）
- 支付
用户在【第三方手机商品展示页】点击支付，第三方处理支付逻辑，
- 掉货
支付完成后，根据支付回调的地址回调友朋，友朋会让设备掉货。
实现流程
注意：需要先在友朋运营商后台购买自定义菜单应用，然后将【第三方设备商品选购页】URL 配置到设备上。友朋会每台设备上的 URL 后拼接设备的 TID
- 根据设备 TID，调用 terminal.product.layout.get 接口，获取设备的商品图片、名称、价格、token 等信息
- 根据商品信息组出【第三方设备商品展示页】
- 用户点击商品时，根据商品 token 和第三方开发的手机端页面 URL 生成二维码（此处可以是小程序码）
- 用户扫码后，手机端调用 terminal.product.get 接口，根据商品 token 获取商品信息，根据商品信息组出手机端商品展示页面
- 用户选择支付方式（此处的支付方式可以是微信、支付宝、积分甚至是让用户完成一个规定的动作），点击支付，调用 consumer.order.create 接口创建订单，拿到订单号和支付回调地址，并根据此订单号关联创建第三方订单调起收银台
- 支付完成后，根据支付回调的地址回调友朋，友朋会让设备掉货。
- 接收 notify.consumer.order.simple 回调的订单号和 TID，收到回调后，需要刷新设备展示页面。
案例四
使用场景
- 选择商品
消费者扫描无屏设备上的【第三方二维码】，进入【第三方手机端商品选购页】选择商品进入【第三方手机端商品展示页】，此处的页面需要根据订单信息和第三方业务组一个手机商品展示页面（第三方业务可以包括展示第三方的优惠信息，积分兑换等）
- 支付
用户在【第三方手机商品展示页】点击支付，第三方处理支付逻辑，
- 掉货
支付完成后，根据支付回调的地址回调友朋，友朋会让设备掉货。
实现流程
- 更换无屏设备上的【友朋二维码】为【第三方二维码】，（此处的第三方二维码根据【第三方手机端商品选购页】URL 和 TID 生成，此处的二维码可以带 TID 的小程序码）
- 用户扫码时，根据设备 TID，调用 terminal.product.layout.get 接口，获取设备的商品图片、名称、价格、token 等信息，根据商品信息组出【第三方手机端商品选购页】
- 用户选择商品后，手机端调用 terminal.product.get 接口，根据商品 token 获取商品信息，根据商品信息组出【第三方手机端商品展示页】
- 用户选择支付方式（此处的支付方式可以是微信、支付宝、积分甚至是让用户完成一个规定的动作），点击支付，调用 consumer.order.create 接口创建订单，拿到订单号和支付回调地址，并根据此订单号关联创建第三方订单调起收银台
- 支付完成后，根据支付回调的地址回调友朋，友朋会让设备掉货。
案例五
使用场景
- 选择商品
消费者扫描无屏设备上的【友朋二维码】，进入【第三方手机端商品选购页】选择商品进入【第三方手机端商品展示页】
- 支付
用户在【第三方手机商品展示页】点击支付，第三方处理支付逻辑，
- 掉货
支付完成后，根据支付回调的地址回调友朋，友朋会让设备掉货。
实现流程
- 联系友朋客服开启第三方支付“隐藏无屏商品设备选购列表”，并在运营商后台【系统管理-支付配置】的无屏商品列表页面配置【第三方手机端商品选购页】URL 并拼接$TID$参数
- 用户扫码时，友朋会携带设备 TID 跳转至【第三方手机端商品选购页】URL，根据 TID，调用 terminal.product.layout.get 接口，获取设备的商品图片、名称、价格、token 等信息，根据商品信息组出【第三方手机端商品选购页】
- 用户选择商品后，手机端调用 terminal.product.get 接口，根据商品 token 获取商品信息，根据商品信息组出【第三方手机端商品展示页】
- 用户选择支付方式（此处的支付方式可以是微信、支付宝、积分甚至是让用户完成一个规定的动作），点击支付，调用 consumer.order.create 接口创建订单，拿到订单号和支付回调地址，并根据此订单号关联创建第三方订单调起收银台
- 支付完成后，根据支付回调的地址回调友朋，友朋会让设备掉货。
三、小程序对接场景
使用场景
希望消费者在小程序中领取兑换券、抵扣券
实现流程
- 在友朋后台创建【H5 线上发放】活动，获取 $h5活动链接$
- 在第三方小程序中放置一个入口，消费者点击后跳转到【友 GO+】小程序领券，小程序跳转时需携带 $appId$ 和 $path$，结构如下：
// 跳转小程序打开H5线上发放活动页
navigateToMiniProgram({
appId: 'wx21cbadf63f793cba', // 友GO+ appid
path: `pages/webview/webview?url=${encodeURIComponent(h5活动链接)}`
})