# 开放型应用（OAuth2.0授权码模式） ### 一、阅读前提 1. 本篇介绍开放型应用（OAuth2.0授权码模式）下如何获取调用凭证（access_token）。 2. 开放型应用下的调用凭证（access_token）失效时间为`30天`、刷新凭证（refresh_token）失效时间为`35天`。调用凭证（access_token）请在临期前，定时通过刷新凭证（refresh_token）进行刷新。若刷新凭证（refresh_token）已失效，只能重新进行授权行为获取相关凭证。 3. 开放型应用每台打印机设备的终端号（machine_code）每日获取次数为20次，避免超出范围、受限。建议数据存储或者缓存。 4. 开放型应用的调用凭证（access_token）只与它绑定的打印机设备（machine_code）有效（access_token与machine_code绑定）。 5. 重新获取或刷新access_token后，旧的access_token将在两小时内失效。因此，请确保及时替换为最新获取的access_token。 6. 关于接口域名、签名等信息，请详读[调用协议](调用协议.md) ### 二、拼接授权地址 #### 接口信息 |协议|方式|地址 |-|-|-| |https|GET|/oauth/authorize #### 请求参数 |名称|类型|必填|描述 |-|-|-|-|-| |client_id|string|是|应用id |response_type|string|是|授权类型，默认值`code` |redirect_uri|string|是|回调地址（应用设置中查看） |state|string|是|自定义参数，回调时与终端号的授权码code一起返回 #### 授权地址示例 ```text https://open-api.10ss.net/oauth/authorize?client_id=xxxx&response_type=code&state=aaa&redirect_uri=https://xxxx ``` ### 三、授权接口 #### 接口信息 |协议|方式|地址 |-|-|-| |https|POST|/oauth/oauth #### 请求参数 |名称|类型|必填|描述 |-|-|-|-|-| |client_id|string|是|应用id |grant_type|string|是|默认值`authorization_code` |sign|string|是|签名 |scope|string|是|权限范围，默认值`all` |timestamp|int|是|时间戳（秒） |id|string|是|请求唯一标识码 |code|string|是|终端号的授权码 #### 响应参数 |名称|类型|描述 |-|-|-|-| |error|int|成功0，其他为异常 |error_description|string|提示信息 |timestamp|int|时间戳（秒） |body|json|数据 #### body 字段示例 ```json { "client_id": "10******24", "access_token": "0a***************a4", "refresh_token": "76***************85", "machine_code": "400*******", "expires_in": 2592000, "refresh_expires_in": 3024000, "scope": "all" } ``` #### body 字段说明 |名称|类型|空|描述 |-|-|-|-| |client_id|string|否|应用id |access_token|string|否|授权凭证 |refresh_token|string|否|刷新凭证 |machine_code|string|否|终端号 |expires_in|string|否|调用凭证有效时间（秒） |refresh_expires_in|string|否|刷新凭证有效时间（秒） |scope|string|否|权限范围 ### 四、刷新授权接口 #### 接口信息 |协议|方式|地址 |-|-|-| |https|POST|/oauth/oauth #### 请求参数 |名称|类型|必填|描述 |-|-|-|-|-| |client_id|string|是|应用id |grant_type|string|是|默认值`refresh_token` |sign|string|是|签名 |scope|string|是|权限范围，默认值`all` |timestamp|int|是|时间戳（秒） |id|string|是|请求唯一标识码 |refresh_token|string|是|刷新凭证 #### 响应参数 |名称|类型|描述 |-|-|-|-| |error|int|成功0，其他为异常 |error_description|string|提示信息 |timestamp|int|时间戳（秒） |body|json|数据 #### body 字段示例 ```json { "client_id": "10******24", "access_token": "0a***************a4", "refresh_token": "76***************85", "machine_code": "400*******", "expires_in": 2592000, "refresh_expires_in": 3024000, "scope": "all" } ``` #### body 字段说明 |名称|类型|空|描述 |-|-|-|-| |client_id|string|否|应用id |access_token|string|否|授权凭证 |refresh_token|string|否|刷新凭证 |machine_code|string|否|终端号 |expires_in|string|否|调用凭证有效时间（秒） |refresh_expires_in|string|否|刷新凭证有效时间（秒） |scope|string|否|权限范围