167 lines
8.0 KiB
Markdown
167 lines
8.0 KiB
Markdown
对接实践
|
|
更新时间：2025-03-26
|
|
阅读数：8756
|
|
1.对接泳道图
|
|
1.1 接入方案A:全流程接入(推荐方案)
|
|
|
|
1.2 接入方案B:券码接入
|
|
|
|
|
|
1.3 接入方案C: 核销接入
|
|
|
|
|
|
注意：由快手发起调用到各位isv的接口如下：
|
|
integration.virtual.eticket.send 请看接口文档，SPI 中的 KwaishopVirtualEticketSendService
|
|
integration.virtual.eticket.destroy 请看接口文档，SPI 中的 KwaishopDigitalETicketDestoryService
|
|
integration.virtual.eticket.query 请看接口文档，SPI中的 KwaishopVirtualEticketQueryService
|
|
|
|
注意：对于选择非快手发码的业务，必须要实现ntegration.virtual.eticket.query方法
|
|
快手会在退款操作前主动调用，确保对端没有发码，如果真的没有发码，请您阻拦发货请求，并且返回结果会成功，且返回etickets为空。
|
|
这样快手会主动退款。否则快手会以资金安全为由阻断买家和卖家的退款行为，造成卡单，对isv您所服务的商家造成发货时效延迟，发货失效过长会导致卖家无法让主播分销。
|
|
|
|
1.4 接入方案D: 平台自发码
|
|
平台发码，无需快手对接核销系统，在商品发布时，”券码发放方式“ 选择 “快手平台发码”即可
|
|
|
|
|
|
|
|
|
|
|
|
1.5 可选的接入方案E:商品发布接入POI(选接)
|
|
何为POI：对于地图产品而言，某个地理位置周边的信息，位置数据，称之为 POI (point of information)
|
|
|
|
想接入门店poi？快手当前提供了将百度、腾讯、高德的主流Poi信息转换为快手的Poi，并且在创建商品时关联这些Poi，这样买家浏览商品时就可以看到可用门店。
|
|
|
|
当需要接入门店时评估接入，可以直接通过快手后台直接完成，也可以通过本方案的接口完成接入，包含2个接口(创建需要把各个图商的Poi转换成快手的Poi)：
|
|
|
|
1. open.shop.poi.getPoiDetailByOuterPoi 通过图商poi获取快手poi详情
|
|
当前支持的图商：1-高德 2-百度 3-腾讯
|
|
|
|
2. open.item.new 商品新增接口
|
|
|
|
请求参数中：poiIds传入，即为带poiId的商品，仅支持快手的Poi
|
|
|
|
快手商品上的poi信息跟卡券核销时的门店信息并没有做关联和强校验，如果需要做可用门店的强校验，请在回传快手核销状态时，接入方自己先做好可用门店的校验。(快手后续会提供对应的功能，请期待)
|
|
|
|
2.能力说明(接入必看)
|
|
在接入的过程当中可能还会遇到需要查询订单信息、退款信息、结算信息、支付信息等接口，这些接口可以在如下文档按需查看。
|
|
|
|
https://open.kwaixiaodian.com/zone/new/docs/api?apiName=open.seller.order.cps.list&version=1
|
|
|
|
如果需要获取订单列表和退款列表等信息，快手提供了接口查询和消息两种方式，监听快手平台消息的文档如下
|
|
https://open.kwaixiaodian.com/zone/new/docs/msg?msgName=kwaishop_order_addOrder&version=1
|
|
|
|
2.1.卡券发码的有效期
|
|
(1) 怎么计算卡券有效期？
|
|
|
|
|
|
途中为商品发布时的卡券有效期选择。从上往下分别为：
|
|
固定起止时间、估计结束时间、预定有效天数
|
|
|
|
快手平台会根据商品上的配置自动计算有效期，要求外部isv发码时的有效期保持一致，否则发码失败。isv的有效期开始时间可以比快手平台略早，结束时间比快手平台略晚。
|
|
|
|
建议接入方直接采用快手根据商品上的配置，计算好的券码有效期，双方保持一致，避免出现客诉
|
|
|
|
|
|
|
|
(2) 如果需要关联erp里自己的货品id，可以通过ext大字段中的skuNick字段关联，请联系卖家上架商品时填入
|
|
|
|
|
|
|
|
2.2.什么是货值
|
|
重点知识：
|
|
|
|
(1)什么是货值和总货值？
|
|
|
|
订单totalGoodsValue标识电子凭证的总的价值。
|
|
|
|
每张券的goodsValue代表本张券所占的权重。
|
|
|
|
平台会校验所有券的goodsValue之和等于totalGoodsValue，并且按照货值比计算每张券的金额
|
|
|
|
|
|
|
|
业务介绍 场景 totalGoodsValue goodsValue 金额占比
|
|
下单购买1件商品，发出3个电子凭证A B C，消费者支付了10元。 货值相等 3
|
|
A券 goodsValue=1
|
|
|
|
B券 goodsValue1
|
|
|
|
C券 goodsValue=1
|
|
|
|
A券=3.33元
|
|
|
|
B券=3.33元
|
|
|
|
C券=3.34元
|
|
|
|
下单购买1件商品，发出3个电子凭证A B C，消费者支付了10元。 货值相等，但是不可以除尽的情况，需要最后一张做倒减 100
|
|
A券 goodsValue=33
|
|
|
|
B券 goodsValue=33
|
|
|
|
C券 goodsValue=34
|
|
|
|
A券=3.33元
|
|
|
|
B券=3.33元
|
|
|
|
C券=3.34元
|
|
|
|
下单购买1件商品，发出3个电子凭证A B C，消费者支付了10元。 货值不相等 100
|
|
A券 goodsValue=10
|
|
|
|
B券 goodsValue=20
|
|
|
|
C券 goodsValue= 70
|
|
|
|
A券=1元
|
|
|
|
B券=2元
|
|
|
|
C券=7元
|
|
|
|
|
|
|
|
2.3.未发货自动关闭订单，货款退回给买家的情况说明
|
|
快手为了保护买卖家的钱款安全，在快手发现您未能及时给买家发货(默认48小时)，会主动关闭订单将钱款退回给买家
|
|
|
|
在操作钱款前，快手会主动触发KwaishopVirtualEticketQueryService(电子凭证查询发码结果或券码状态)接口，如果该接口抛出异常，或者查出卡券不为空，则会中断流程，详细处理方式如下：
|
|
|
|
接口 您的返回结果 快手的处理方式 建议服务商的处理方式
|
|
KwaishopVirtualEticketQueryService(电子凭证查询发码结果或券码状态) success为1 ，卡券列表为空 快手认为您的确未发券，自动关闭订单。(正常处理流程) 不用处理
|
|
KwaishopVirtualEticketQueryService(电子凭证查询发码结果或券码状态) success不为1 ，或者抛出异常
|
|
快手认为您服务挂了，暂缓关闭订单，退钱给买家的操作。订单卡住。
|
|
|
|
(异常处理流程)会影响您店铺的平均发货时长，店铺指标下降。
|
|
|
|
返回正确的接口，参考success为1的上诉场景
|
|
|
|
KwaishopVirtualEticketQueryService(电子凭证查询发码结果或券码状态) success为1 ，且返回了卡券 快手认为您那边发了货，但是没回传给快手，暂时中断发货流程，等您补发卡券
|
|
1. 通过发码回调接口，把码发送给快手。
|
|
|
|
2. 联系运营，关闭这一批异常订单。
|
|
|
|
|
|
|
|
2.4.过期自动退款场景，快手发起作废和退款的情况说明
|
|
当卡券被发放给买家后，就会开始计算有效期，当有效期时间到，快手会优先锁定快手内的卡券的状态，进入到销毁中(此处在快手内卡券不可使用)，然后通过KwaishopDigitalETicketDestoryService(电子凭证发起销毁接口)通知服务商，此时KwaishopDigitalETicketDestoryService接口中的reason字段固定为："ETICKET_EXPIRED"。此类请求的含义为：当前卡券已经过期了，请服务商也销毁您那边的卡券。
|
|
|
|
主动发起退款场景，如果您48小时未处理卡券，将会自动同意退款，卡券只能一次性处理所有卡券，不能仅销毁成功其中一张。
|
|
|
|
|
|
|
|
接口 服务商的后置请求 快手的处理方式 建议服务商的处理方式
|
|
快手了KwaishopDigitalETicketDestoryService接口以后 KwaishopDigitalETicketDestoryService接口返回受理成功，并且调用。“integration.callback.virtual.eticket.destroy”接口，reason回传给快手的也是ETICKET_EXPIRED 这种场景，快手侧的卡券和服务商的卡券均已销毁
|
|
快手立即触发退款，将钱退给买家。(正确场景) 无需修改
|
|
快手了KwaishopDigitalETicketDestoryService接口以后
|
|
KwaishopDigitalETicketDestoryService接口24小时未受理成功，或者24小时内未回传快手
|
|
|
|
这种场景，快手侧认为是服务商超时未处理过去卡券，
|
|
|
|
24小时候强制将钱退给买家。(有资损风险)
|
|
|
|
改成正确的方式
|
|
|
|
|
|
2.5 什么是卡券结算(可选)
|
|
需要您在店铺开通对应的门店结算能力，既卡券核销一张既结算一张，并且钱会独立结算给核销的门店，需要您的各个门店在快手上绑定，并且有独立的结算账户。金额会按照您配置好的门店结算给独立的门店账户。 |