增加文档与图片
This commit is contained in:
yml2213
@@ -0,0 +1,76 @@
|
||||
基础技术
|
||||
更新时间：2025-03-26
|
||||
阅读数：5722
|
||||
本处介绍开放平台的基础协议和通用接入方式
|
||||
|
||||
1.环境说明
|
||||
两套环境相互独立，数据不可相互使用
|
||||
|
||||
环境 环境地址 说明
|
||||
线上环境 https://open.kwaixiaodian.com 线上环境可直接使用
|
||||
线下环境 https://gw-merchant-staging.test.gifshow.com 测试环境调用需要提供出口IP，并联系快手对接人添加ip白名单
|
||||
2.授权流程
|
||||
2.1 如何获取token
|
||||
首先需要拿到appkey、appsecret、signSecret信息，线下环境找快手提供，线上环境到“开放平台-控制台-应用中心-应用详情”查看，请求示例如下
|
||||
https://gw-merchant-staging.test.gifshow.com/integration/virtual/topup/mobile/order/callback?access_token=ChFvYXV0aC5hY2Nlc3NUb2tlbhJAErnBVtjx5FPdE0AITaSq4xlW6XaTOaV_McGinj-hFivkyxAw1SZ3i28bLEa6xP-C4UuKlRz6uh3lukYRLDcAdRoSeCxQKnQhAPTTL4YL0_NqmqD-IiApwDDKEL1wBW7EbWH0ZRDO3UUNSCxMwkuF7nb57Fn7AygFMAE&appkey=ks683702719562282620&method=integration.virtual.topup.mobile.order.callback¶m=%7B%22orderId%22%3A%22100%22%2C%22businessTime%22%3A%222021-06-08T14%3A16%3A01%2B0800%22%2C%22mobile%22%3A%2215990013607%22%2C%22status%22%3A%22FAILED%22%2C%22amount%22%3A%225000%22%2C%22bizType%22%3A20%7D&signMethod=MD5×tamp=1623132961782&version=1&sign=c091ca3414a9d6429a0fda47c383d202
|
||||
|
||||
注：如果回调失败需要以指数周期（1m、2m、4m、8m...）重试
|
||||
|
||||
注意：
|
||||
|
||||
测试环境需要把自己的出口ip给到快手，配置白名单，否则无权限访问。配置对接人：屈国庆，王哲，杨天问
|
||||
测试环境和线上环境，是两套token，不可混用。测试token，如下方式获取。线上token通过上面sdk调用，有效期48h。
|
||||
Token授权码：参考文档（2.2节 商家开发者角色）
|
||||
授权一定要用店主的主账号来授权，否则token换取到的sellerId就是子账号的id
|
||||
线上token验证：https://open.kwaixiaodian.com/commonTool/tokenAuth/accessToken?cateId=0&typeIndex=1，需要快手app扫描登录
|
||||
测试环境获取token的步骤（参考文档（2.2节 商家开发者角色））：
|
||||
|
||||
测试环境：优先使用集成中心自己调试
|
||||
线上环境：需要按照开放平台的授权文档，通过你的店铺由店主授权(不要用子账号授权)，然后用你的redirect_uri来接收code。
|
||||
用授权码code换取长时令牌refreshToken以及访问令牌accessToken
|
||||
示例：https://gw-merchant-staging.test.gifshow.com/oauth2/access_token?app_id=ks683702719562282620&app_secret=zSCiWmGOk_diMCU9k3zHcg&grant_type=code&code=bab4f0378269db7a1603de9d5a381615d7d2c451ffbb32f8ede78ac8f05b6171f7d4eb8c
|
||||
|
||||
用长时令牌refreshToken刷新访问令牌accessToken
|
||||
示例：
|
||||
https://gw-merchant-staging.test.gifshow.com/oauth2/refresh_token?app_id=ks683702719562282620&app_secret=zSCiWmGOk_diMCU9k3zHcg&grant_type=refresh_token&refresh_token=ChJvYXV0aC5yZWZyZXNoVG9rZW4SkAGpBE83BKP9TeiwbEP1-IIQL2G08s8rU-OETIzfs5wFN2HeZgUaR_mfGjKHjHzfV-sicHG4IZmxVKlxQhdAZIdf01AR51ZtPN7sHY3eeW6RMnx8LPKo92V1yk-GnkXiiPMWpn9Vmhq0dk_U_aKh5Jwg7mMySO8IEDoz-fPk9Rc2rjUK3inqxNd7rqTQ9fz316oaEsFIUEDt4EyD090nGWRnwQ5g3SIgY-ctBM_4jrFXxBA9EF1jMaP6as57lNYIyOZf9Qlqq64oBTAB
|
||||
|
||||
后面就可以一直用第三步来刷新accessToken
|
||||
|
||||
3.签名算法
|
||||
3.1 协议
|
||||
https协议，支持GET/POST，调用地址、appkey、signSecret由快手提供，返回结果为json字符串。
|
||||
|
||||
3.2 签名
|
||||
官方签名说明
|
||||
|
||||
快手电商开放平台的所有开放API调用都需要进行加签，服务端会根据请求参数，对签名进行验证，签名不合法的请求将会被拒绝。当前平台支持的签名算法为MD5(signMethod=MD5)
|
||||
|
||||
下面将详细介绍签名流程：
|
||||
|
||||
对所有API系统参数和请求参数(不包括sign参数和byte[]类型的参数），根据参数名称进行字典顺序排序；
|
||||
|
||||
排序前的顺序是：appkey=ks123，version=1，method=open.xxx.xxx，signMethod=MD5，access_token=xxxx，timestamp=1583271919000，param={"title":"短袖", "relItemId":123456, "categoryId":12}
|
||||
|
||||
排序后的顺序是：appkey=ks123¶m={"categoryId":12,"relItemId":123456,"title":"短袖"}&signMethod=MD5×tamp=1583271919000&version=1&signSecret=abc
|
||||
|
||||
|
||||
|
||||
保留=符号，用&符号将多个参数及其值组装在一起，根据上面的示例得到的排序结果为：access_token=xxx&appkey=ks123&method=open.xxx.xxx¶m={"title":"短袖", "relItemId":123456, "categoryId":12}&signMethod=MD5×tamp=1583271919000&version=1
|
||||
|
||||
排序好参数后，在末尾加入signSecret（在应用创建审核通过后由平台分配，在“应用中心-应用列表-应用详情”中可见）进行对应算法的签名计算
|
||||
|
||||
MD5(access_token=xxx&appkey=ks123&method=open.xxx.xxx.xxx¶m={"title":"短袖", "relItemId":123456, "categoryId":12}&signMethod=MD5×tamp=1583271919000&version=1&signSecret=xxxxxx)=sign
|
||||
|
||||
|
||||
|
||||
签名加好后，将sign添加到请求参数中，并对param内容进行encode（双引号"和冒号:也需要encode），这里注意请求参数里面是不包括signSecret的，signSecret只是作为加签因子用于签名sign的计算，
|
||||
|
||||
所以千万不要将signSecret当作请求参数传输，请求参数内容见第3点API调用参数说明的表格内容，请求url样例：
|
||||
|
||||
https://open.kwaixiaodian.com/open/xxx/xxx?access_token=xxx&appkey=ks123&method=open.xxx.xxx.xxx¶m=%7B%22title%22%3A%22%E7%9F%AD%E8%A2%96%22%2C%20%22relItemId%22%3A123456%2C%20%22categoryId%22%3A12%7D&version=1&signMethod=MD5×tamp=1583271919000&sign=af2d80958e77e17f1d973003b7b7aec2
|
||||
说明：param是json对象，需要排序
|
||||
|
||||
4.API调用
|
||||
确认完成了授权流程后进行API的调用测试，内容详情可见《API调用说明》，也可使用平台提供的API测试工具测试
|
||||
|
||||
|
||||
@@ -0,0 +1,167 @@
|
||||
对接实践
|
||||
更新时间：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 什么是卡券结算(可选)
|
||||
需要您在店铺开通对应的门店结算能力，既卡券核销一张既结算一张，并且钱会独立结算给核销的门店，需要您的各个门店在快手上绑定，并且有独立的结算账户。金额会按照您配置好的门店结算给独立的门店账户。
|
||||
@@ -0,0 +1,45 @@
|
||||
接口文档
|
||||
更新时间：2025-03-26
|
||||
阅读数：6374
|
||||
API
|
||||
类目 名称 展示名 操作
|
||||
订单 open.order.cursor.list 获取订单列表v2 查看
|
||||
订单 open.seller.order.close 关闭订单 查看
|
||||
订单 open.seller.order.fee.detail 获取订单费用详情 查看
|
||||
订单 open.order.detail 订单详情v2 查看
|
||||
退款 open.seller.order.refund.detail 售后单详情 查看
|
||||
退款 open.seller.order.refund.fee.detail 退款单退款费用详情 查看
|
||||
退款 open.seller.order.refund.approve 商家同意退款 查看
|
||||
退款 open.seller.order.refund.pcursor.list 售后单列表(游标方式) 查看
|
||||
退款 open.seller.order.refund.disagree.refund 商家不同意退款 查看
|
||||
商品 open.item.get 获取商品详情 查看
|
||||
商品 open.item.new 商品新增（新） 查看
|
||||
商品 open.item.edit 编辑商品（新） 查看
|
||||
商品 integration.item.stock.deduct 商品库存扣减 查看
|
||||
商品 integration.item.stock.query 商品库存查询 查看
|
||||
商品 open.item.shelf.status.update 商品上下架管理 查看
|
||||
商品 open.item.list.get 查询商品列表 查看
|
||||
店铺 open.shop.poi.getPoiDetailByOuterPoi 通过图商poi获取快手poi详情 查看
|
||||
虚拟 integration.callback.virtual.eticket.send 电子凭证发货回调接口 查看
|
||||
虚拟 integration.callback.virtual.eticket.consume 电子凭证核销回调接口 查看
|
||||
虚拟 integration.callback.virtual.eticket.reverse 电子凭证冲正回调接口 查看
|
||||
虚拟 integration.callback.virtual.eticket.destroy 电子凭证销毁回调接口 查看
|
||||
虚拟 open.virtual.eticket.checkavailable 电子凭证检查电子凭证是否有效 查看
|
||||
|
||||
|
||||
消息
|
||||
类目 名称 展示名 操作
|
||||
退款 kwaishop_refund_addRefund 新增退款单消息 查看
|
||||
退款 kwaishop_refund_updateRefund 退款单更新消息 查看
|
||||
订单 kwaishop_order_addOrder 订单新增消息 查看
|
||||
订单 kwaishop_order_statusChange 订单状态变更消息 查看
|
||||
订单 kwaishop_order_totalFeeChange 订单费用变更消息 查看
|
||||
订单 kwaishop_order_addNote 订单备注消息 查看
|
||||
SPI
|
||||
类目 名称 展示名 操作
|
||||
虚拟 KwaishopVirtualEticketSendService 快手电子凭证通知发货 查看
|
||||
虚拟 KwaishopVirtualEticketQueryService 电子凭证查询发码结果或券码状态 查看
|
||||
虚拟 KwaishopDigitalETicketDestoryService 电子凭证发起销毁接口 查看
|
||||
|
||||
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 862 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 776 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 274 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 164 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 169 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 292 KiB |
Reference in New Issue
Block a user