# 📺 Получить список воспроизведения

Этот API предоставляет функции аутентификации и создания плейлистов для XC_VM. Клиенты могут аутентифицироваться с помощью имени пользователя/пароля или токена, после чего генерируется персонализированный плейлист.

---

## 📚 Навигация

- [📂 Расположение файла](#расположение-файла)
- [🔑 Аутентификация](#аутентификация)
- [🚀 Конечные точки](#конечные-точки)
- [❌ Коды ошибок](#коды-ошибок)
- [🧾 Примечания](#примечания)

---

## 📂 Расположение файла

Playlist API обрабатывается `PlaylistApiController`:

```
src/public/Controllers/Api/PlaylistApiController.php
```

---

## 🔑 Аутентификация

API требует аутентификацию либо через имя пользователя и пароль, либо через токен. Это обеспечивает безопасность доступа к контенту.

### Базовый URL

```http
http://<ваш-домен>:80/playlist
```

---

## 🚀 Конечные точки

### 1. Аутентификация и создание плейлиста

**Метод и конечная точка:**

```http
GET /
```

**Параметры запроса:**

| Параметр   | Тип      | Требуется | Описание |
|------------|----------|-----------|----------|
| username  | string   | Yes*     | Имя пользователя для аутентификации (обязательно, если не используется `token`). |
| password  | string   | Yes*     | Пароль для аутентификации (требуется, если `token` не используется). |
| token     | string   | Yes*     | Токен аутентификации (требуется, если имя пользователя и пароль не используются). |
| type      | string   | No       | Тип устройства (по умолчанию: `m3u_plus`). |
| key       | string   | No       | Тип контента (live — прямой эфир, movies — фильмы, radio_streams — радио, series — сериалы). |
| output    | string   | No       | Формат вывода (hls или m3u). |
| nocache   | boolean  | No       | Если true, отключается кэширование. |

> 💡 *Yes* — обязательно один из вариантов: либо username/password, либо token.

**Примеры запросов:**

```bash
curl -X GET "http://<your-domain>:80/playlist/username/password/type&output=hls&key=live"
```

```bash
curl -X GET "http://<your-domain>:80/playlist/token/type&output=hls&key=live"
```

**Ответ:**

- Файл плейлиста в указанном формате (M3U или HLS).

---

## ❌ Коды ошибок

В случае ошибок API возвращает соответствующие коды для диагностики проблем.

| Код ошибки              | Описание |
|-------------------------|----------|
| NO_CREDENTIALS         | Отсутствуют данные аутентификации. |
| INVALID_CREDENTIALS    | Неверное имя пользователя, пароль или токен. |
| BLOCKED_USER_AGENT     | Агент пользователя заблокирован. |
| EXPIRED                | Срок действия учетной записи истек. |
| DEVICE_NOT_ALLOWED     | Тип устройства не разрешен. |
| BANNED                 | Пользователь заблокирован. |
| DISABLED               | Учетная запись отключена. |
| EMPTY_USER_AGENT       | Агент пользователя необходим, но отсутствует. |
| NOT_IN_ALLOWED_IPS     | IP-адрес не разрешен. |
| NOT_IN_ALLOWED_COUNTRY | Страна не разрешена. |
| NOT_IN_ALLOWED_UAS     | Агент пользователя не разрешен. |
| ISP_BLOCKED            | Провайдер заблокирован. |
| ASN_BLOCKED            | Применено ограничение ASN. |
| DOWNLOAD_LIMIT_REACHED | Слишком много запросов. |
| GENERATE_PLAYLIST_FAILED | Не удалось сгенерировать список воспроизведения. |

> ⚠️ **Совет:** Проверьте логи сервера для дополнительных деталей при возникновении ошибок.

---

## 🧾 Примечания

- **Параметры запроса:** Убедитесь, что все параметры указаны корректно, чтобы избежать ошибок аутентификации.
- **Ограничения:** API применяет фильтры по агенту пользователя, IP-адресу и стране для повышения безопасности.
- **Защита от перегрузки:** Установлены лимиты на количество запросов, чтобы предотвратить чрезмерную нагрузку на сервер.
- **Рекомендации:** Для тестирования используйте инструменты вроде cURL или Postman. В продакшене интегрируйте с вашим приложением для автоматизированной генерации плейлистов.

> 💬 Если возникнут вопросы по интеграции, создайте issue в [репозитории](https://github.com/Vateron-Media/XC_VM/issues).

---