应用授权

本指南详细介绍了应用程序使用 OAuth 授权的流程，包括了每个步骤的具体实现方式、安全性措施以及可能遇到的常见问题和解决方法。

OAuth 流程​

SHOPLINE 使用 OAuth 2.0 授权流程 来颁发 Access Token，以授权应用程序访问商家店铺数据。 OAuth 授权流程方便商家授权给应用程序，从而允许应用程序获取访问其店铺数据的权限。例如，店铺可以授权给应用程序访问订单和商品数据的权限。 下图展示了基于商家、应用程序和 SHOPLINE 之间的 OAuth 流程：

1. 商家请求安装应用程序。
2. 应用程序重定向到 SHOPLINE，在商家的浏览器加载 OAuth 授权页面，该页面展示了应用程序申请的权限范围。
3. 商家同意应用程序所请求的权限范围。
4. 应用程序的回调地址收到授权码（code），这是 OAuth 授权的临时凭证，需要进行签名验证。
5. 应用程序向 SHOPLINE 发送请求以获取访问令牌（Access Token）。
6. SHOPLINE 在身份验证后颁发访问令牌。现在，应用程序可以使用访问令牌请求 SHOPLINE API 获取数据了。

第一步：App 授权前置检查​

获取在创建应用程序时获得的 AppKey 和 AppSecret。这些客户端凭据在授权过程中用于识别你的应用程序身份。 获取应用程序的客户端凭据，请按以下步骤操作：

1. 登录你的 SHOPLINE 合作伙伴后台。
2. 点击“应用”选项。
3. 选择你想要检索其客户端凭据的应用程序名称。
4. 查看“应用凭据”部分。
5. 查看或复制你的 AppKey 和 AppSecret。

接入授权前，请先确认应用是否为如下类型：

1. 公共应用。
2. 自定义应用。

第二步：App 验证安装请求​

当商家请求安装应用时，SHOPLINE 会访问你配置的应用地址，并携带请求安装的店铺标识、时间戳、AppKey 和签名。

GET   https://{appUrl}?appkey={appkey}&handle={handle}&lang={lang}&timestamp={timestamp}&sign={sign}

SHOPLINE 的请求会携带以下参数：

如果是内嵌应用（内嵌在 SHOPLINE admin 后台的应用都为内嵌应用），则请求还会携带以下参数：

在这时，你收到安装请求后，需要依次做以下判断：

第三步：App 请求授权码​

如果店铺需要进行授权，则应用程序需要重定向到 SHOPLINE，并在商家的浏览器中加载 OAuth 授权页面，该页面将展示应用程序请求商家权限的范围。

你可以重定向到以下地址：

GET   https://{handle}.myshopline.com/admin/oauth-web/#/oauth/authorize?appKey={appKey}&responseType=code&scope={scope}&redirectUri={redirectUri}

这些参数必须包含在请求中：

你还可以在请求中包含这些参数：

第四步：商家验证并授权访问​

在 SHOPLINE 向应用程序提供授权码之前，会对商家进行身份验证，商家需要登录到 SHOPLINE Admin 后台

成功登录后，SHOPLINE 将商家重定向到授权页，以审批授予该应用程序的权限范围。 如果商家之前已经批准了这些权限范围，则无需再次审批。

第五步：App 收到授权码​

商家批准了应用程序申请的权限范围后，SHOPLINE 将商家重定向到第三步中传递的 redirectUri。App 在收到请求后，需要验证签名，然后再通过 code 获取 access token。

GET   https://{redirectUri}?appkey={appkey}&code={code}&customField={customField}&handle={handle}&timestamp={timestamp}&sign={sign}

SHOPLINE 的请求会携带以下参数：

如果是内嵌应用还将包含以下参数：

第六步：App 请求 Access Token​

如果以上步骤都执行完，你可以通过向商店端点发送请求获取 Access Token，在请求 body 中携带第五步收到的授权码。

POST    https://{handle}.myshopline.com/admin/oauth/token/create
Header  content-type: application/json
            appkey: {appkey}
            timestamp: {timestamp}
            sign: {sign}
Body     {"code":{code}}

SHOPLINE 对该接口有限流要求，因此应用程序不能连续为同一个店铺获取 Access Token。同时，应避免在获取 Access Token 后立即进行刷新操作。 请求必须携带以下参数：

第七步：App 收到 Access Token​

SHOPLINE 在验证签名后，会以 JSON 格式返回带有 Access Token 的响应。

{
	"code": 200,
	"i18nCode": "SUCCESS",
	"message": null,
	"data": {
		"accessToken": {accessToken},
		"expireTime": {expireTime},
		"scope": {scope}
	},
	"traceId":{traceId}
}

响应包含以下参数：

你可能会收到以下错误码：

第八步：App 请求刷新 Access Token​

为了确保商家数据的安全，Access Token 有效期为 10 小时。如果商店已安装你的应用程序，你可以在 Access Token 过期时请求更新，以换取新的有效 Access Token。

POST    https://{handle}.myshopline.com/admin/oauth/token/refresh
Header  content-type: application/json
            appkey: {appkey}
            timestamp: {timestamp}
            sign: {sign}

请求必须携带以下参数：

第九步：App 收到新的 Access Token​

SHOPLINE 在验证签名后，将以 JSON 格式返回带有新 Access Token 的响应。

{
	"code": 200,
	"i18nCode": "SUCCESS",
	"message": null,
	"data": {
		"accessToken": {accessToken},
		"expireTime": {expireTime},
		"scope": {scope}
	},
	"traceId":{traceId}
}

响应包含这些参数：

你可能会收到以下错误码：

第十步：App 更改授予的权限范围（可选）​

基于业务的发展，在已经有商家安装应用程序的情况下，你仍然可能希望更改权限范围。例如，你之前可能仅请求了 read_products 权限，但随后你需要增加 read_orders 权限。

要更改权限范围，你可以将商家重定向到第三步的授权页。如果你的应用程序是内嵌的，则你必须使用 App-Bridge 提供的 重定向 功能来帮助你实现重定向。