7.9 KiB
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权限