Интеграция за 48 часов

Введение.

Для доступа к описанию и получения API-токена необходимо авторизоваться в админ-панели (логин / пароль запросить у менеджера).

Ссылка для генерации TOKEN.

API-инструментарий (SWAGGER).

Логи запросов от 24ТВ.

Бизнесы-процессы и методология тестирования изложены последнем разделе “Тестирование схемы интеграции”.

В рамках интеграции провайдеру необходимо реализовать:

  1. Регистрация пользователя.

  2. Управление подписками:

    1. подключение базового и/или доп. пакета

    2. переход на более дорогой базовый пакет

    3. переход на более дешевый базовый пакет

    4. постановка пакета на паузу и снятие с неё

    5. отключение пакета

  3. Отображение баланса лицевого счёта в Приложении 24ТВ.

  4. Ответы на запросы запросы AUTH и PACKET (обратная интеграция - управление пакетами со стороны приложения )

  5. Расторжение договора (обеспечение возможностью платить в 24ТВ напрямую).

Службе поддержки Tech Support 24ТВ необходимо предоставить интеграционный URL (API URL), на который платформа будет отправлять запросы, и PROXY URL.

Логика подключения пакетов и переходов с пакета на пакет.

  • Пакеты бывают 2-х типов: базовые (взаимоисключающие друг друга) и дополнительные. Каждый базовый пакет имеет свой набор дополнительных пакетов для подключения (могут быть базовые пакеты и без дополнительных, например, на пакет “Все включено”, где весть контент уже включен, нет необходимости включать доп. пакеты). С 2023 г. разрешено включение доп. пакетов без базовых. Провайдер самостоятельно решает можно ли подключить доп. пакет без базового. Рекомендуем убрать ограничения и проверки, на условие, что доп. пакет нельзя купить без базового. См. также файл “Схема обратной интеграции”.

  • Подключение пакета производится на календарный месяц, если не указаны дата "с" и/или дата "по". Пример:

Дата начала

Дата окончания

Дата начала

Дата окончания

20 января

20 февраля

31 января

03 марта

Регистрация пользователя.

Для регистрации пользователя в платформе 24ТВ необходимо использовать вызов API: 

Тип запроса: POST

https://provapi.24h.tv/v2/users?token=<TOKEN>

Передаваемые параметры:

{ "username": "<username>", "first_name": "<Имя пользователя>", "last_name": "<Фамилия пользователя>", "email": "email пользователя", "phone": "<телефон пользователя>", "provider_uid": "<id в биллинговой системе провайдера>", "is_provider_free": <Доступ к тв не из сети провайдера (false - запретить, true - разрешить)>, "is_active": <Активность пользователя (false - заблокирован, true - активен)> }

Обязательные к заполнению:

{ "username": "<username>", "phone": "<телефон пользователя>" }

В ответ будет возвращены данные в json формате. В ответе получите идентификатор пользователя в платформе (ID), его необходимо сохранить и использовать для дальнейшей идентификации:

Response Code - 200

{ "id": <идентификатор пользователя в платформе 24часаТВ, его необходимо сохранить и использовать для дальнейшей идентификации>, "username": "<username пользователя>", "first_name": "<Имя пользователя>", "last_name": "<Фамилия пользователя>", "phone": "<Телефон>", "email": "<email пользователя>", "timezone": null, "provider": { "id": <ID провайдера в платформе 24часаТВ>, "name": "<Название провайдера>", "proxy": "", "landing": { "shortname": "<Короткое название провайдера>", "logo": null, "url": "", "support": { "url": "<URL провайдера>", "phone": "<Телефон провайдера>" }, "login": { "title": "", "description": "<Сообщение при регистрации пользователя>" } } }, "provider_uid": "<id в биллинговой системе провайдера>" }

В случае неверных данных будет возвращена ошибка с описанием в json формате, например, если попытаться создать такого же пользователя:

Response Code - 400

Поле email не является обязательным. Чтобы не было ошибки при передаче email пустым, это поле можно в параметрах не указывать.

Изменение информации о пользователе.

Метод позволяет изменить часть пользовательских данных и возвращает измененные данные пользователя.

Тип запроса: PATCH

User_ID - полученный при создании пользователя:

https://provapi.24h.tv/v2/users/<User_ID>?token=<TOKEN>

Передаваемые параметры:

В ответ будет возвращены данные в json формате. В ответе получите идентификатор пользователя в платформе (ID), его необходимо сохранить и использовать для дальнейшей идентификации:

В случае неверных данных будет возвращена ошибка с описанием в json.

В случае блокировки пользователя, установкой флага is_active=false, данный пользователь не сможет войти в приложение 24ТВ. При этом подписки на пакеты не отключаются! Если вам необходимо блокировать пользователя, то перед этим остановите все его активные подписки!

Получение списка зарегистрированных пользователей.

Метод получать список всех зарегистрированных пользователей провайдера.
Тип запроса: GET

https://provapi.24h.tv/v2/users?token=<TOKEN>

В ответ будет возвращены данные в json формате со списком всех пользователей провайдера:

При выводе большого списка используется постраничный вывод, поэтому, для получения полного списка пользователей необходимо в запрос добавлять параметры &limit= и &offset=.

Поиск пользователя среди зарегистрированных.

Поиск пользователей возможен по:

  • id пользователя в платформе 24ТВ 

  • По номеру телефона или по id в биллинговой системе провайдера.

Поиск по id пользователя:

Тип запроса: GET

https://provapi.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>?token=<TOKEN>

В ответ будет возвращены данные в json формате о пользователе провайдера:

В случае неудачного поиск будет возвращена ошибка:

Response Code - 404


По номеру телефона или по id в биллинговой системе провайдера:

Тип запроса: GET

по номеру телефона:

https://provapi.24h.tv/v2/users?phone=<Номер телефона абонента>&token=<TOKEN>

по ID в биллинговой системе провайдера:

https://provapi.24h.tv/v2/users?provider_uid=<ID пользователя из биллинговой системы провайдера>&token=<TOKEN>

В ответ будет возвращены данные в json формате о пользователе провайдера:

В случае неудачного поиска будет возвращен пустой ответ:

Получение списка пакетов.

В платформе 24ТВ пакеты разделены на два типа: Базовые пакеты (в ответе "base": true) и Дополнительные пакеты (в ответе "base": false).

Некоторые базовые пакеты уже включают в себя некоторые дополнительные (максимальный тариф “Всё включено” содержит в себе все дополнительные тарифы).

Запрос иерархичного списка пакетов.

https://provapi.24h.tv/v2/packets?token=<TOKEN>&includes=<availables,includes,videos,channels>

  • Будут выведены все пакеты провайдера, в том числе неопубликованные. Пакеты с флагом is_public=false не будут показываться абоненту в приложении.

  • На первом уровне списка — базовые пакеты. Чтобы увидеть дополнительные пакеты в виде дерева, добавьте аргумент includes=availables. Дополнительные пакеты будут в ключе «availables» каждого пакета

  • Возможные значения параметра includes :

    • availables — получение возможных пакетов для подключения

    • includes — получение включенных дополнительных пакетов в базовые

    • videos — включение в ответ информации о видеоисточниках, включенных в пакет

    • channels — каналы в данном пакете

  • Значения includes можно комбинировать через запятую: includes=availables,videos

В ответ будет возвращены данные в json формате о пакетах провайдера:

Без параметра includes будет возвращен список базовых тарифов.

https://provapi.24h.tv/v2/packets?token=<TOKEN>

В ответ будет возвращены данные в json формате о пакетах провайдера:

Запрос плоского списка пакетов.

https://provapi.24h.tv/v2/?token=<TOKEN>

  • При запросе с указанием провайдерского токена token будут выведены все пакеты провайдера, в том числе неопубликованные

  • При запросе с указанием пользовательского токена access_token будут выведены только пакеты, видимые этому пользователю

  • Если нужны только базовые пакеты, добавьте аргумент фильтра is_base=true. Если только дополнительные, добавьте is_base=false

Подключение пакета.

Тип запроса: POST

https://provapi.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/subscriptions?token=<TOKEN>
Передаваемые параметры:

Обязательные параметры:

В ответ будет возвращен json с информацией о подписке:

Response Code - 200

В случае ошибки:

Response Code - 400

Отключение пакета.

Тип запроса: DELETE

https://provapi.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/subscriptions/<ID подписки>?token=<TOKEN>

В ответ будет возвращен json с информацией о приостановленной подписке:

Response Code - 200

В случае ошибки:

Response Code - 400

Получение списка подписок на пакеты пользователя.

Для получения текущих подписок пользователя используется вызов API платформы 24ТВ:

Тип запроса: GET

https://provapi.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/subscriptions/current?token=<TOKEN>

В ответе будет содержаться список текущих подписок пользователя в формате json:

Для получения списка всех когда либо назначенных подписок используется запрос:

Тип запроса: GET

https://provapi.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/subscriptions?token=<TOKEN>

В ответе будет содержаться список всех подписок пользователя в формате json.

Персонализация пакета для пользователя.

Используется при необходимости персонализировать название, описание или цену пакета для любого абонента.

Тип запроса: POST

https://provapi.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/packets?token=<TOKEN>

Передаваемые параметры:

В ответе будет содержаться информация о пакете:

Постановка на паузу подписки пользователя.

В случае, если пользователь провайдера желает приостановить свои платные подписки на неопределенное время возможна установка паузы у подписок.

Получение списка подписок установленных на паузу:

Тип запроса: GET

https://provapi.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/subscriptions/<ID подписки>/pauses?token=<TOKEN>

В ответе будет содержаться информация о приостановке подписки на паузу:

В случае если подписка не на паузе ответ будет:

Response Code - 404

Установка подписки на паузу:

Тип запроса POST

https://provapi.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/subscriptions/<ID подписки>/pauses?token=<TOKEN>

В ответе будет содержаться информация о приостановке подписки на паузу:

Response Code - 200

В случае ошибки ответ будет:

Response Code - 404

Постановка всех подписок пользователя на паузу.

Установка подписки на паузу:

Тип запроса POST

https://provapi.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/pauses?token=<TOKEN>

В ответе будет содержаться информация о приостановке подписок на паузу:

Response Code - 200

В случае ошибки ответ будет:

Response Code - 404

Снятие с паузы.

Тип запроса DELETE

https://provapi.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/subscriptions/<ID подписки>/pauses/<ID паузы>?token=<TOKEN>

Response Code - 200

В случае ошибки ответ будет:

Response Code - 404

Снятие с паузы всех подписок.

Тип запроса DELETE

https://provapi.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/pauses/<ID паузы>?token=<TOKEN>

Response Code - 200

В случае ошибки ответ будет:

Response Code - 404

Если подписка стоит на паузе, период действия подписки не учитывается и будет пересчитан после снятия с паузы.

Для проведения каких либо операций с подпиской необходимо снять паузу.

Отображения баланса из биллинговой системы в приложении 24ТВ.

В платформе 24ТВ заложена возможность трансляции баланса из биллинговой системы провайдера в приложения пользователей. При любом изменении баланса у пользователя в биллинговой системе, провайдер может обновить его и в платформе 24ТВ.

Установка отображаемого баланса:

Тип запроса POST

https://provapi.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/provider/account?token=<TOKEN>

Параметры:

  • id - id лицевого счета в биллинговой системе провайдера

  • amount - значение отображаемого баланса в рублях

Response Code - 200

В случае ошибки ответ будет:

Response Code - 404

Метод для просмотра установленного значения:

Тип запроса: GET

https>://provapi.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/provider/account?token=<TOKEN>

В случае успешного поиска в платформе 24ТВ будет возвращена информация о установленном значении:

Response Code - 200

В случае ошибки ответ будет:

Response Code - 404

Другой способ - отображать баланс напрямую из биллинга интеграционным запросом BALANCE. Запрос будет отправлен в сторону провайдера при входе абонента в настройки приложения, он описан в следующем разделе.

Методы формируемые платформой в сторону интеграции оператора (биллинга).

Запрос к провайдеру AUTH (сопоставление с лицевым счетом в биллинге).

Согласно договору необходимо реализовать:

  • AUTH-запрос - автоматический поиск пользователя в биллинговой системе по IP-адресу (реальному или «серому») и привязку к учетной записи (метод AUTH-аутентификации). Данный функционал должен быть доступен для любого пользователя постоянно.

  • В случае использования «серых» IP-адресов в сети и NAT (преобразование сетевых адресов) - наличие proxy-сервера для направления запросов к Сервису для определения фактических IP-адресов Пользователей (инструкция Установка proxy сервера на стороне провайдера при работе клиентов через NAT).

  • PACKET-запрос - отработку со стороны системы биллинга запросов пользователей на подключение ТВ-пакетов из приложений (метод PACKET). Данный функционал должен быть постоянно включен для всех пользователей. Запросы должны отрабатываться для любых пакетов, кроме бандлов, при наличии положительного баланса на счету пользователя.

  • Списание оплаты за подключаемые из приложения продукты с основного счета пользователя в системе биллинга.

ВАЖНО! На стороне 24ТВ прописываются IP адреса провайдера. При регистрации абонента в 24ТВ с этих адресов, он автоматически попадает/соотносится к провайдеру, и оплата возможна только провайдеру. Если абонент ранее зарегистрирован и числится за другим провайдером, не имеет платных подписок, то при 3-х кратном в сутки запуске приложения с указанных IP адресов, он будет автоматически соотнесен к провайдеру - владельцу IP адресов. Если абонент регистрировался из другой сети, например, из сети мобильного оператора, вы можете выполнить перенос абонента самостоятельно через админ-панель, при соответствии условиям: прошел регистрацию не из вашей сети, хотя бы раз выполнил вход из вашей сети и не привязан к другому провайдеру. Для этого достаточно в поиске написать номер телефона такого абонента и согласиться на перенос нажав кнопку "Pick up user".

Цель AUTH-запроса - установить соответствие у пользователя между системой 24ТВ и биллингом провайдера - присвоить <provider_user_id>.В дальнейшем <provider_user_id> будет сообщаться провайдеру в запросе PACKET. При входе в приложение метод AUTH (запрос на <provider_user_id>) придёт в API провайдера, если у пользователя не заполнено поле <provider_user_id> и используется биллинговая схема "simple_auth" (схема устанавливается службой поддержки 24ТВ по запросу провайдера). [cм. также файл “Схема обратной интеграции”]

На указанный провайдером интеграционный URL 24ТВ отправляет POST-запрос (параметры передаются в строке запроса):

https://<API URL>/auth?ip=<ip_address>&phone=<phone>&mbr_id=<user_id>&provider_id=<provider_id>

API URL должен заканчиваться на "/" так как далее к этому URL добавляется "auth?ip=..." и т.д.

где:

  • ip_address - ip адрес абонента.

  • phone - номер мобильного телефона, с которого зарегистрировался абонент.

  • mbr_id - id учетной записи в 24ТВ (user_id).

  • provider_id - id провайдера.

Платформа 24ТВ ожидает ответ в формате json:

В случае удачного идентификации абонента в биллинговой системе провайдера id учетной записи или договора:

В случае неудачи необходимо вернуть:

Список кодов ошибок "err":

  • -1 Пользователь не найден. 

  • -2 Ошибка регистрации.

Описание ошибки - любое текстовое сообщение.

Запрос к провайдеру PACKET (желание подключить пакет пользователем из приложения).

Данный запрос производится от 24ТВ к биллинговой системе провайдера, когда пользователь желает подключить платный пакет через ТВ-приложение.

Запрос синхронный. Биллинговая система провайдера после получения данного запроса определяет возможность подключения желаемого платного пакета, подключает платный пакет через API платформы 24ТВ (используя метод https://provapi.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/subscriptions?token=<TOKEN>) и возвращает положительный ответ в успешном случае или отрицательный ответ с текстом сообщения об ошибке, которое транслируется в приложение пользователю.

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

  • Если у абонента уже подключен базовый пакет с большей стоимостью - необходимо отменить его автопродление (установкой флага renew=false) и подключить новый пакет с даты окончания текущего.

  • Если у абонента подключен базовый пакет с меньшей стоимостью - необходимо подключить новый с текущего времени. Для этого необходимо сначала остановить старый базовый пакет путем отправки запроса DELETE https://provapi.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/subscriptions/<ID подписки>?token=<TOKEN>, после этого отправить запрос в 24часаТВ на подключение нового пакета.

Тип запроса: POST

Запрос https://<API URL>/packet?user_id=<Provider_user_id>&trf_id=<ID платного пакета в платформе 24часаТВ>

В теле запроса будет json такого типа:

Можно ориентироваться как на параметры URL, так и на json в теле запроса.

В ответ платформа 24ТВ ожидает json с параметрами - status = 1 - в случае успеха.

Или status != -1 и errmsg  c описанием ошибки, которое транслируется в приложение (на телеэкран).

Положительный ответ в json формате:

 Отрицательный ответ в json формате:

ВАЖНО! В случае нехватки денежных средств, запрос PACKET всегда должен возвращать status = -1
В случае других причин используйте любые другие коды с отрицательным значением (-2, -3 и т.п.)

Запрос к провайдеру DELETE_SUBSCRIPTION (желание отключить пакет пользователем из приложения).

Данный запрос производится от 24ТВ к биллинговой системе провайдера, когда в ТВ приложении на пакете абонент нажимает кнопку "Отключить".

Запрос синхронный. Биллинговой системе провайдера после получения данного запроса определяет возможность отключения желаемого платного пакета, отключает платный пакет через API платформы 24ТВ и возвращает положительный ответ в успешном случае или отрицательный ответ с текстом сообщения об ошибке, которое транслируется в приложение пользователю.

Обращаем внимание, что в сервисе 24часаТВ по агентской схеме пакеты подключаются на срок не менее месяца. Поэтому биллинговая система при запросе пользователя на отключение должен снять автопродление пакета в собственной базе и проинформировать об этом сервис установкой флага renew=false в соответствующей подписке.

Тип запроса: POST

Запрос: https://<API URL>/delete_subscription?user_id=<Provider_user_id>&sub_id=<ID подписки в платформе 24часаТВ>

В теле запроса будет json такого типа:

Положительный ответ в json формате:

Отрицательный ответ в json формате:

Запрос к провайдеру BALANCE (отображение баланса в приложении).

Запрос отправляется в биллинг провайдера при входе абонента в настройки приложения. Для включения запроса необходимо сообщить об этом службе поддержки 24ТВ (включается опция “Запрашивать баланс абонентов из биллинга”).

https://<API URL>/balance?user_id=<Provider_user_id>

При отсутствии Provider_user_id на платформе запрос не отправится.

В теле запроса будет json такого типа:

Положительный ответ в json формате:

В случае такого ответа в личном кабинете 24ТВ или в настройках тв приложения будет отображен баланс 100.00 рублей.

Отрицательный ответ в json формате:

Расторжение договора.

В случае расторжения договора с абонентом - перехода к другому провайдеру, необходимо обеспечить его возможностью оплаты не с лицевого счета в вашем биллинге, а например банковской картой. Для этого используется метод переноса в 24ТВ.

Тип запроса: PUT

https://provapi.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/change_provider/1?token=<TOKEN>

где 1 - id провайдера “24ТВ” (да “24ТВ” - это отдельный провайдер на платформе 24ТВ)

Логи.

Посмотреть логи по запросам в биллинг провайдера можно в админ-панели, раздел Инструменты.

Таймаут по запросам в биллинг провайдера составляет 5 секунд, в случае превышении времени ответа такой запрос отбрасывается и в лог в качестве тела ответа будет записано как “none”.

Тестирование схемы интеграции.

Тест (бизнес-процесс)

Действие

Результат

Замечания

Действия через тв-приложение

1

Саморегистрация абонента через тв-приложение (реальный ip адрес)

Появление в биллинге договора/учетки/услуги на тв, привязанной к интернет-договору абонента с этим ip адресом и общим балансом. Проставление provider_uid в системе 24ТВ





2

Саморегистрация абонента через тв-приложение (серый ip адрес)

Появление в биллинге договора/учетки/услуги на тв, привязанной к интернет-договору абонента с этим ip адресом и общим балансом. Проставление provider_uid в системе 24ТВ





3

Саморегистрация абонента через тв-приложение (динамический ip адрес)

Появление в биллинге договора/учетки/услуги на тв, привязанной к интернет-договору абонента, которому выдан данный динамический-ip адрес в текущий момент, и общим балансом. Проставление provider_uid в системе 24ТВ





4

Подключение через тв-приложение базового пакета

В биллинге должно произойти списание денежных средств с договора/учетки/услуги и подключен этот пакет в биллинге и в 24ТВ





5

Подключение через тв-приложение дополнительного пакета

В биллинге должно произойти списание денежных средств с договора/учетки/услуги и подключен этот пакет в биллинге и в 24ТВ





6

Переход через тв-приложение на более дорогой пакет

В биллинге должно произойти списание денежных средств и подключен этот пакет в биллинге и в 24ТВ (см. также действия через биллинг п. 12)





7

Переход через тв-приложение на дешевый пакет

В биллинге должно произойти планирование перехода на более дешевый пакет после окончания более дорогого (см. действия через биллинг п. 13, 14)





8

Отключение подписки через тв-приложение

Отключения флага автопродления в системе 24ТВ и биллинге провайдера





Действия через биллинг

9

Создание тв договора/учетки/услуги через биллинг

Абонент должен появиться в системе 24ТВ с корректным номером телефона и provider_uid





10

Подключение базового пакета через биллинг

В системе 24ТВ должна появиться подписка на данный пакет





11

Подключение дополнительного пакета через биллинг

В системе 24ТВ должна появиться подписка на данный пакет





12

Переход на более дорогой базовый пакет

В системе 24ТВ должна появиться подписка на данный пакет, предыдущий дешевый должна быть отключен. Если у абонента вместе с дешевым был включен доп. пакет, который входит в запрошенный дорогой (см. также запрос иерархичного списка пакетов, includes=availables и получение списка подписок на пакеты пользователя), то его также необходимо отключить.





13

Переход на более дешевый базовый пакет

В билинге должна быть запланирована подписка на более дешевый пакет после окончания более дорогого. Пример: с Премиум (999 ₽) на Оптимум+ (399 ₽).





14

Переход на другой более дешевый базовый пакет

В билинге должна быть запланирована подписка на новый более дешевый пакет после окончания более дорогого. Пример: с Премиум (999 ₽) на Оптимум+ (399 ₽) и не дожидаясь его включения, на Лайт+(199 ₽).





15

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

В системе 24ТВ подписка должна быть приостановлена





16

Снятие подписки с паузы через биллинг

В системе 24ТВ подписка должна быть возобновлена





17

Остановка/закрытие подписки через биллинг

Подписка в системе 24ТВ должна быть остановлена





18

Проверка корректного отображения баланса из биллинга в тв-приложении

Должен отображаться правильный баланс из билинга в тв-приложении





19

Расторжение договора - перенос в 24ТВ

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