> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建 Channel QR Session

> 为 Channel 创建短生命周期扫码授权会话。

`POST /api/v1/forward/channels/{channel_id}/qr_sessions`

创建 QR session，用于激活或重新绑定支持扫码授权的 Channel。

## 请求头

| Header          | 是否必填 | 说明             |
| --------------- | ---- | -------------- |
| Authorization   | 是    | `Bearer <PAT>` |
| Idempotency-Key | 否    | 有副作用请求可选的幂等键。  |

## 路径参数

| 参数          | 类型     | 是否必填 | 说明          |
| ----------- | ------ | ---- | ----------- |
| channel\_id | string | 是    | Channel ID。 |

## 请求体

可省略请求体，也可以发送空 JSON 对象 `{}`。

## 示例请求

```bash theme={null}
curl -s -X POST 'https://api.qoder.com/api/v1/forward/channels/channel_019eabc123/qr_sessions' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## 示例响应

**HTTP 200 OK**

```json theme={null}
{
  "session_key": "qr-a1b2c3d4",
  "channel_id": "channel_dingtalk-001",
  "channel_type": "dingtalk",
  "status": "waiting",
  "qr_code_content": "https://login.dingtalk.com/oauth2/...",
  "qr_code_image_base64": "data:image/png;base64,...",
  "expires_at": "2026-06-18T10:05:00Z",
  "poll_interval_seconds": 2
}
```

## 响应字段

| 字段                      | 类型      | 说明                                      |
| ----------------------- | ------- | --------------------------------------- |
| session\_key            | string  | 用于轮询状态的不透明 QR session key。              |
| channel\_id             | string  | 关联的 Channel ID。                         |
| channel\_type           | string  | `wechat`、`feishu`、`dingtalk` 或 `wecom`。 |
| status                  | string  | 初始状态，通常为 `waiting`。                     |
| qr\_code\_content       | string  | 二维码原始内容，通常是三方授权 URL。                    |
| qr\_code\_image\_base64 | string  | 服务端生成的二维码图片。                            |
| expires\_at             | string  | 过期时间。                                   |
| poll\_interval\_seconds | integer | 建议轮询间隔。                                 |

## 错误

| HTTP | Type                    | Code                       | 触发条件                |
| ---- | ----------------------- | -------------------------- | ------------------- |
| 400  | `invalid_request_error` | `channel_type_unsupported` | 渠道类型不支持 QR session。 |
| 404  | `not_found_error`       | `channel_not_found`        | Channel 不存在。        |
| 409  | `conflict_error`        | `channel_disabled`         | Channel 已停用。        |
| 502  | `api_error`             | `channel_auth_failed`      | 三方渠道授权失败。           |
| 401  | `authentication_error`  | `authentication_required`  | PAT 无效或已过期。         |

## 注意事项

* 当前 QR session 支持 `wechat`、`feishu`、`dingtalk` 和 `wecom`。
* `qq` 当前不支持统一 QR session。
* 请求体可省略或发送 `{}`。

## 相关

<CardGroup cols={2}>
  <Card title="获取 Channel QR Session" icon="arrows-rotate" href="/cloud-agents/api/forward/channels/get-qr-session" />

  <Card title="获取 Channel" icon="file-lines" href="/cloud-agents/api/forward/channels/get" />
</CardGroup>