order_site/docs/行业电子凭证/解决方案/技术方案/2.对接实战.md

对接实践 更新时间：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 什么是卡券结算(可选) 需要您在店铺开通对应的门店结算能力，既卡券核销一张既结算一张，并且钱会独立结算给核销的门店，需要您的各个门店在快手上绑定，并且有独立的结算账户。金额会按照您配置好的门店结算给独立的门店账户。