## 获取设备码和二维码内容

### 基本信息

| 属性         | 内容                               |
|:-----------|:---------------------------------|
| 接口名称       | 获取设备码和二维码内容                    |
| 接口版本       | v1.0                             |
| 接口路径       | /authDeviceCode                  |
| 请求方法       | POST                             |
| 接口状态       | 生产环境                             |

### 接口说明

该接口用于 OAuth 2.0 + PKCE 手机扫码授权流程的第一步，获取设备码和二维码内容。此模式适用于无后端服务的第三方客户端，无需提供 AppSecret。

第三方客户端需要根据响应中的 `data.qrcode` 生成二维码，供 115 客户端扫码授权。

### 接口地址

```
https://passportapi.115.com/open/authDeviceCode
```

### 请求方式

```
POST
Content-Type: application/x-www-form-urlencoded
```

### 认证方式

```
OAuth 2.0 + PKCE
```

### 请求参数

| 参数名                  | 类型     | 必填 | 默认值 | 说明                              | 约束/示例                                                      |
|:---------------------|:-------|:---|:----|:--------------------------------|:-----------------------------------------------------------|
| client_id            | string | 是  | -   | AppID                           | `YOUR_APP_ID`                                              |
| code_challenge       | string | 是  | -   | PKCE 挑战码                        | `THHodGWg-FZfv8XYz7QArNGIK_aVomSHPldlSOTUtkw`              |
| code_challenge_method | string | 是  | -   | `code_challenge` 的哈希算法，见下方枚举表格 | `sha256`                                                   |

#### 请求参数中的 code_challenge_method 字段枚举

| 值      | 说明                         | 备注 |
|:-------|:---------------------------|:---|
| md5    | 使用 MD5 计算挑战码               | -  |
| sha1   | 使用 SHA-1 计算挑战码             | -  |
| sha256 | 使用 SHA-256 计算挑战码，推荐使用      | -  |

### 请求示例

```shell
curl 'https://passportapi.115.com/open/authDeviceCode' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=YOUR_APP_ID' \
  --data-urlencode 'code_challenge=THHodGWg-FZfv8XYz7QArNGIK_aVomSHPldlSOTUtkw' \
  --data-urlencode 'code_challenge_method=sha256'
```

### 响应字段说明

| 字段         | 类型   | 描述                                        |
|:-----------|:-----|:------------------------------------------|
| state      | int  | 状态码                                       |
| code       | int  | 错误码                                       |
| message    | string | 响应信息                                    |
| data       | object | 响应数据                                    |
| data.uid   | string | 设备码，轮询二维码状态时使用                         |
| data.time  | int    | 校验时间戳，轮询二维码状态时使用                       |
| data.qrcode | string | 二维码内容，第三方客户端需要据此生成设备二维码                |
| data.sign  | string | 校验签名，轮询二维码状态时使用                         |

### 响应示例

```json
{
  "state": 1,
  "code": 0,
  "message": "",
  "data": {
    "uid": "DEVICE_CODE_PLACEHOLDER",
    "time": 0,
    "qrcode": "QRCODE_CONTENT_PLACEHOLDER",
    "sign": "SIGN_PLACEHOLDER"
  }
}
```

### 注意事项

- `code_verifier` 为长度 43 至 128 位的随机字符串。
- `code_challenge` 的计算方式为 `url_safe(base64_encode(hash(code_verifier)))`。哈希结果按二进制数据参与 Base64 编码，算法需要与 `code_challenge_method` 一致。
- AppID 等应用凭证请使用实际应用配置，不要在公开仓库或日志中记录敏感凭证。

### 修改历史

| 修改时间                         | 修改说明 |
|:-----------------------------|:-----|
| 2025年04月01日(周二) 00:00:00 | 创建文档 |