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