---
url: /docs/api-docs/v1/admin/channels.md
---
# channel — 支付/分发渠道（5 action）

> 前缀：`/api/v1/admin/channel/`
> 权限：`CHANNEL_READ`（list/detail）· `CHANNEL_WRITE`（set-config/switch/close — close 高敏感）— 仅 **super + it**，operator 一律 403
> 代码：`src/app/admin/interface/api/channel_mgmt.py` + `application/usecase/channel_mgmt.py`

## 3.10.1 list —— 渠道列表

`GET /api/v1/admin/channel/list` · 权限 `CHANNEL_READ`

**Query 参数**：

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `page` | int | ⬜ | 1 | ≥1 |
| `page_size` | int | ⬜ | 20 | 1~100 |
| `type` | string | ⬜ | — | 渠道类型（非法值 → `40201001`） |
| `status` | string | ⬜ | — | 渠道状态（非法值 → `40201001`） |

**响应 data**：`{ total, page, page_size, items: [ChannelSummary] }`

`ChannelSummary` 字段：

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` / `name` | string | 渠道 / 名称 |
| `type` | string | 渠道类型 |
| `status` | string | `active` | `inactive` | `closed` |
| `request_count` | int | 请求计数（流量指向观测） |
| `created_at` | string | ISO |

**错误码**：`40201001` page/page\_size < 1 / type/status 非法。

## 3.10.2 detail —— 渠道详情

`GET /api/v1/admin/channel/detail/{channel_id}` · 权限 `CHANNEL_READ`

**响应 data**：

| 字段 | 类型 | 说明 |
|---|---|---|
| `channel` | object | 全字段（含 `migration_strategy`） |
| `integration_config` | object | 接入配置 |
| `stats` | object | 业务统计 |

**错误码**：`40201721`（404）渠道不存在。

## 3.10.3 set-config —— 更新渠道配置

`POST /api/v1/admin/channel/set-config` · 权限 `CHANNEL_WRITE`

**请求 body**：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `channel_id` | string | ✅ | 目标渠道 |
| `config_key` | string | ✅ | 配置键 |
| `config_value` | any | ⬜ | 配置值 |

**响应 data**：`{ "success": true }`

**错误码**：`40201721`（404）· `40201723` 渠道已关闭（不可再改配置）· `40201001` 参数非法。

## 3.10.4 switch —— 渠道切换（流量迁移）

`POST /api/v1/admin/channel/switch` · 权限 `CHANNEL_WRITE`

**请求 body**：

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `from_channel_id` | string | ✅ | — | 源渠道（切为 inactive） |
| `to_channel_id` | string | ✅ | — | 目标渠道（切为 active） |
| `migration_strategy` | string | ⬜ | `immediate` | 迁移策略 |

**响应 data**：`{ "success": true, "migration_status": "<status>" }`

**错误码**：

| code | 场景 |
|---|---|
| `40201721` | 渠道不存在（404） |
| `40201722` | 切换失败（同渠 / 源渠道不可用） |
| `40201723` | 渠道已关闭 |
| `40201001` | 参数非法 |

**验收链路（§7.5）**：`switch` 旧渠道（active→inactive）→ 新渠道（→active）→ list 流量指向断言 + audit。

## 3.10.5 close —— 关闭渠道（⚠️ 高敏感）

`POST /api/v1/admin/channel/close` · 权限 `CHANNEL_WRITE` · **confirm\_text = `"CLOSE"`**

**请求 body**：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `channel_id` | string | ✅ | 目标渠道 |
| `reason` | string | ✅ | 关闭原因 |
| `effective_at` | string | null | ⬜ | 生效时间（ISO；缺省立即） |
| `confirm_text` | string | ✅ | **必须逐字为 `"CLOSE"`**，否则 `40201001`（400） |

**响应 data**：`{ "success": true }`

**错误码**：`40201721`（404）· `40201723` 重复关闭 · `40201001` confirm\_text 不匹配 / 参数非法。

***

**本域错误码汇总**：`40201721`-`40201723`（§6.9 channel 区段）。通用失败见 [admin 总览](/api-docs/v1/admin/)。