# 用API和AI工具管理受保护内容

> 通过BCL API或经MCP连接的AI助手，读取受保护内容和买家，并更改状态、标题和访问规则。
>
> Source: https://docs.bcl.my/zh/protected-content-api/

你可以从自己的系统或AI助手管理受保护内容。BCL API和BCL MCP服务器可以列出你的内容、显示谁有访问权限，以及更改内容的状态、标题和访问规则。创建内容、上传文件和把内容连接到产品，都要在仪表板完成。

## 开始之前

你需要一个API token。在**Platform Setup** → **Integrations**的**API Token**标签页创建。请看[创建API token](/zh/api-tokens/)。

| 用途 | Token权限 |
|---|---|
| 通过API读取内容和买家 | **API Read** |
| 通过API更改内容 | **API Write** |
| 通过MCP使用AI助手 | **MCP Read**，要做更改还需要**MCP Write** |

每个API请求都要发送这些header：

- `Authorization: Bearer <your token>`
- `Accept: application/json`
- 一个写上你App名称的`User-Agent`，例如`KopiKampung/1.0`。使用curl或Python默认user agent的请求会被拒绝。

Base URL是`https://api.bcl.my/v1`。API只能看到token所属团队的内容。

## API endpoint

以下是受保护内容的endpoint：

| Method和路径 | 作用 | 参数 |
|---|---|---|
| `GET /protected-contents` | 列出你的内容 | `search`（标题）、`status`（`active`、`inactive`、`all`）、`content_type`（`video`、`text`、`file`、`redirect`）、`access_type`（`immediate`、`scheduled`、`duration`）、`sort_by`（`title`、`created_at`、`updated_at`）、`sort_order`、`page`、`per_page`（最多100，默认15） |
| `GET /protected-contents/{id}` | 一项内容及其设置和统计：买家、目前可访问人数、总观看次数和下载次数 | - |
| `GET /protected-contents/{id}/customers` | 拥有访问权限的买家 | `status`（`active`、`expired`、`revoked`、`all`）、`page`、`per_page` |
| `PATCH /protected-contents/{id}/status` | 开启或关闭内容 | `is_active`（true或false） |
| `PATCH /protected-contents/{id}/title` | 为内容改名，也可以更改它在访问电邮里的名称 | `title`（必填，最多255个字符）、`email_title` |
| `PATCH /protected-contents/{id}/access` | 更改访问规则 | `access_type`（必填）；`scheduled_start_at`（`scheduled`必填）、`scheduled_end_at`；`access_duration_days`（`duration`必填）；`max_devices`（1或以上）；`max_downloads`；`show_on_receipt` |

`{id}`是列表里的内容ID，也就是内容在仪表板网址里出现的那个代码。响应里的每项内容都有一个`access_url`：内容的Access Finder链接。

例如，关闭一项内容：

```sh
curl -X PATCH "https://api.bcl.my/v1/protected-contents/7XBRVXK4/status" \
  -A "KopiKampung/1.0" \
  -H "Authorization: Bearer $BCL_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'
```

更改成功时，会返回`"success": true`和新的值。如果发送的值已经是当前设置，会返回HTTP 422，例如“The protected content is already inactive.”。未知的ID会返回404“Protected content not found”。

## 注意事项

请记住这些限制：

- **访问权限的更改只适用于新买家**。和仪表板一样，`PATCH .../access`不会更改已有访问权限的人的日期。之后请在内容的**Customer Access**页面使用**Sync Access Dates**。
- **通过API时，`max_devices`必须是1或以上**。要允许无限设备，请在仪表板把**Maximum Devices**设为0。
- **没有给单一买家授予或撤销访问权限的endpoint**。请在仪表板使用**Grant Buyer Access**和其他**Customer Access**操作。

## 使用AI助手（MCP）

BCL MCP服务器让Claude、ChatGPT或Cursor等AI助手使用你的账号。在**Platform Setup** → **Connect AI Agent**设置。以下工具用于受保护内容：

| 工具 | 需要 | 作用等同于 |
|---|---|---|
| `list_protected_contents` | **MCP Read** | `GET /protected-contents` |
| `get_protected_content` | **MCP Read** | `GET /protected-contents/{id}` |
| `get_protected_content_customers` | **MCP Read** | `GET /protected-contents/{id}/customers` |
| `update_protected_content_status` | **MCP Write** | `PATCH .../status` |
| `update_protected_content_title` | **MCP Write** | `PATCH .../title` |
| `update_protected_content_access` | **MCP Write** | `PATCH .../access` |

然后你就可以用日常用语提问，例如“哪些Kopi Kampung课程的买家最多？”或“关闭Live Cupping Session内容”。

## Webhook和自动化里的访问链接

当一笔订单解锁受保护内容时，付款webhook会在每个产品的`protected_content`下列出它，包括内容标题、买家的访问链接（`url`）和`access_finder_url`。自动化也有对应的变量，所以你可以通过WhatsApp把访问链接发给买家。请看[Payment form webhook](/zh/webhook-payment-form/)。

## 常见问题

### 我可以通过API创建受保护内容吗？

暂时不行。API和MCP工具可以读取内容和买家，也可以更改状态、标题和访问权限设置。请在BCL仪表板创建内容，并把它连接到产品。

### 我的系统可以查到谁有某个课程的访问权限吗？

可以。调用GET /protected-contents/{id}/customers。它会返回每位买家的名字、电邮、电话、订单号码、状态、访问日期、观看次数和下载次数。

### 促销活动结束后，我可以叫AI助手帮我关闭内容吗？

可以。用拥有MCP Write的token，通过MCP把助手连接到BCL，然后叫它做。它会使用update_protected_content_status工具。