97 lines
4.2 KiB
Markdown
97 lines
4.2 KiB
Markdown
# 自用型应用获取和刷新 access_token
|
||
|
||
## 1. 接口说明
|
||
* **接口功能**：用于“自用型应用”获取及刷新调用有赞云 API 所需的身份验证凭证（`access_token`）。
|
||
* **前提条件**：已在有赞云控制台完成自用型应用的创建，并且完成了店铺授权。
|
||
* **业务注意**：
|
||
1. 一个店铺只能授权给一个自用型应用，而一个自用型应用可以有多个店铺授权（多店授权需通过有赞云审核）。
|
||
2. 建议开发者在代码中全局捕获 Token 失效的错误码，并实现 `access_token` 失效时自动重新获取的逻辑。
|
||
|
||
---
|
||
|
||
## 2. 请求说明
|
||
* **请求地址**：`https://open.youzanyun.com/auth/token`
|
||
* **请求方式**：`POST`
|
||
* **请求头 (Header)**：`Content-Type: application/json`
|
||
> ⚠️ **注意**：必须严格使用 `POST` 加上 `application/json` 的请求方式，否则会报错。
|
||
|
||
---
|
||
|
||
## 3. 请求参数
|
||
|
||
在请求的 Body（JSON格式）中传入以下参数：
|
||
|
||
| 参数名称 | 类型 | 是否必须 | 示例值 | 描述说明 |
|
||
| :--- | :--- | :---: | :--- | :--- |
|
||
| `client_id` | String | **是** | `239ec70db50cfd...` | 有赞云颁发给开发者的应用 ID [1] |
|
||
| `client_secret` | String | **是** | `9ea25ab4513b7f...` | 有赞云颁发给开发者的应用密钥 (AppSecret) [1] |
|
||
| `authorize_type` | String | **是** | `silent` | 授权方式。自用型应用固定为 `"silent"` [1] |
|
||
| `grant_id` | String | **是** | `123456` | 授权店铺ID（即 `kdt_id`）。如果是API接口对接传店铺ID；如果是支付商户对接传 `mchId` [1] |
|
||
| `refresh` | Boolean | 否 | `false` | 是否需要返回 `refresh_token`。默认为 `false`。如需通过 `refresh_token` 刷新凭证，需传入 `true` [1] |
|
||
|
||
*(注：`client_id`、`client_secret` 和店铺ID `grant_id`，请前往有赞云控制台的应用详情和授权页面查看 [1]。)*
|
||
|
||
---
|
||
|
||
## 4. 响应参数
|
||
|
||
响应主体为 JSON 格式，核心数据包裹在 `data` 节点中：
|
||
|
||
| 参数名称 | 类型 | 描述说明 |
|
||
| :--- | :--- | :--- |
|
||
| `success` | Boolean | 请求是否成功 |
|
||
| `code` | Integer | HTTP 状态码，`200` 表示成功 |
|
||
| `data.access_token` | String | 用于调用业务 API 接口的有效凭证 |
|
||
| `data.expires_in` | Long | `access_token` 的有效时间（单位：秒，通常为 7 天 / 604800秒） |
|
||
| `data.authority_id` | String | 授权店铺的 ID（`kdt_id`） |
|
||
| `data.refresh_token` | String | 用于刷新 `access_token` 的凭证（仅在请求参数 `refresh` 为 `true` 时返回） |
|
||
|
||
---
|
||
|
||
## 5. 请求与响应示例
|
||
|
||
### 5.1 CURL 请求示例 [1]
|
||
```bash
|
||
curl -X POST https://open.youzanyun.com/auth/token \
|
||
-H 'content-type: application/json' \
|
||
-d '{
|
||
"client_id": "YOUR_CLIENT_ID",
|
||
"client_secret": "YOUR_CLIENT_SECRET",
|
||
"authorize_type": "silent",
|
||
"grant_id": "88888",
|
||
"refresh": false
|
||
}'
|
||
```
|
||
|
||
### 5.2 成功响应示例
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"data": {
|
||
"access_token": "f59b1a6bb04f4eqweqd1c6af315d",
|
||
"expires_in": 604800,
|
||
"authority_id": "88888",
|
||
"refresh_token": "c3b21a6bb04f4eqweqd1c6af315d"
|
||
},
|
||
"message": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 🔄 如何刷新 access_token？
|
||
|
||
对于**自用型应用**，有赞云提供了两种刷新/重新获取 token 的策略：
|
||
|
||
### 方式一：直接静默重新获取（推荐做法）
|
||
因为自用型应用采用的是 `silent`（静默）授权模式，无需商家人工干预。因此当 `access_token` 过期时，**直接再次发送和首次获取时完全一样的 POST 请求**（`authorize_type` 依然为 `silent`），即可直接生成并获取到一个全新的 `access_token`。
|
||
|
||
### 方式二：通过 refresh_token 刷新
|
||
1. 在首次获取 token 时，必须将入参的 `refresh` 字段设置为 `true` [2]，此时响应数据中会返回一个 `refresh_token`。
|
||
2. 当 `access_token` 过期后，可以改变请求参数来刷新 Token：
|
||
* 将 `authorize_type` 的值修改为 `"refresh_token"` [2]
|
||
* 增加传递 `"refresh_token": "你获取到的refresh_token字符串"` [2]
|
||
* 仍然携带 `client_id` 和 `client_secret` [2]
|
||
|
||
*(建议：业务中采取在 Redis / 本地缓存中托管 Token 及到期时间，在到期前提前 10-30 分钟使用方式一重新拉取即可。)* |