Интеграция за 24 часа

Для интеграции такого типа 24часаТВ предлагает провайдеру создать на своей стороне обработку двух http/https запросов со стороны 24часаТВ.

Ниже принципиальная схема работы систем при интеграции:

Open

1. Абонент провайдера устанавливает тв приложение 24часаТВ на свое оборудование, регистрируется с помощью мобильного номера телефона

2. Получает по смс одноразовый пароль и входит в приложение 24часаТВ.

3. В системе 24часаТВ создается учетная запись для абонента, по ip адресу абонента она привязывается к провайдеру. Абонент после успешной регистрации в системе 24часаТВ получает промо период бесплатного просмотра тв каналов.

4. Система 24часаТВ высылает http/https запрос в сторону провайдера (AUTH) с ip адресом абонента и номером телефона. Запрос высылается один раз, после ввода одноразового пароля из смс абонентом.

5. Провайдер на данное событие идентифицирует своего абонента по ip адресу, создает в своем биллинге при необходимости учетную запись или договор для услуг ТВ и отвечает на AUTH в формате json, в ответе сообщает id созданой учетной записи или договора (provider_user_id). Запрос AUTH будет повторен, если абонент переидентифицируется в приложении и для него не установлен provider_user_id).

6. После окончания промо периода или во время его абонент может подключить платный пакет. Абонент в настройках приложения выбирает предпочитаемый платный пакет и нажимает кнопку "Подключить". В этот момент в системе 24часаТВ создается операция и в сторону провайдера отправляется http/https запрос CONT c provider_user_id, стоимостью платного пакета, id платного пакета и названием пакета. Провайдер по provider_user_id находит учетную запись или договор в своей биллинговой системе, проверяет баланс, списывает стоимость платного пакета и создает у себя в системе начисление.

7. В ответ на запрос CONT провайдер в формате json отправляет id начисления.

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

После создания интеграции провайдер сообщает интеграционный url в 24часаТВ.

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

• Пакеты бывают двух типов, базовые (основной) и дополнительные. Каждый базовый пакет имеет свой набор дополнительных пакетов для подключения (могут быть базовые пакеты и без дополнительных).

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

• Подключение любого типа пакета производится на календарный месяц (на количество дней в месяце на момент подключения пакета).

• После окончания срока действия любого пакета происходит его автоматическое автопродление (если не снят флаг автопродления у этого пакета). При этом по схеме интеграции "24 часа", провайдеру будет отправлен новый запрос CONT на продление этого пакета (запрос CONT описан ниже). 

• Переход на более дорогой базовый пакет (докупка) возможен в любой момент времени действия этого пакета. При таком переходе высчитывается стоимость недосмотренного времени по более дешевому пакету и стоимость более дорогого пакета уменьшается на эту сумму.

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

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

Описание запроса AUTH в сторону провайдера из системы 24часаТВ

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

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

<http или https>://<url для интеграции>:<порт>/auth?ip=<ip_address>&phone=<phone>&mbr_id=<user_id>

где:

• url для интеграции:порт - url и порт указанный провайдером.<br>

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

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

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

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

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

{ "user_id": <provider_user_id> }

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

{ "status": -1, "err": <код ошибки>, "errmsg": "<Описание ошибки>" }

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

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

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

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

 Описание запроса CONT в сторону провайдера из системы 24часаТВ

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

<http или https>://<url для интеграции>:<порт>/cont?user_id=<provider_user_id>&sum=<стоимость>&cont_id=<cont_id>&trf_id=<tariff_id>&message=<Название пакета>&start=<Дата>

где:

• url для интеграции:порт - url и порт указанный провайдером.

• provider_user_id - id учетной записи или договора из биллинга провайдера.

• стоимость - стоимость платного пакета (в случае перехода с тарифа на тариф система 24часаТВ высчитает разницу перехода).

• cont_id - id операции в системе 24часаТВ.

• tariff_id - id платного пакета в системе 24часаТВ.

• Название пакета - название платного пакета.

• Дата - дата начала действия платного пакета.

В теле запроса идет информация в json формате:

{
"type": "cont",
    "user": {
        "id": <ID в системе 24часаТВ>,
        "provider_uid": "<ID провайдера>",
        "username": "<Телефон абонента>",
        "first_name": "<Имя абонента>",
        "last_name": "<Фамилия абонента>",
        "phone": "<Телефон абонента>",
        "email": <email абонента>,
        "timezone": <Таймзона абонента>
    },
    "packet": {
        "id": <ID подключаемого пакета>,
        "name": "<Название подключаемого абонента>",
        "price": "<Стоимость пакета>",
        "is_base": <Признак основной/дополнительный>
    }
}

В случае удачного списания денежных средств с лицевого счета абонента в биллинге провайдера:

{ "id": <id списания>, "status": 1 }

В случае нехватки денежных средств или неудачи списания в поле status указывается код ошибки:

{

"status": <код ошибки>, "errmsg": "<Описание ошибки>" }

Коды ошибок:

-1 - Ошибка списания денежных средств.
-2 - Не хватает денежных средств.

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

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

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

Расширение функционала схемы "24 часа".

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

Из расширения функционала возможно:

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

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

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

• Снятие с паузы подписки пользователя

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

• Отображение баланса пользователя из биллинга в тв приложении

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

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

Полное описание  доступно по адресу: https://api.24h.tv/v2/doc/provider#!/

Ниже идет описание методов API 24часаТВ.

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

Описание - https://api.24h.tv/v2/doc/provider#!/Users/get_users_user_id_subscriptions_subscription_id_pauses

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

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

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

{ "id": "<ID паузы>", "start_at": "<Дата постановки на паузу>", "end_at": null }

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

Response Code - 404

{

"detail": "Не найдено.", "error": { "message": "Не найдено." }, "status_code": 404 }

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

Описание - https://api.24h.tv/v2/doc/provider#!/Users/post_users_user_id_subscriptions_subscription_id_pauses

Тип запроса POST

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

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

Response Code - 200

{ "id": "<ID паузы>", "start_at": "<Дата постановки на паузу>", "end_at": null }

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

Response Code - 404

{

"detail": "Не найдено.", "error": { "message": "Не найдено." }, "status_code": 404 }

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

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

Описание - https://api.24h.tv/v2/doc/provider#!/Users/post_users_user_id_pauses

Тип запроса POST

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

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

Response Code - 200

[
{ "id": "<ID паузы>", "start_at": "<Дата постановки на паузу>", "end_at": null },
{
"id": "<ID паузы>", "start_at": "<Дата постановки на паузу>", "end_at": null
},
......
]

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

Response Code - 404

{

"detail": "Не найдено.", "error": { "message": "Не найдено." }, "status_code": 404 }

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

Описание - https://api.24h.tv/v2/doc/provider#!/Users/delete_users_user_id_subscriptions_subscription_id_pauses_pause_id

Тип запроса DELETE

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

Response Code - 200

{ "id": "<ID паузы>", "start_at": "<Дата постановки на паузу>", "end_at": "<Дата снятия с паузы>" }

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

Response Code - 404

{

"detail": "Не найдено.", "error": { "message": "Не найдено." }, "status_code": 404 }

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

Описание - https://api.24h.tv/v2/doc/provider#!/Users/delete_users_user_id_pauses

Тип запроса DELETE

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

Response Code - 200

[
{ "id": "<ID паузы>", "start_at": "<Дата постановки на паузу>", "end_at": "<Дата снятия с паузы>" },
{
"id": "<ID паузы>", "start_at": "<Дата постановки на паузу>", "end_at": "<Дата снятия с паузы>" },
......
]

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

Response Code - 404

{

"detail": "Не найдено.", "error": { "message": "Не найдено." }, "status_code": 404 }

Отображение баланса пользователя из биллинга в тв приложении

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

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

Описание - https://api.24h.tv/v2/doc/provider#!/Users/post_users_user_id_provider_account

Тип запроса POST

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

Параметры:

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

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

Response Code - 200

{ "id": <ID лицевого счета в биллинге провайдера>, "source": { "id": <ID платежного аккаунта в платформе 24часаТВ>, "name": "<Название платежного аккаунта в платформе 24часаТВ>" }, "amount": "<значение отображаемого баланса в рублях>" }

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

Response Code - 404

{ "status_code": 404, "error": { "message": "Не найдено." }, "detail": "Не найдено." }

Так же есть метод для просмотра установленного значения:

Описание - https://api.24h.tv/v2/doc/provider#!/Users/get_users_user_id_provider_account

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

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

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

Response Code - 200

{ "id": <ID лицевого счета в биллинге провайдера>, "source": { "id": <ID плаьежного аккаунта в платформе 24часаТВ>, "name": "<Название платежного аккаунта в платформе 24часаТВ>" }, "amount": "<значение отображаемого баланса в рублях>" }

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

Response Code - 404

{ "status_code": 404, "error": { "message": "Не найдено." }, "detail": "Не найдено." }

 

Тестирование интеграции