自用型应用获取和刷新 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]

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 成功响应示例

{
    "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 刷新

在首次获取 token 时，必须将入参的 refresh 字段设置为 true [2]，此时响应数据中会返回一个 refresh_token。
当 access_token 过期后，可以改变请求参数来刷新 Token：
- 将 authorize_type 的值修改为 "refresh_token" [2]
- 增加传递 "refresh_token": "你获取到的refresh_token字符串" [2]
- 仍然携带 client_id 和 client_secret [2]

(建议：业务中采取在 Redis / 本地缓存中托管 Token 及到期时间，在到期前提前 10-30 分钟使用方式一重新拉取即可。)

4.2 KiB Raw Blame History Unescape Escape