增加文档与图片
This commit is contained in:
yml2213
@@ -0,0 +1,396 @@
|
||||
2.OAuth2的code授权流程及接口简介
|
||||
2.1 code授权流程
|
||||
|
||||
|
||||
授权流程可以简单归纳为：
|
||||
1.获取授权码code（步骤1234）；
|
||||
2.授权码code换取长时令牌refreshToken以及短时访问令牌accessToken（步骤56），使用accessToken调用电商授权API（步骤789）；
|
||||
3.若短时访问令牌accessToken过期，则使用长时令牌refreshToken刷新短时访问令牌accessToken，再使用新的accessToken进行调用。
|
||||
|
||||
下面将详细介绍每一步的调用过程及用到的接口
|
||||
|
||||
2.2 获取授权码code
|
||||
授权页面地址示例：https://open.kwaixiaodian.com/oauth/authorize?app_id=xxx&redirect_uri=xxx&scope=xxx,xxx&response_type=code&state=xxx
|
||||
|
||||
使用说明：
|
||||
1、若应用为”商家后台””快分销”“快赚客”自研应用，需要现在应用的测试用户或授权用户列表中添加用户后，用户打开授权页面完成授权；
|
||||
2、若应用为第三方ISV应用，需要上架到服务市场，用户需在服务市场订购了服务完成授权。
|
||||
|
||||
页面参数说明:
|
||||
|
||||
参数名
|
||||
|
||||
是否必须
|
||||
|
||||
描述
|
||||
|
||||
app_id
|
||||
|
||||
是
|
||||
|
||||
应用的 appKey
|
||||
|
||||
response_type
|
||||
|
||||
是
|
||||
|
||||
授权的类型，默认为"code"
|
||||
|
||||
scope
|
||||
|
||||
是
|
||||
|
||||
APP已经拥有且需要获取用户授权的权限包，多个用 “,” 连接，比如merchant_item。可至“应用中心-APP详情页”查看APP已获得的权限包列表，平台所有权限包见下文
|
||||
|
||||
redirect_uri
|
||||
|
||||
是
|
||||
|
||||
授权成功的回调uri，为APP在创建时填写的回调地址
|
||||
|
||||
state
|
||||
|
||||
否
|
||||
|
||||
状态值，成功授权后回调时会原样带回
|
||||
|
||||
如果授权成功，授权服务器会将用户的浏览器重定向到应用 ：http(s)://redirect_uri?code=CODE&state=STATE
|
||||
|
||||
参数名
|
||||
|
||||
参数类型
|
||||
|
||||
是否必须
|
||||
|
||||
code
|
||||
|
||||
string
|
||||
|
||||
用来换取access_token 的授权码，有效期为 2 分钟且只能使用一次，在用户首次允许授权时返回
|
||||
|
||||
state
|
||||
|
||||
string
|
||||
|
||||
如果请求时传递参数，会回传该参数
|
||||
|
||||
2.3 用授权码code换取长时令牌refreshToken以及访问令牌accessToken
|
||||
请求地址: https://openapi.kwaixiaodian.com/oauth2/access_token ** 此接口为后端接口**
|
||||
|
||||
请求方法: GET
|
||||
|
||||
请求参数:
|
||||
|
||||
参数名
|
||||
|
||||
是否必须
|
||||
|
||||
描述
|
||||
|
||||
app_id
|
||||
|
||||
是
|
||||
|
||||
开发者appKey
|
||||
|
||||
grant_type
|
||||
|
||||
是
|
||||
|
||||
授权的类型，"code"
|
||||
|
||||
code
|
||||
|
||||
是
|
||||
|
||||
2.2中获取到的code
|
||||
|
||||
app_secret
|
||||
|
||||
是
|
||||
|
||||
开发者的appSecret
|
||||
|
||||
正确返回值:
|
||||
|
||||
参数名
|
||||
|
||||
描述
|
||||
|
||||
result
|
||||
|
||||
返回结果类型，1为正确，其他为不正确
|
||||
|
||||
access_token
|
||||
|
||||
临时访问令牌，作为调用授权API时的入参，过期时间为expires_in值，授权用户、app和权限组范围唯一决定一个access_token值
|
||||
|
||||
refresh_token
|
||||
|
||||
长时访问令牌，默认为180天，授权用户、app和权限组范围唯一决定一个refresh_token值
|
||||
注意：refresh_token值不需要存储固定值，因access_token48小时过期时间内需要用长时令牌refreshToken刷新访问令牌accessToken，每次刷新会换取新的refreshToken
|
||||
|
||||
open_id
|
||||
|
||||
用户对该开发者的唯一身份标识
|
||||
|
||||
expires_in
|
||||
|
||||
access_token过期时间，单位秒，默认为172800，即48小时
|
||||
|
||||
scopes
|
||||
|
||||
本次授权中，用户允许的授权权限范围，即access_token和refresh_token中包含的scopes
|
||||
|
||||
异常返回值：
|
||||
|
||||
参数名
|
||||
|
||||
描述
|
||||
|
||||
result
|
||||
|
||||
返回结果类型，详情查看本文错误码简介
|
||||
|
||||
error
|
||||
|
||||
错误类型
|
||||
|
||||
error_msg
|
||||
|
||||
错误详情，用于提示具体的错误原因
|
||||
|
||||
2.4 用长时令牌refreshToken刷新访问令牌accessToken
|
||||
当access_token 过期时，可以使用(在有效期内的) refresh_token重新获取新的access_token，不需要显式的用户授权过程，若refresh_token也过期了，则需要再次经过用户授权，因此需要关注refresh_token的时效（默认180天），需要在时效内用此接口再换取新的refresh_token才不会出现用户授权频繁失效的情况。该接口只支持authorization_code模式获取access_token 刷新，刷新得到新的access_token 和refresh_token, 旧的refresh_token 随即在5分钟内失效。
|
||||
|
||||
使用子账号的refreshToken刷新accessToken时以下情况会报错：1、子账号被禁用、删除或状态不可用；2、子账号的主账号和APP不存在授权关系。
|
||||
|
||||
当且仅当子账号状态可用，且子账号的主账号和APP存在授权关系时，才可正确获取到子账号的accessToken。
|
||||
|
||||
请求地址: https://openapi.kwaixiaodian.com/oauth2/refresh_token ** 此接口为后端接口**
|
||||
|
||||
请求方法: POST
|
||||
|
||||
请求参数:
|
||||
|
||||
参数名
|
||||
|
||||
是否必须
|
||||
|
||||
描述
|
||||
|
||||
grant_type
|
||||
|
||||
是
|
||||
|
||||
授权的类型，必须是"refresh_token"
|
||||
|
||||
refresh_token
|
||||
|
||||
是
|
||||
|
||||
长时访问令牌，默认为180天，2.3接口中返回的值
|
||||
|
||||
app_id
|
||||
|
||||
是
|
||||
|
||||
开发者 appId
|
||||
|
||||
app_secret
|
||||
|
||||
是
|
||||
|
||||
开发者的appSecret
|
||||
|
||||
正确返回值:
|
||||
|
||||
参数名
|
||||
|
||||
描述
|
||||
|
||||
result
|
||||
|
||||
返回结果类型，1为正确，其他为不正确
|
||||
|
||||
access_token
|
||||
|
||||
临时访问令牌，作为调用授权API时的入参，过期时间为expires_in值
|
||||
|
||||
expires_in
|
||||
|
||||
access_token过期时间，单位秒，默认为172800，即48小时
|
||||
|
||||
refresh_token
|
||||
|
||||
长时访问令牌，默认为180天，会返回新的refresh_token，原有的refresh_token即失效
|
||||
注意：refresh_token值不需要存储固定值，因access_token48小时过期时间内需要用长时令牌refreshToken刷新访问令牌accessToken，每次刷新会换取新的refreshToken
|
||||
|
||||
refresh_token_expires_in
|
||||
refresh_token 的过期时间，单位秒，默认为180天
|
||||
|
||||
scopes
|
||||
access_token包含的scope
|
||||
|
||||
异常返回值：
|
||||
|
||||
参数名
|
||||
|
||||
描述
|
||||
|
||||
result
|
||||
|
||||
返回结果类型，详情查看本文错误码简介
|
||||
|
||||
error
|
||||
|
||||
错误类型
|
||||
|
||||
error_msg
|
||||
|
||||
错误详情，用于提示具体的错误原因
|
||||
|
||||
|
||||
|
||||
===
|
||||
4.授权错误码简介
|
||||
result
|
||||
|
||||
error
|
||||
|
||||
异常描述
|
||||
|
||||
100200100
|
||||
|
||||
invalid_request
|
||||
|
||||
缺少必要的请求参数
|
||||
|
||||
100200101
|
||||
|
||||
unauthorized_client
|
||||
|
||||
app 非法，例如 开发者不存在，app 不存在或状态不正确等
|
||||
|
||||
100200102
|
||||
|
||||
access_denied
|
||||
|
||||
请求被拒绝，授权和后续API，访问中出现任何的Token 错误都会返回这个异常，存在三种可能
|
||||
invalid refresh_token 无效token
|
||||
refreshToken.discarded refreshToken已经用过，不能重复使用
|
||||
refreshToken.revokedAuthorization 用户已经撤销授权
|
||||
|
||||
100200103
|
||||
|
||||
unsupported_response_type
|
||||
|
||||
responseType 错误
|
||||
|
||||
100200104
|
||||
|
||||
unsupported_grant_type
|
||||
|
||||
换取accessToken 使用的grantType 错误
|
||||
|
||||
100200105
|
||||
|
||||
invalid_grant
|
||||
|
||||
换取accessToken 使用的 code 错误
|
||||
|
||||
100200106
|
||||
|
||||
invalid_scope
|
||||
|
||||
权限 scope 错误，或者用户取消了授权等
|
||||
|
||||
100200107
|
||||
|
||||
invalid_openid
|
||||
|
||||
用户的 openid 无效
|
||||
|
||||
100200500
|
||||
|
||||
server_error
|
||||
|
||||
服务器内部错误，开发者侧无法处理
|
||||
|
||||
|
||||
|
||||
5.权限组列表
|
||||
权限组用于控制APP调用API和接受消息的权限范围，只有当APP拥有该API所属的权限组才可以调用API，只有当APP拥有该消息所属的权限组才可以消费消息，列表中说明了现有的权限组以及对应的权限组的API和消息。快手电商开放平台会根据开发者创建的应用类型授予默认的权限组，若开发者需要申请额外的权限组，请发邮件到open@kuaishou.com并说明理由。
|
||||
|
||||
Scope
|
||||
|
||||
描述
|
||||
|
||||
备注
|
||||
|
||||
user_base
|
||||
|
||||
授权之后的默认权限
|
||||
|
||||
所有应用默认拥有此权限组
|
||||
|
||||
user_info
|
||||
|
||||
用户基本信息
|
||||
|
||||
所有应用默认拥有此权限组
|
||||
|
||||
merchant_user
|
||||
|
||||
商家用户信息
|
||||
|
||||
用户API权限
|
||||
|
||||
merchant_item
|
||||
|
||||
读取或更新店铺的商品数据
|
||||
|
||||
商品API和商品消息权限
|
||||
|
||||
merchant_order
|
||||
|
||||
读取或更新店铺的订单信息
|
||||
|
||||
订单API和订单消息权限
|
||||
|
||||
merchant_refund
|
||||
|
||||
读取或更新店铺的售后信息
|
||||
|
||||
退款单API和退款单消息权限
|
||||
|
||||
merchant_distribution
|
||||
|
||||
读取或更新分销信息
|
||||
|
||||
分销API权限
|
||||
|
||||
merchant_logistics
|
||||
|
||||
读取或更新物流信息
|
||||
|
||||
物流API权限
|
||||
|
||||
merchant_promotion
|
||||
|
||||
读取或更新营销信息
|
||||
|
||||
营销API权限
|
||||
|
||||
merchant_cs
|
||||
|
||||
读取或更新店铺的客服信息
|
||||
|
||||
客服API权限
|
||||
|
||||
merchant_comment
|
||||
|
||||
读取或更新店铺的评价信息 评价API权限
|
||||
merchant_servicemarket
|
||||
|
||||
获取应用在服务市场的订购信息 服务市场API权限
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 362 KiB |
@@ -0,0 +1,309 @@
|
||||
方案介绍
|
||||
更新时间：2025-03-26
|
||||
阅读数：21079
|
||||
1.业务介绍
|
||||
快手平台提供了凭证发送和核销能力，给有线上发码及线下消费的交易商家提供服务。码商可以通过入驻快手小店及电商开放平台，给快手商家提供电子凭证的发送以及核销的服务。目前快手整体提供了三种电子凭证的对接能力
|
||||
|
||||
1.快手发码和核销：此种方式无需ISV对接，联系我们的快手电子平台运营同学，即可接入，这种方式属于接入最快的方式。所有券码的生命周期由快手平台负责，商家可以自定义券的应用场景，有效期等。【平台发码产品使用手册（可忽略门店管理）】
|
||||
|
||||
2.码库发码、快手核销：商家可以通过excel导入已有的券码，核销由快手平台核销，这种方式也无需ISV对接，但是需要商家手动把外部二维码导入。【码库发码产品使用手册（可忽略门店管理）】
|
||||
|
||||
3.商家发码和核销：这种方式下由商家系统自己负责发码，并且将码的副本信息同步给快手平台，双方共同管理券码的生命周期，本方案主要介绍这种接入方式。
|
||||
|
||||
4. 新开发的跨门店结算/按卡券结算能力/poi接入的相关细节可以查看对接实践
|
||||
|
||||
|
||||
|
||||
名词解释
|
||||
发码方式：用户购买后商家通过某种方式把卡券发送给用户，目前快手支持3种发码方式：商家发码、码库发码、快手平台发码
|
||||
|
||||
i、商家发码：商家通过对接收单和发码2个接口，当用户购买商品后，快手会「推送订单给商家」，以及商家必须在超时时效内「回调发码的结果」给快手
|
||||
|
||||
ii、码库发码：商家需提前准备一批「未核销」的卡券，上传到快手小店的「码库」中。当用户购买商品后，快手会自动从「码库」中选择一个「未核销」的卡券发给用户。无需商家对接「发码接口」
|
||||
|
||||
iii、快手平台发码：商家无需提前准备卡券，由快手侧自动生成唯一的卡券发给用户。缺点是这批卡券是快手生成的，商家系统是不存在这些卡券的，所以不支持商家核销，只能在快手内核销
|
||||
|
||||
|
||||
|
||||
核销方式：用户收到卡券后可以通过不同方式核销掉，目前快手支持2中核销方式：商家核销、快手核销
|
||||
|
||||
i、商家核销：用户收到卡券后，拿着卡券去商家系统进行核销，核销完成后商家需回传核销状态给快手，快手驱动卡券状态到『已核销』。商家需要对接『核销回调接口』
|
||||
|
||||
ii、快手核销（非自动）：商家使用快手商家版APP或者快手小店后台「券码工具箱」，对用户卡券进行核销。核销后快手会驱动卡券状态到『已核销』。商家无需对接核销接口
|
||||
|
||||
iii、自动核销（只发不核）：用户的卡券发放成功后，快手会自动核销，适用于少数业务场景。该核销方式必须同步给快手小二并获得其同意，方可配置。商家无需对接核销接口
|
||||
|
||||
|
||||
|
||||
关单：商家在指定的发码时间内，未进行发码回调。快手先调用商家的查询接口，如果查询到券码，报警人工处理。如果查询不到券码，才会调用销毁接口通知商家进行关单。
|
||||
|
||||
i、查询接口：超过24h（不同业务，超时时间不同）商家还未发码回调，快手定时任务会触发查询发码结果的操作，商家只能返回2种错误码「4012002-订单不存在」「 4012005-卡券不存在」，详见错误码规范
|
||||
|
||||
ii、发起销毁接口：当快手「查询接口」识别到商家返回的是上面2种指定的「关单错误码」，快手侧会调用「发起销毁接口」通知商家关单。商家必须要同意销毁「result=1」，快手才会关单并退款
|
||||
|
||||
|
||||
|
||||
常用对接场景
|
||||
商家发商家核：只能商家发码且商家主动核销，商家需要对接「发码」和「核销」接口，对应下文的方案A 。
|
||||
|
||||
只发不核：发码后自动核销，无需用户主动去「商家系统」或者「快手系统」核销。只发不核模式容易产生大量客诉，需要小二谨慎评估才可以使用该功能。包括：商家发码自动核销、码库发码自动核销、快手平台发码自动核销，统称为「只发不核」
|
||||
|
||||
|
||||
|
||||
快手已支持的链路
|
||||
发码方式 \ 核销方式 商家核销 快手核销（非自动） 自动核销【只发不核】（需加白才能开通）
|
||||
商家发码 支持 不支持 支持
|
||||
码库发码 支持 支持 支持
|
||||
快手平台发码 不支持 支持 支持
|
||||
|
||||
|
||||
订单和卡券状态
|
||||
动作 订单状态 卡券状态
|
||||
用户支付成功 已支付/待发货（30） 无
|
||||
商家发码成功 已发货（40） 未使用
|
||||
商家核销成功 已签收（50） 已使用
|
||||
核销成功 + N天，用户无异议推动订单完成（结算货款） 交易完成（70） 已使用
|
||||
商家超时未发码（默认24h内需发货） 交易失败（80） 无
|
||||
卡券到期未核销（过期自动退场景） 交易失败（80） 已销毁
|
||||
用户主动申请退款（支持退款场景） 交易失败（80） 已销毁
|
||||
|
||||
|
||||
2.接入评估
|
||||
2.1 目标用户
|
||||
面向拥有自研能力可以发码的商家，可以和平台进行对接并将数据同步，双方共同管理券码的生命周期
|
||||
|
||||
2.2 接入评估
|
||||
评估点 评估等级 评估内容 默认 备注信息
|
||||
售卖类目 高 放在哪个类目下？有哪些资质 运营决策 商家和快手小二沟通清楚售卖类目
|
||||
售后规则 高
|
||||
随时退过期退：未使用状态下，支持用户主动申请。卡券未使用状态下，过期会自动退款
|
||||
|
||||
过期自动退：不支持用户主动申请退款。卡券未使用状态下，过期会自动退款
|
||||
|
||||
不可退：卡券不关心是否使用，都不支持退款
|
||||
|
||||
已商家实际业务为准，不可以随意选择
|
||||
商品发品示例如下，不支持其他售后规则，比如：不支持「7天无理由退款」。
|
||||
|
||||
|
||||
|
||||
发码方式 高
|
||||
【商家发码、码库发码、快手平台发码】
|
||||
|
||||
商家发码：商家通过对接接口进行发码
|
||||
|
||||
码库发码：商家在快手小店先导入券码，发品的时候绑定码库。如果用户购买了该商品，那么快手会从该商品绑定的码库里面选择一个「可用」券码发给用户
|
||||
|
||||
快手平台发码：商家无需做任何操作，快手会随机生成券码然后发给用户
|
||||
|
||||
已商家实际业务为准，不可以随意选择
|
||||
建议联系运营小二，做正确评估。商品发品示例：
|
||||
|
||||
|
||||
|
||||
核销方式 高
|
||||
商家核销、快手核销、自动核销（只发不核）
|
||||
|
||||
商家核销：用户在快手站外核销，然后商家必须通过对接接口把核销状态同步给快手
|
||||
|
||||
快手核销：商家可以在快手小店-商品-券码工具箱，操作核销
|
||||
|
||||
自动核销（只发不核）：特殊业务场景，卡券发了之后不能退还，需发码即核销。容易产生客诉，运营小二会严格审核
|
||||
|
||||
商家核销
|
||||
建议联系产品、运营同学做完整接入的评估
|
||||
|
||||
|
||||
|
||||
技术对接方案 高 参考2.4节，有5种方案可选 默认方案A（商家发码、商家核销）
|
||||
核销方式在哪 中 扫码核销、网页核销、电话核销等，说清楚 扫码核销 商家描述清楚用户卡券核销全链路
|
||||
是否需要支持实体卡 低 实体卡、虚拟卡 虚拟卡，目前已不支持实体卡 仅大闸蟹业务支持实体卡
|
||||
是否会冻结资金 低 是、否 否
|
||||
一单一份发一张码还是多张码？ 低 一单一码、一单多码 一单一码
|
||||
购买时一单一件，发「一张卡券」
|
||||
|
||||
购买时一单多件，发「多张卡券」
|
||||
|
||||
快手不支持次卡（一张卡券只能核销一次）
|
||||
|
||||
结算方式 低 结算时间、结算周期、起结金额等
|
||||
1. 首张核销+N天结算
|
||||
2. 全部核销+N天结算
|
||||
3. 卡券核销+N天按卡券独立结算给门店(跨门店结算) 全部核销后+7天 不支持商家定制
|
||||
退款方式 低 部分退、整单退 整单退
|
||||
发码账号类型 低 用户填写的账号类型，比如：手机号 手机号 目前只支持手机号
|
||||
卡号形式 低 卡券号、卡密，或者两者都有 仅卡券号
|
||||
- 卡密（卡号 + 卡密）只支持在「商家发码」方式下
|
||||
|
||||
- 卡号（仅卡号）3种方式都支持
|
||||
|
||||
是否需要展示二维码 低 二维码用卡券号还是卡密等 卡券号二维码 - 只发不核默认不展示二维码
|
||||
是否需要支持撤销核销（冲正） 低 是、否，一般撤销核销配合预约核销功能使用 否
|
||||
是否有独立品牌和资质 低 自有品牌，代理品牌，无品牌等 自有品牌
|
||||
基于以上评估，选择哪个对接方案 方案A、方案B、方案C、方案D、方案E 方案A
|
||||
|
||||
2.3 评估模板示例
|
||||
售卖类目：游戏充值类目
|
||||
发码方式：商家发码
|
||||
核销方式：自动核销（只发不核）
|
||||
核销方式在哪：游戏内部充值入口
|
||||
支持实体卡：否
|
||||
冻结资金：否
|
||||
一单一码：一单一码
|
||||
退款方式：不支持七天无理由退款、产品质量问题整单退
|
||||
是否需要展示二维码：不需要
|
||||
卡号形式：仅卡号
|
||||
是否过期退：不支持
|
||||
是否有独立品牌和资质：是，有独立品牌及资质
|
||||
选择对接方案：方案E
|
||||
|
||||
|
||||
|
||||
2.4 方案对比
|
||||
接口
|
||||
方案A (推荐方案)
|
||||
|
||||
(商家发码，商家核销)
|
||||
|
||||
方案B
|
||||
|
||||
(商家发码，快手退款)
|
||||
|
||||
方案C
|
||||
|
||||
(快手码库发码，商家核销)
|
||||
|
||||
方案D (推荐方案)
|
||||
|
||||
(快手平台全托管)
|
||||
|
||||
方案E（只发不核）
|
||||
|
||||
(需要和运营沟通，只支持代金卡密类目)
|
||||
|
||||
优点：方案最成熟，功能最完善，接入后券码由isv生成，可以自己定制逻辑，券码生命周期保持跟快手平台同步，并且可以自动化处理退款和券码。
|
||||
|
||||
缺点：接口数量相对较多
|
||||
|
||||
接口数量：8-13个
|
||||
|
||||
优点：在接入方案A的基础之上做减法，只保留基础的发码功能
|
||||
|
||||
缺点：退款需要在卖家后台处理，主播带货场景需要大量客服小二处理退款，容易造成退款不及时
|
||||
|
||||
接口数量：6个
|
||||
|
||||
优点：接入速度最快，仅需接入2个接口，完全由快手平台负责券码的生命周期
|
||||
|
||||
缺点：不支持卡密
|
||||
|
||||
接口数量：2个
|
||||
|
||||
优点：快手平台发码/码库发码，无需开发，运营配置即可使用
|
||||
|
||||
缺点：无法定制化，完全依赖快手平台已有能力，不支持卡密
|
||||
|
||||
接口数量：0个
|
||||
|
||||
优点：只需要接入发码、查询、销毁接口
|
||||
|
||||
缺点：接入限制多，要和运营沟通确认
|
||||
|
||||
接口数量：3
|
||||
|
||||
是否需要开发
|
||||
|
||||
|
||||
|
||||
电子凭证通知发码接口
|
||||
|
||||
integration.virtual.eticket.send
|
||||
|
||||
是 是 否 否 是
|
||||
电子凭证发码回调
|
||||
integration.callback.virtual.eticket.send
|
||||
是 是 否 否 是
|
||||
订单新增消息
|
||||
|
||||
kwaishop_order_addOrder
|
||||
|
||||
或
|
||||
|
||||
获取订单列表v2
|
||||
|
||||
open.order.cursor.list
|
||||
|
||||
可选 可选 否 否 可选
|
||||
新增退款单消息 kwaishop_refund_addRefund
|
||||
|
||||
或
|
||||
|
||||
售后单列表(游标方式) open.seller.order.refund.pcursor.list
|
||||
|
||||
是 否 否 否 否
|
||||
商家同意/不同意退款接口
|
||||
|
||||
open.seller.order.refund.approve
|
||||
|
||||
open.seller.order.refund.disagree.refund
|
||||
|
||||
是 否 否 否 否
|
||||
商家超时未发码，快手发起关单接口
|
||||
|
||||
或
|
||||
|
||||
卡券过期，快手发起销毁接口
|
||||
|
||||
integration.virtual.eticket.destroy
|
||||
|
||||
是 是
|
||||
否
|
||||
|
||||
否
|
||||
|
||||
是
|
||||
电子凭证销毁回调接口
|
||||
|
||||
integration.callback.virtual.eticket.destroy
|
||||
|
||||
是 是 否 否 否
|
||||
电子凭证查询接口
|
||||
|
||||
integration.virtual.eticket.query
|
||||
|
||||
是 是 否 否 是
|
||||
电子凭证冲正回调接口
|
||||
|
||||
integration.callback.virtual.eticket.reverse
|
||||
|
||||
可选 可选 可选 否 否
|
||||
电子凭证核销回调接口
|
||||
|
||||
integration.callback.virtual.eticket.consume
|
||||
|
||||
是 是 是 否 否
|
||||
电子凭证检查电子凭证是否有效
|
||||
|
||||
open.virtual.eticket.checkavailable
|
||||
|
||||
可选 可选 是 否 否
|
||||
通过图商poi获取快手poi详情
|
||||
|
||||
open.shop.poi.getPoiDetailByOuterPoi
|
||||
|
||||
可选 可选 可选 可选 可选
|
||||
商品新增
|
||||
|
||||
open.item.new
|
||||
|
||||
可选 可选 可选 可选 可选
|
||||
商品上下架管理
|
||||
|
||||
open.item.shelf.status.update
|
||||
|
||||
可选 可选 可选 可选 可选
|
||||
商品库存扣减
|
||||
|
||||
integration.item.stock.deduct
|
||||
|
||||
可选 可选 可选 可选 可选
|
||||
@@ -0,0 +1,46 @@
|
||||
对接流程
|
||||
更新时间：2025-03-26
|
||||
阅读数：9606
|
||||
1.对接流程
|
||||
参考案例，
|
||||
|
||||
可见：https://docs.qingque.cn/d/home/eZQBvJqHNtsz2N14vyTrUe_BH?identityId=Ci9gpanFbu#section=h.747sjcxfqui
|
||||
|
||||
自主测试平台：
|
||||
|
||||
https://gw-merchant-staging.test.gifshow.com/tool/micro
|
||||
|
||||
|
||||
|
||||
2.对接准备
|
||||
商家入驻—开放平台入驻—商品发布—绑定收款账户—联调测试—账单对账，需要按步骤完成所有的对接准备工作，即可进行技术对接
|
||||
|
||||
2.1.商家入驻
|
||||
完成在快手小店的入驻，成为快手商家，详情请见商家入驻：《企业店铺入驻手册-商家侧》
|
||||
https://s.kwaixiaodian.com/
|
||||
|
||||
|
||||
|
||||
2.2 开发者入驻
|
||||
完成在快手电商开放平台的入驻，成为商家开发者，详情请见：《开放平台入驻指南》
|
||||
|
||||
成为开发者后，创建商家后台应用，详情请见：《开放平台应用开发》，应用创建完成后申请虚拟类目权限
|
||||
|
||||
https://open.kwaixiaodian.com/
|
||||
|
||||
|
||||
|
||||
2.3 发布商品
|
||||
商品发布：《虚拟商品发布手册》
|
||||
|
||||
https://s.kwaixiaodian.com/zone/goods/config/release/add
|
||||
|
||||
|
||||
|
||||
2.4 绑定账户
|
||||
绑定收款账户以及短账期：商家收款账户绑定
|
||||
|
||||
需要确定俩个账户都绑定成功，才可以进行第六步
|
||||
|
||||
2.5 账单对账
|
||||
账单对账：PC账单使用说明 如需系统对账，请单独联系我们产研同学接口
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 822 KiB |
@@ -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