Управление абонентами¶

Абоненты (subscribers) — это конечные пользователи вашего IPTV-сервиса, которые получают доступ к просмотру телевизионных каналов. Система Catena обеспечивает гибкое управление абонентами, их подписками на пакеты каналов и контроль доступа.

Что такое абонент¶

Абонент в Catena — это учётная запись пользователя, который имеет доступ к просмотру каналов через подключённые пакеты.

Основные возможности:

Аутентификация по SMS — основной способ входа абонентов через код, отправленный на телефон
Управление подписками — подключение и отключение пакетов каналов
Контроль доступа — автоматическое управление доступом к каналам на основе подписок
Токены воспроизведения — уникальные токены для авторизации при просмотре
Мониторинг активности — отслеживание сеансов просмотра и активности абонентов

Типичный workflow:

Создать учётную запись абонента с указанием телефона
Подключить пакеты каналов к абоненту
Абонент получает SMS с кодом для входа в приложение
После входа абонент получает доступ ко всем каналам из своих пакетов
Система автоматически управляет правами доступа на основе активных подписок

Основные параметры абонента¶

Технические параметры¶

Идентификатор абонента (Subscriber ID)

Автоматически генерируется при создании абонента
Формат: base64-кодированный Snowflake ID с заменой символов +/= на -_.
Пример: aKl9SW3AAAE.
Используется для программного доступа через API
Не редактируется после создания

ID портала (Portal ID)

Идентификатор портала, к которому принадлежит абонент
Автоматически устанавливается при создании
Абонент может получать доступ только к каналам и пакетам своего портала

Личные данные¶

Имя абонента (Name)

Отображаемое имя или идентификатор пользователя
Может быть ФИО, никнеймом или идентификатором из внешней системы
Используется для отображения в интерфейсе управления
Примеры: "Иван Петров", "user123", "Apartment 42"

Номер телефона (Phone)

Номер телефона абонента без кода страны
Используется для аутентификации через SMS — основного способа входа
Только цифры, без пробелов и специальных символов
Паттерн валидации: ^[0-9]*$
Примеры: 9161234567, 234567890

Код страны (Phone Country Code)

Код страны телефона без знака плюс
Используется вместе с полем phone для формирования полного номера
Только цифры
Паттерн валидации: ^[0-9]*$
Примеры: 7 (Россия), 1 (США), 44 (Великобритания)

Полный номер телефона формируется как: +{phoneCountryCode}{phone}

Пример: phoneCountryCode: "7" + phone: "9161234567" = +79161234567

Параметры доступа¶

Токен воспроизведения (Playback Token)

Уникальный токен для авторизации при воспроизведении видео
Генерируется автоматически системой
Используется streaming-сервером для проверки прав доступа
Передаётся в приложение после успешной аутентификации
Может быть регенерирован при необходимости

Список пакетов (Packages)

Массив идентификаторов пакетов каналов, к которым подключён абонент
Поле только для чтения — отображает текущие активные подписки
Обновляется автоматически при подключении/отключении пакетов
Определяет, к каким каналам абонент имеет доступ
Пример: ["pKl9SW3AAAE.", "bKl9SW3AAAE."]

Аутентификация абонентов¶

Вход по SMS (основной способ)¶

Catena использует аутентификацию через SMS как основной способ входа абонентов. Это обеспечивает:

Простоту использования — не нужно запоминать пароли
Безопасность — одноразовые коды, привязанные к телефону
Удобство — быстрая регистрация и вход
Защита от мошенничества — телефон как фактор аутентификации

Процесс входа по SMS:

Абонент вводит номер телефона в приложении
Система отправляет SMS с одноразовым кодом на указанный номер
Абонент вводит код из SMS в приложении
Система проверяет код и выдаёт токен доступа
Абонент получает доступ к просмотру каналов из своих пакетов

Важно: Номер телефона является уникальным идентификатором абонента в системе. Убедитесь, что номера указаны корректно при создании учётных записей.

Автоматическое создание абонентов¶

Система может автоматически создавать учётные записи абонентов при первой попытке входа через SMS, если такая функция включена в настройках портала. Это позволяет реализовать самостоятельную регистрацию пользователей.

Создание абонента¶

Через веб-интерфейс¶

Откройте раздел "Абоненты" в панели управления Catena
Нажмите кнопку "Создать абонента"
Заполните обязательные поля:
Name — имя или идентификатор абонента
Phone Country Code — код страны (например, 7 для России)
Phone — номер телефона без кода страны
Сохраните абонента
Подключите пакеты через раздел управления подписками

После создания абонент получит уникальный ID и сможет войти в систему через SMS.

Через Management API¶

curl -X POST https://your-catena-domain.com/tv-management/api/v1/subscribers \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Иван Петров",
    "phoneCountryCode": "7",
    "phone": "9161234567"
  }'

Ответ:

{
  "subscriberId": "sKl9SW3AAAE.",
  "portalId": "pKl9SW3AAAE.",
  "name": "Иван Петров",
  "phoneCountryCode": "7",
  "phone": "9161234567",
  "playback_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "packages": []
}

Просмотр списка абонентов¶

Через веб-интерфейс¶

В разделе "Абоненты" отображается таблица со всеми абонентами портала:

Имя — имя или идентификатор абонента
Телефон — полный номер телефона
Пакеты — количество подключённых пакетов
Последняя активность — время последнего входа или просмотра
Статус — активен/заблокирован
Действия — кнопки редактирования, управления пакетами и удаления

Через Management API¶

Получить список всех абонентов:

curl -X GET https://your-catena-domain.com/tv-management/api/v1/subscribers \
  -H "X-Auth-Token: your-api-key"

Ответ:

{
  "subscribers": [
    {
      "subscriberId": "sKl9SW3AAAE.",
      "portalId": "pKl9SW3AAAE.",
      "name": "Иван Петров",
      "phoneCountryCode": "7",
      "phone": "9161234567",
      "playback_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "packages": ["pKl9SW3AAAE.", "bKl9SW3AAAE."]
    },
    {
      "subscriberId": "tKl9SW3AAAE.",
      "portalId": "pKl9SW3AAAE.",
      "name": "Мария Сидорова",
      "phoneCountryCode": "7",
      "phone": "9267654321",
      "playback_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "packages": ["pKl9SW3AAAE."]
    }
  ],
  "next": "cursor-for-next-page"
}

Пагинация:

curl -X GET "https://your-catena-domain.com/tv-management/api/v1/subscribers?cursor=cursor-for-next-page" \
  -H "X-Auth-Token: your-api-key"

Получение информации об абоненте¶

Через Management API¶

curl -X GET https://your-catena-domain.com/tv-management/api/v1/subscribers/sKl9SW3AAAE. \
  -H "X-Auth-Token: your-api-key"

Ответ: Аналогичен объекту subscriber из списка.

Редактирование абонента¶

Через веб-интерфейс¶

Откройте список абонентов
Найдите нужного абонента и нажмите кнопку "Редактировать"
Измените параметры:
Name — имя абонента
Phone Country Code — код страны
Phone — номер телефона
Сохраните изменения

Примечание: При изменении номера телефона абонент должен будет пройти повторную аутентификацию по SMS с новым номером.

Через Management API¶

curl -X PUT https://your-catena-domain.com/tv-management/api/v1/subscribers/sKl9SW3AAAE. \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Иван Петрович Петров",
    "phoneCountryCode": "7",
    "phone": "9161234567"
  }'

Управление подписками на пакеты¶

Подключение пакета к абоненту¶

Через веб-интерфейс:

Откройте карточку абонента
Перейдите в раздел "Пакеты"
Нажмите "Добавить пакет"
Выберите пакет из списка доступных
Подтвердите добавление

Абонент немедленно получит доступ ко всем каналам из добавленного пакета.

Через Management API:

curl -X POST https://your-catena-domain.com/tv-management/api/v1/packages-subscribers \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriberId": "sKl9SW3AAAE.",
    "packageId": "pKl9SW3AAAE."
  }'

Ответ:

{
  "subscriberId": "sKl9SW3AAAE.",
  "packageId": "pKl9SW3AAAE.",
  "portalId": "pKl9SW3AAAE."
}

Отключение пакета от абонента¶

Через веб-интерфейс:

Откройте карточку абонента
Перейдите в раздел "Пакеты"
Найдите пакет в списке активных
Нажмите "Удалить"
Подтвердите отключение

Абонент немедленно потеряет доступ ко всем каналам из отключённого пакета.

Через Management API:

curl -X DELETE https://your-catena-domain.com/tv-management/api/v1/packages-subscribers \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriberId": "sKl9SW3AAAE.",
    "packageId": "pKl9SW3AAAE."
  }'

Массовое управление подписками¶

Для массового подключения или отключения пакетов используйте циклы или скрипты. Пример добавления пакета нескольким абонентам:

#!/bin/bash
SUBSCRIBERS=("sKl9SW3AAAE." "tKl9SW3AAAE." "uKl9SW3AAAE.")
PACKAGE_ID="pKl9SW3AAAE."

for SUBSCRIBER_ID in "${SUBSCRIBERS[@]}"; do
  curl -X POST https://your-catena-domain.com/tv-management/api/v1/packages-subscribers \
    -H "X-Auth-Token: your-api-key" \
    -H "Content-Type: application/json" \
    -d "{
      \"subscriberId\": \"$SUBSCRIBER_ID\",
      \"packageId\": \"$PACKAGE_ID\"
    }"
done

Удаление абонента¶

Через веб-интерфейс¶

Откройте список абонентов
Найдите абонента для удаления
Нажмите кнопку "Удалить"
Подтвердите удаление

Предупреждение: При удалении абонента:

Учётная запись будет полностью удалена
Все подписки на пакеты будут отменены
История просмотров сохранится для аналитики
Абонент потеряет доступ к просмотру каналов
Восстановление учётной записи будет невозможно

Через Management API¶

curl -X DELETE https://your-catena-domain.com/tv-management/api/v1/subscribers/sKl9SW3AAAE. \
  -H "X-Auth-Token: your-api-key"

Мониторинг активности абонентов¶

Просмотр сеансов воспроизведения¶

Catena автоматически регистрирует все сеансы просмотра каналов абонентами. Это позволяет отслеживать активность, популярность каналов и выявлять проблемы.

Получить сеансы конкретного абонента:

curl -X GET "https://your-catena-domain.com/tv-management/api/v1/play-sessions?subscriberId=sKl9SW3AAAE." \
  -H "X-Auth-Token: your-api-key"

Получить только активные сеансы:

curl -X GET "https://your-catena-domain.com/tv-management/api/v1/play-sessions?subscriberId=sKl9SW3AAAE.&active=true" \
  -H "X-Auth-Token: your-api-key"

Фильтрация по времени:

curl -X GET "https://your-catena-domain.com/tv-management/api/v1/play-sessions?subscriberId=sKl9SW3AAAE.&opened_at_gte=1714233600&opened_at_lt=1714320000" \
  -H "X-Auth-Token: your-api-key"

Ответ:

{
  "sessions": [
    {
      "sessionId": "sessKl9SW3AAAE.",
      "subscriberId": "sKl9SW3AAAE.",
      "channelId": "chKl9SW3AAAE.",
      "channelName": "sport1",
      "portalId": "pKl9SW3AAAE.",
      "openedAt": 1714233600,
      "closedAt": 1714237200,
      "active": false,
      "bytes": 5242880000,
      "ip": "192.168.1.100",
      "userAgent": "VLC/3.0.16"
    }
  ],
  "next": "cursor-for-next-page"
}

Журнал операций¶

Все изменения в учётных записях абонентов (создание, удаление, изменение подписок) записываются в журнал операций.

Получить операции по абоненту:

curl -X GET "https://your-catena-domain.com/tv-management/api/v1/operations?subscriberId=sKl9SW3AAAE." \
  -H "X-Auth-Token: your-api-key"

Фильтрация по типу операции:

curl -X GET "https://your-catena-domain.com/tv-management/api/v1/operations?subscriberId=sKl9SW3AAAE.&type=createPackageSubscriber" \
  -H "X-Auth-Token: your-api-key"

Ответ:

{
  "operations": [
    {
      "operationId": "opKl9SW3AAAE.",
      "type": "createSubscriber",
      "subscriberId": "sKl9SW3AAAE.",
      "portalId": "pKl9SW3AAAE.",
      "createdAt": "2024-10-16T10:00:00Z",
      "payload": {
        "name": "Иван Петров",
        "phone": "+79161234567"
      }
    },
    {
      "operationId": "opKl9SW3AAAB.",
      "type": "createPackageSubscriber",
      "subscriberId": "sKl9SW3AAAE.",
      "packageId": "pKl9SW3AAAE.",
      "portalId": "pKl9SW3AAAE.",
      "createdAt": "2024-10-16T10:05:00Z",
      "payload": {
        "packageId": "pKl9SW3AAAE."
      }
    }
  ],
  "next": "cursor-for-next-page"
}

Типичные сценарии использования¶

Создание нового абонента с базовым пакетом¶

Задача: Зарегистрировать нового абонента и подключить базовый пакет

Шаги:

Создайте учётную запись абонента через API
Получите subscriberId из ответа
Подключите базовый пакет через API packages-subscribers
Абонент получает SMS для входа в приложение
После входа абонент видит каналы из базового пакета

Пример скрипта:

#!/bin/bash

# 1. Создаём абонента
RESPONSE=$(curl -s -X POST https://your-catena-domain.com/tv-management/api/v1/subscribers \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Новый абонент",
    "phoneCountryCode": "7",
    "phone": "9161234567"
  }')

# 2. Извлекаем ID абонента
SUBSCRIBER_ID=$(echo $RESPONSE | jq -r '.subscriberId')

# 3. Подключаем базовый пакет
curl -X POST https://your-catena-domain.com/tv-management/api/v1/packages-subscribers \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d "{
    \"subscriberId\": \"$SUBSCRIBER_ID\",
    \"packageId\": \"basic-package-id\"
  }"

echo "Абонент создан с ID: $SUBSCRIBER_ID"

Апгрейд абонента на премиум пакет¶

Задача: Перевести абонента с базового на премиум пакет

Вариант 1: Добавить премиум к базовому

# Абонент получит доступ к каналам обоих пакетов
curl -X POST https://your-catena-domain.com/tv-management/api/v1/packages-subscribers \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriberId": "sKl9SW3AAAE.",
    "packageId": "premium-package-id"
  }'

Вариант 2: Заменить базовый на премиум

# Сначала отключаем базовый
curl -X DELETE https://your-catena-domain.com/tv-management/api/v1/packages-subscribers \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriberId": "sKl9SW3AAAE.",
    "packageId": "basic-package-id"
  }'

# Затем подключаем премиум
curl -X POST https://your-catena-domain.com/tv-management/api/v1/packages-subscribers \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriberId": "sKl9SW3AAAE.",
    "packageId": "premium-package-id"
  }'

Интеграция с биллинговой системой¶

Задача: Автоматически управлять подписками на основе платежей

Концепция:

Биллинговая система отслеживает платежи абонентов
При успешной оплате биллинг вызывает API Catena для подключения пакета
При окончании подписки биллинг отключает пакет через API
Catena автоматически управляет доступом к каналам

Пример webhook от биллинга:

import requests

def on_payment_success(subscriber_phone, package_name):
    # 1. Найти абонента по телефону
    subscribers = requests.get(
        f"https://catena.example.com/tv-management/api/v1/subscribers",
        headers={"X-Auth-Token": "your-api-key"}
    ).json()

    subscriber = next(
        s for s in subscribers['subscribers']
        if f"+{s['phoneCountryCode']}{s['phone']}" == subscriber_phone
    )

    # 2. Подключить оплаченный пакет
    requests.post(
        "https://catena.example.com/tv-management/api/v1/packages-subscribers",
        headers={"X-Auth-Token": "your-api-key"},
        json={
            "subscriberId": subscriber['subscriberId'],
            "packageId": get_package_id(package_name)
        }
    )

def on_subscription_expired(subscriber_phone, package_name):
    # Аналогично, но через DELETE
    pass

Массовая миграция абонентов¶

Задача: Перенести абонентов из старой системы в Catena

Шаги:

Экспортируйте данные абонентов из старой системы (CSV/JSON)
Создайте скрипт массового импорта через API
Создайте учётные записи в Catena
Подключите соответствующие пакеты
Оповестите абонентов о переходе на новую систему

Пример скрипта импорта:

import csv
import requests

API_URL = "https://catena.example.com/tv-management/api/v1"
API_KEY = "your-api-key"

def import_subscribers(csv_file):
    with open(csv_file, 'r') as f:
        reader = csv.DictReader(f)
        for row in reader:
            # Создать абонента
            response = requests.post(
                f"{API_URL}/subscribers",
                headers={"X-Auth-Token": API_KEY},
                json={
                    "name": row['name'],
                    "phoneCountryCode": row['country_code'],
                    "phone": row['phone']
                }
            )

            subscriber_id = response.json()['subscriberId']

            # Подключить пакеты
            for package_id in row['packages'].split(','):
                requests.post(
                    f"{API_URL}/packages-subscribers",
                    headers={"X-Auth-Token": API_KEY},
                    json={
                        "subscriberId": subscriber_id,
                        "packageId": package_id.strip()
                    }
                )

            print(f"Импортирован: {row['name']} ({subscriber_id})")

import_subscribers('subscribers.csv')

Лучшие практики¶

Управление номерами телефонов¶

Рекомендации:

Валидация при вводе — проверяйте формат номера до отправки в API
Уникальность — один номер телефона = один абонент
Международный формат — храните код страны и номер раздельно
Изменение номера — требуйте подтверждения через SMS на новый номер
Деактивация — при отключении номера оператором своевременно обновляйте данные

Безопасность¶

Защита токенов воспроизведения:

Не передавайте playback_token третьим лицам
Используйте HTTPS для всех API запросов
Регулярно обновляйте токены при подозрении на компрометацию
Логируйте попытки доступа с неверными токенами

Контроль доступа:

Ограничивайте количество одновременных сеансов на абонента
Отслеживайте подозрительную активность (разные IP, разные устройства)
Блокируйте абонентов при обнаружении мошенничества

Управление подписками¶

Рекомендации:

Плавный переход — предупреждайте об изменениях в подписках заранее
Автоматизация — интегрируйте с биллингом для автоматического управления
Бесплатные пакеты — используйте free packages в портале для демо-контента
Пробные периоды — временно подключайте премиум пакеты для trial
История изменений — используйте журнал операций для аудита

Коммуникация с абонентами¶

Когда отправлять уведомления:

При создании учётной записи
При изменении подписок
При окончании оплаченного периода
При изменении номера телефона
При блокировке доступа

Каналы коммуникации:

SMS — для кодов входа и критичных уведомлений
Email — для информационных рассылок (если есть в вашей системе)
Push-уведомления — через мобильное приложение
In-app сообщения — при входе в приложение

Устранение проблем¶

Возможные причины:

Неверно указан номер телефона при регистрации
SMS не доставлена (проблемы оператора связи)
Код из SMS истёк
Номер телефона заблокирован в SMS-шлюзе

Решение:

Проверьте номер телефона в учётной записи абонента
Убедитесь, что формат номера корректен (+код_страны + номер)
Проверьте логи SMS-шлюза на доставку сообщений
Попробуйте отправить SMS повторно
Если SMS не приходят — проверьте баланс SMS-шлюза и его настройки

Абонент не видит каналы¶

Возможные причины:

У абонента нет подключённых пакетов
Пакеты не содержат каналов
Токен воспроизведения устарел или недействителен
Технические проблемы со streaming-сервером

Решение:

Проверьте список пакетов в поле packages абонента
Убедитесь, что пакеты содержат каналы
Проверьте, что каналы активны и работают
Перегенерируйте playback_token если необходимо
Проверьте логи streaming-сервера

Ошибки при подключении пакета¶

Возможные причины:

Пакет уже подключён к абоненту
Указан неверный packageId или subscriberId
Пакет и абонент принадлежат разным порталам
Пакет не существует или удалён

Решение:

Проверьте текущие пакеты абонента через GET /subscribers/{id}
Убедитесь, что ID пакета и абонента корректны
Проверьте, что пакет существует через GET /packages/{id}
Убедитесь, что portalId совпадает у пакета и абонента

Дубликаты номеров телефонов¶

Проблема: Попытка создать абонента с уже существующим номером

Решение:

API должен возвращать ошибку при создании дубликата
Перед созданием проверяйте наличие абонента с таким номером
Используйте UPDATE вместо CREATE для существующих абонентов
Реализуйте поиск по номеру телефона в вашем интерфейсе

См. также¶

Управление пакетами каналов — создание и настройка пакетов для абонентов
Управление каналами — настройка телевизионных каналов
Журнал операций — отслеживание изменений в системе
Сеансы воспроизведения — мониторинг активности просмотра

Управление абонентами¶

Что такое абонент¶

Основные параметры абонента¶

Технические параметры¶

Личные данные¶

Параметры доступа¶

Аутентификация абонентов¶

Вход по SMS (основной способ)¶

Автоматическое создание абонентов¶

Создание абонента¶

Через веб-интерфейс¶

Через Management API¶

Просмотр списка абонентов¶

Через веб-интерфейс¶

Через Management API¶

Получение информации об абоненте¶

Через Management API¶

Редактирование абонента¶

Через веб-интерфейс¶

Через Management API¶

Управление подписками на пакеты¶

Подключение пакета к абоненту¶

Отключение пакета от абонента¶

Массовое управление подписками¶

Удаление абонента¶

Через веб-интерфейс¶

Через Management API¶

Мониторинг активности абонентов¶

Просмотр сеансов воспроизведения¶

Журнал операций¶

Типичные сценарии использования¶

Создание нового абонента с базовым пакетом¶

Апгрейд абонента на премиум пакет¶

Интеграция с биллинговой системой¶

Массовая миграция абонентов¶

Лучшие практики¶

Управление номерами телефонов¶

Безопасность¶

Управление подписками¶

Коммуникация с абонентами¶

Устранение проблем¶

Абонент не может войти по SMS¶

Абонент не видит каналы¶

Ошибки при подключении пакета¶

Дубликаты номеров телефонов¶

См. также¶