# 自用型应用获取和刷新 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 分钟使用方式一重新拉取即可。)*