---
title: "应用授权"

doc_type: static
doc_category: static
doc_version: v20270301
source_url:
  html: 'https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/app-authorization'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/app-authorization.md'
---
# 应用授权
本指南详细介绍了应用程序使用 OAuth 授权的流程，包括了每个步骤的具体实现方式、安全性措施以及可能遇到的常见问题和解决方法。

## OAuth 流程
SHOPLINE 使用 [OAuth 2.0 授权流程](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1) 来颁发 Access Token，以授权应用程序访问商家店铺数据。
OAuth 授权流程方便商家授权给应用程序，从而允许应用程序获取访问其店铺数据的权限。例如，店铺可以授权给应用程序访问订单和商品数据的权限。
下图展示了基于商家、应用程序和 SHOPLINE 之间的 OAuth 流程：

![授权机制-中文版.png](https://s2cdn.myshopline.com/slfs/op-new/171629970172097/授权机制-中文版.png)

1. 商家请求安装应用程序。
2. 应用程序重定向到 SHOPLINE，在商家的浏览器加载 OAuth 授权页面，该页面展示了应用程序申请的权限范围。
3. 商家同意应用程序所请求的权限范围。
4. 应用程序的回调地址收到授权码（code），这是 OAuth 授权的临时凭证，需要进行[签名验证](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md?lang=zh-hans-cn)。
5. 应用程序向 SHOPLINE 发送请求以获取访问令牌（Access Token）。
6. SHOPLINE 在身份验证后颁发访问令牌。现在，应用程序可以使用访问令牌请求 SHOPLINE API 获取数据了。

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

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

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

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

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

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

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

| **参数** | **描述** |
| --- | --- |
| appkey | 应用唯一标识。 |
| handle | 店铺唯一标识，店铺域名前缀，如：open001.myshopline.com 的 handle 为：open001。 |
| timestamp | 时间戳，毫秒级。 |
| sign | 安全签名，算法：[HMAC-SHA256](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md?lang=zh-hans-cn)。 |

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

| **参数** | **描述** |
| --- | --- |
| lang | 账户语言，商家在 SHOPLINE Admin 后台当前设定的语种，支持的语种包括：<li>`zh-hans-cn`：简体中文</li><li>`zh-hant-tw`：繁体中文</li><li>`en`：英语</li><li>`ms`：马来语</li><li>`vi`：越南</li><li>`th`：泰语</li><li>`id`：印尼语</li><li>`ja`：日语</li> |

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

![App验证安装请求.png](https://s2cdn.myshopline.com/slfs/op-new/171629903914299/App验证安装请求.png)

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


> **tip**
>
> 当店铺已经授权且授权范围（scope）没有变化时，即使应用程序发起授权码请求，SHOPLINE 也会跳过授权页的展示。


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

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

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

| **参数** | **作用描述** |
| --- | --- |
| handle | 表示你将为该店铺安装 App，通常与第二步传递给你 App 的 handle 一致。 |
| appKey | 应用唯一标识，告知 SHOPLINE 该店铺需要安装此 App。 |
| responseType | 授权方式，授予授权码流程传 code。 |
| scope | 权限范围，当申请多个权限时，用英文逗号拼接，如：read_products,read_orders。SHOPLINE 支持的 scope 请参见[权限点列表](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/access-scope.md) |
| redirectUri | 商家授权 App 后重定向的 URL，需要与 SHOPLINE 合作伙伴后台配置的应用回调地址的其中一个一致即可。该字段值需要 url encode 编码。 |

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

| 参数 | 描述 |
| --- | --- |
| customField | 自定义字段，该字段会在回调时透传给你指定的redirectUri，需要 url encode 编码。 |

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

![SHOPLINE.jpg](https://s2cdn.myshopline.com/slfs/op-new/171629977432109/SHOPLINE.jpg)

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

![image4.png](https://s2cdn.myshopline.com/slfs/op-new/171629984444496/image4.png)


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

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

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

| 参数 | 描述 |
| --- | --- |
| appkey | 应用唯一标识。 |
| code | OAuth 2.0 授权码，10 分钟内过期。 |
| customField | 自定义字段，你在第三步传递的字段。 |
| handle | 店铺唯一标识，店铺域名前缀，如：open001.myshopline.com 的 handle 为：open001。 |
| timestamp | 时间戳，毫秒级。 |
| sign | 安全签名，算法：[HMAC-SHA256](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md?lang=zh-hans-cn)。 |

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

| **参数** | **描述** |
| --- | --- |
| lang | 账户语言，商家在 SHOPLINE Admin 后台当前设定的语种，支持的语种包括：<li>`zh-hans-cn`：简体中文</li><li>`zh-hant-tw`：繁体中文</li><li>`en`：英语</li><li>`ms`：马来语</li><li>`vi`：越南</li><li>`th`：泰语</li><li>`id`：印尼语</li><li>`ja`：日语</li> |

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

```html
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 后立即进行刷新操作。
请求必须携带以下参数：

| 参数 | 描述 |
| --- | --- |
| handle | 店铺唯一标识，店铺域名前缀，如：open001.myshopline.com 的 handle 为：open001。 |
| appkey | 应用唯一标识。|
| timestamp | 发起请求时的时间戳，毫秒级。 |
| sign | 安全签名，需要根据请求参数重新计算签名，算法：[HMAC-SHA256](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md?lang=zh-hans-cn)。 |
| code | OAuth 2.0 授权码，10 分钟内过期。 |

## 第七步：App 收到 Access Token
SHOPLINE 在验证签名后，会以 JSON 格式返回带有 Access Token 的响应。

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

响应包含以下参数：

| 参数 | 描述 |
| --- | --- |
| code | 请求状态码，会返回 200 表示请求成功、500 表示请求失败 |
| i18nCode | 请求错误码，需要关注返回 500 时的错误码 |
| message | 错误描述 |
| accessToken | 授权令牌，10 小时内有效期。如需保持长期有效，请继续第八步。 |
| expireTime | 授权令牌到期时间，**yyyy-MM-dd'T'HH:mm:ss.SSSXXX** 格式零时区时间 |
| scope | 拥有的 API 权限范围，SHOPLINE 支持的 scope 请参见[权限点列表](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/access-scope.md) |
| traceId | 请求的全局唯一标识符。用于追踪请求在系统中的流转，以便于问题发生时进行定位和调试。 |

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

| 错误码 | 描述 |
| --- | --- |
| REQUEST_FREQUENTLY | 请求被限流，请稍后再试 |
| OAUTH_CODE_INVALID | 授权码失效，App 需要重新获取授权码 |
| STORE_INFORMATION_ERROR | 店铺信息异常，请稍后再试 |
| REQUEST_NOT_IN_APP_IP_WHITELIST | 非法 IP 请求，请检查 SHOPLINE 合作伙伴后台配置的 IP 白名单 |
| TOKEN_CREATE_EXCEPTION | 创建 Access Token 异常，请稍后再试 |

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

> **warning**
>
> 注意：SHOPLINE 对该接口实施了有限流控制，因此应用程序不可连续更新 Access Token。

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

请求必须携带以下参数：

| 参数 | 描述 |
| --- | --- |
| handle | 店铺唯一标识，店铺域名前缀，如：open001.myshopline.com 的 handle 为：open001。 |
| appkey | 应用唯一标识。 |
| timestamp | 发起请求时的时间戳，毫秒级。 |
| sign | 安全签名，需要根据请求参数重新计算签名，算法：[HMAC-SHA256](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md?lang=zh-hans-cn)。 |

## 第九步：App 收到新的 Access Token
SHOPLINE 在验证签名后，将以 JSON 格式返回带有新 Access Token 的响应。

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

响应包含这些参数：

| 参数 | 描述 |
| --- | --- |
| code | 请求状态码，会返回 200 表示请求成功、500 表示请求失败 |
| i18nCode | 请求错误码，需要关注返回 500 时的错误码 |
| message | 错误描述 |
| accessToken | 授权令牌，10 小时有效期。如需保持长期有效，请继续第八步。 |
| expireTime | 授权令牌到期时间，**yyyy-MM-dd'T'HH:mm:ss.SSSXXX** 格式零时区时间 |
| scope | 拥有的API权限范围 |
| traceId | 请求的全局唯一标识符。用于追踪请求在系统中的流转，以便于问题发生时进行定位和调试。 |

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

| 错误码 | 描述 |
| --- | --- |
| REQUEST_FREQUENTLY | 请求被限流，请稍后再试 |
| STORE_NOT_INSTALL_APP | 店铺未安装此 App，需要跳转到第三步重新授权 |
| APP_AUDIT_NOT_PASS | App 未审核通过，请在 SHOPLINE 合作伙伴后台提交审核 |
| REQUEST_NOT_IN_APP_IP_WHITELIST | 非法 IP 请求，请检查 SHOPLINE 合作伙伴后台配置的 IP 白名单 |
| TOKEN_REFRESH_EXCEPTION | 刷新 Access Token 异常，请稍后再试 |

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

要更改权限范围，你可以将商家重定向到第三步的授权页。如果你的应用程序是内嵌的，则你必须使用 App-Bridge 提供的 [重定向](https://developer.shopline.com/zh-hans-cn/docs/apps/development-tool/app-bridge/actions/routing.md) 功能来帮助你实现重定向。