# Urus kandungan dilindungi melalui API & tool AI

> Baca kandungan dilindungi dan pembelinya, dan tukar status, tajuk dan peraturan aksesnya melalui API BCL atau AI agent melalui MCP.
>
> Source: https://docs.bcl.my/ms/protected-content-api/

Anda boleh mengurus kandungan dilindungi dari sistem anda sendiri atau pembantu AI. API BCL dan server MCP BCL menyenaraikan kandungan anda, menunjukkan siapa yang ada akses, dan menukar status, tajuk dan peraturan akses sesuatu kandungan. Mencipta kandungan, upload fail dan link kandungan kepada item dibuat dalam dashboard.

## Sebelum anda mula

Anda memerlukan API token. Cipta satu di bawah **Platform Setup** → **Integrations**, pada tab **API Token**. Lihat [Cipta API token](/ms/api-tokens/).

| Kegunaan | Kebenaran token |
|---|---|
| Baca kandungan dan pembeli melalui API | **API Read** |
| Tukar kandungan melalui API | **API Write** |
| AI agent melalui MCP | **MCP Read**, dan **MCP Write** untuk membuat perubahan |

Hantar header ini bersama setiap request API:

- `Authorization: Bearer <your token>`
- `Accept: application/json`
- `User-Agent` yang menamakan aplikasi anda, contohnya `KopiKampung/1.0`. Request dengan user agent default curl atau Python ditolak.

Base URL ialah `https://api.bcl.my/v1`. API hanya nampak kandungan team yang memiliki token itu.

## Endpoint API

Ini ialah endpoint kandungan dilindungi:

| Method dan path | Fungsinya | Parameter |
|---|---|---|
| `GET /protected-contents` | Menyenaraikan kandungan anda | `search` (tajuk), `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` (sehingga 100, default 15) |
| `GET /protected-contents/{id}` | Satu kandungan dengan tetapan dan statistiknya: pembeli, yang boleh akses sekarang, jumlah tontonan dan download | - |
| `GET /protected-contents/{id}/customers` | Pembeli yang ada akses | `status` (`active`, `expired`, `revoked`, `all`), `page`, `per_page` |
| `PATCH /protected-contents/{id}/status` | On-kan atau off-kan kandungan | `is_active` (true atau false) |
| `PATCH /protected-contents/{id}/title` | Menukar nama kandungan, dan jika mahu, namanya dalam e-mel akses | `title` (wajib, sehingga 255 aksara), `email_title` |
| `PATCH /protected-contents/{id}/access` | Menukar peraturan akses | `access_type` (wajib); `scheduled_start_at` (wajib untuk `scheduled`), `scheduled_end_at`; `access_duration_days` (wajib untuk `duration`); `max_devices` (1 atau lebih); `max_downloads`; `show_on_receipt` |

`{id}` ialah ID kandungan dari senarai, iaitu kod yang sama seperti dalam alamat dashboard kandungan itu. Setiap kandungan dalam respons ada `access_url`: link Access Finder kandungan itu.

Contohnya, untuk off-kan sesuatu kandungan:

```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}'
```

Perubahan yang berjaya memulangkan `"success": true` dengan nilai baru. Menghantar nilai yang sudah ditetapkan memulangkan HTTP 422, contohnya "The kandungan dilindungi is already inactive." ID yang tidak dikenali memulangkan 404 "Kandungan dilindungi not found".

## Perkara yang perlu anda tahu

Ingat had berikut:

- **Perubahan akses digunakan untuk pembeli baru.** Sama seperti dalam dashboard, `PATCH .../access` tidak menukar tarikh orang yang sudah ada akses. Guna **Sync Access Dates** pada page **Customer Access** kandungan itu selepas itu.
- **`max_devices` mesti 1 atau lebih melalui API.** Untuk membenarkan peranti tanpa had, tetapkan **Maximum Devices** kepada 0 dalam dashboard.
- **Tiada endpoint untuk memberi atau membatalkan akses seorang pembeli.** Guna **Grant Buyer Access** dan tindakan **Customer Access** yang lain dalam dashboard.

## Guna AI agent (MCP)

Server MCP BCL membolehkan pembantu AI seperti Claude, ChatGPT atau Cursor berfungsi dengan akaun anda. Sediakannya di bawah **Platform Setup** → **Connect AI Agent**. Tool berikut meliputi kandungan dilindungi:

| Tool | Perlukan | Sama seperti |
|---|---|---|
| `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` |

Anda kemudian boleh bertanya dalam bahasa biasa, contohnya "Kursus Kopi Kampung mana yang paling banyak pembeli?" atau "Off-kan kandungan Live Cupping Session".

## Link akses dalam webhook & automasi

Apabila sesuatu pesanan membuka akses kepada kandungan dilindungi, webhook bayaran menyenaraikannya di bawah `protected_content` setiap item, dengan tajuk kandungan, link akses pembeli (`url`) dan `access_finder_url`. Automasi ada variable yang sepadan, jadi anda boleh menghantar link akses pembeli melalui WhatsApp. Lihat [Payload webhook payment form](/ms/webhook-payment-form/).

## Isu biasa

### Boleh saya cipta kandungan dilindungi melalui API?

Belum boleh. API dan tool MCP membaca kandungan dan pembeli, dan menukar status, tajuk dan tetapan akses. Cipta kandungan itu dan link kepada item dalam dashboard BCL.

### Boleh sistem saya mengetahui siapa yang ada akses kepada sesuatu kursus?

Boleh. Panggil GET /protected-contents/{id}/customers. Ia memulangkan nama, e-mel, telefon, nombor pesanan, status, tarikh akses, jumlah tontonan dan download setiap pembeli.

### Boleh saya minta pembantu AI off-kan kandungan saya selepas promosi tamat?

Boleh. Sambungkan pembantu itu kepada BCL melalui MCP dengan token yang ada MCP Write, dan minta ia berbuat demikian. Ia menggunakan tool update_protected_content_status.