Для доступа к описанию необходимо авторизоваться в кабинете оператора.
Полное описание (SWAGGER) https://api.24h.tv/v2/doc/provider#!/
Основные бизнесы-процессы и методология тестирования изложены последнем разделе “Тестирование схемы интеграции”.
Для доступа к API необходимо зарегистрироваться в 24ТВ, через менеджера получить доступ к личному кабинету провайдера и сгенерировать там TOKEN https://24h.tv/admin/settings/tokens/
Логи запросов от 24ТВ к партнёру по ссылке https://24htv.platform24.tv/admin/api-requests/
В рамках интеграции провайдеру необходимо реализовать:
Создание/изменение пользователя (договора/учётки/услуги)
Управление подписками:
подключение базового и/или доп. пакета
переход на более дорогой базовый пакет
переход на более дешевый базовый пакет
постановка пакета на паузу и снятие с неё
отключение пакета
Отображение баланса лицевого счёта из биллинговой системы в 24ТВ
Ответы на запросы запросы AUTH и PACKET (обратная интеграция - управление пакетами со стороны приложения )
Службе поддержки https://t.me/help24htv необходимо предоставить интеграционный URL (API URL) на который платформа 24ТВ будет отправлять запросы.
Пакеты бывают 2-х типов: базовые (взаимоисключающие друг друга) и дополнительные. Каждый базовый пакет имеет свой набор дополнительных пакетов для подключения (могут быть базовые пакеты и без дополнительных, например, на пакет “Все включено”, где весть контент уже включен, нет необходимости включать доп. пакеты). С 2023 г. разрешено включение доп. пакетов без базовых. Провайдер самостоятельно решает можно ли подключить доп. пакет без базового. Рекомендуем убрать ограничения и проверки, на условие, что доп. пакет нельзя купить без базового. См. также файл “Схема обратной интеграции”.
Подключение пакета производится на календарный месяц, если не указаны дата "с" и/или дата "по". Пример:
Дата начала | Дата окончания |
---|---|
20 января | 20 февраля |
31 января | 03 марта |
20 февраля | 20 марта |
28 февраля | 28 марта |
29 февраля | 29 марта |
31 марта | 1 мая |
31 мая | 01 июля |
После окончания срока действия любого пакета происходит его автоматическое автопродление (если не снят флаг автопродления у этого пакета). При этом по схеме интеграции "48 часов" в отличии от “24 часа” Интеграция за 24 часа , при автопродлении подписки, запрос к провайдеру PACKET не отправляется! Под продлением подразумевается завершение продлеваемой подписки и подключение новой подписки с новым ID.
Переход на более дорогой базовый пакет (докупка) должен быть возможен в любой момент времени действия этого пакета. При таком переходе провайдером высчитывается стоимость недосмотренного времени по более дешевому пакету и стоимость более дорогого пакета уменьшается на эту сумму.
Переход с более дорогого базового пакета на более дешевый должен быть возможен только после окончания действия более дорогого, при этом более дешевый пакет должен быть запланирован в биллинговой системе провайдера на подключение после окончания дорогого пакета, также необходимо отключить автопродление у этого пакета. Пользователь до окончания срока действия более дорогого пакета может изменить запланированный пакет на любой другой, это должно быть учтено в биллинговой системе провайдера.
При переходе с базового пакета на другой базовый пакет дополнительные пакеты автоматически не отключаются, этим также должен управлять биллинговая система провайдера.
Для регистрации пользователя в платформе 24ТВ необходимо использовать вызов API:
Описание https://api.24h.tv/v2/doc/provider#!/Users/post_users
Тип запроса: POST
<http или https>://api.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 - активен)> } |
Обязательных к заполнению параметра 2:
{ "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
{ "error": { "message": "{'email': ['User with this email already exists.'], 'phone': ['User with this phone already exists.'], 'username': ['User with this username already exists.']}" }, "status_code": 400, "detail": { "email": [ "User with this email already exists." ], "phone": [ "User with this phone already exists." ], "username": [ "User with this username already exists." ] } }
Поле email не является обязательным. Чтобы не было ошибки при передаче email пустым, это поле можно в параметрах не указывать.
Метод позволяет изменить часть пользовательских данных и возвращает измененные данные пользователя.
Описание - https://api.24h.tv/v2/doc/provider#!/Users/patch_users_user_id
Тип запроса: PATCH
User_ID - полученный при создании пользователя:
<http или https>://api.24h.tv/v2/users/<User_ID>?token=<TOKEN>
Передаваемые параметры:
{
"username": "<username пользователя>",
"first_name": "<Имя пользователя>",
"last_name": "<Фамилия пользователя>",
"provider_uid": "<id в биллинговой системе провайдера>",
"password": "<пароль>", <Только для платформенных клиентов с авторизацией по логину/паролю>,
"is_provider_free": <Доступ к тв не из сети провайдера (false - запретить, true - разрешить)>,
"is_active": <Активность пользователя (false - заблокирован, true - активен)>
}
В ответ будет возвращены данные в json формате. В ответе получите идентификатор пользователя в платформе (ID), его необходимо сохранить и использовать для дальнейшей идентификации:
{ "id": <id пользователя в платформе 24часаТВ>, "username": "<username пользователя>", "first_name": "<Имя пользователя>", "last_name": "<Фамилия пользователя>", "phone": "<Номер телефона>", "email": "<email пользователя>", "timezone": null, "provider": { "id": <ID провайдера в платформе 24часаТВ>, "name": "<Название провайдера>", "proxy": null, "landing": { "shortname": "<Краткое название провайдера>", "logo": null, "url": "", "support": { "phone": "<Телефон провайдера>", "url": "<URL провайдера>" }, "login": { "title": "", "description": "<Сообщение приветствия при регистрации>" } } }, "provider_uid": "<id пользователя в биллинговой системе провайдера>" }
В случае неверных данных будет возвращена ошибка с описанием в json формате.
В случае блокировки пользователя, установкой флага is_active=false, данный пользователь не сможет войти в приложение 24ТВ. При этом подписки на пакеты не отключаются! Если вам необходимо блокировать пользователя, то перед этим остановите все его активные подписки!
Метод получать список всех зарегистрированных пользователей провайдера.
Описание - https://api.24h.tv/v2/doc/provider#!/Users/get_users
Тип запроса: GET
<http или https>://api.24h.tv/v2/users?token=<TOKEN>
В ответ будет возвращены данные в json формате со списком всех пользователей провайдера:
[ { "id": <id пользователя в платформе 24часаТВ>, "username": "<username пользователя>", "first_name": "<Имя пользователя>", "last_name": "<Фамилия пользователя>", "phone": "<Номер телефона>", "email": "<email пользователя>", "timezone": null, "provider": { "id": <ID провайдера в платформе 24часаТВ>, "name": "<Название провайдера>", "proxy": null, "landing": { "shortname": "<Краткое название провайдера>", "logo": null, "url": "", "support": { "phone": "<Телефон провайдера>", "url": "<URL провайдера>" }, "login": { "title": "", "description": "<Сообщение приветствия при регистрации>" } } }, "provider_uid": "<id пользователя в биллинговой системе провайдера>" }, ... список остальных пользователей, вырезан для краткости ] |
При выводе большого списка используется постраничный вывод, поэтому необходимо в запрос добавлять параметры &limit= и &offset= для получения полного списка пользователей.
Поиск пользователей возможен по:
id пользователя в платформе 24ТВ
По номеру телефона или по id в биллинговой системе провайдера.
Поиск по id пользователя:
Описание - https://api.24h.tv/v2/doc/provider#!/Users/get_users_user_id
Тип запроса: GET
<http или https>://api.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>?token=<TOKEN>
В ответ будет возвращены данные в json формате о пользователе провайдера:
В случае неудачного поиск будет возвращена ошибка:
{ "id": <id в платформе 24часаТВ>, "username": "<username пользователя>", "first_name": "<Имя пользователя>", "last_name": "<Фамилия пользователя>", "phone": "<Телефон пользователя>", "email": "<email пользователя>", "timezone": null, "provider": { "id": <ID провайдера в платформе 24часаТВ>, "name": "<Название провайдера>", "proxy": "<PROXY провайдера>", "landing": { "shortname": "<Название ландинг страницы провайдела>", "logo": "<Логотип провайдера>", "url": "", "support": { "url": "<url провайдера>", "phone": "<Телефон провайдера>" }, "login": { "title": "", "description": "<Текст приветствия при регистрации>" } } }, "provider_uid": "<id в биллинговой системе провайдера>" } |
Response Code - 404
{ "error": { "message": "Не найдено." }, "status_code": 404, "detail": "Не найдено." } |
По номеру телефона или по id в биллинговой системе провайдера:
Описание - https://api.24h.tv/v2/doc/provider#!/Users/get_users
Тип запроса: GET
по номеру телефона:
<http или https>://api.24h.tv/v2/users?phone=<Номер телефона абонента>&token=<TOKEN>
по ID в биллинговой системе провайдера:
<http или https>://api.24h.tv/v2/users?provider_uid=<ID пользователя из биллинговой системы провайдера>&token=<TOKEN>
В ответ будет возвращены данные в json формате о пользователе провайдера:
{ "id": <id в платформе 24часаТВ>, "username": "<username пользователя>", "first_name": "<Имя пользователя>", "last_name": "<Фамилия пользователя>", "phone": "<Телефон пользователя>", "email": "<email пользователя>", "timezone": null, "provider": { "id": <ID провайдера в платформе 24часаТВ>, "name": "<Название провайдера>", "proxy": "<PROXY провайдера>", "landing": { "shortname": "<Название ландинг страницы провайдела>", "logo": "<Логотип провайдера>", "url": "", "support": { "url": "<url провайдера>", "phone": "<Телефон провайдера>" }, "login": { "title": "", "description": "<Текст приветствия при регистрации>" } } }, "provider_uid": "<id в биллинговой системе провайдера>" } |
В случае неудачного поиска будет возвращен пустой ответ:
[] |
В платформе 24ТВ пакеты разделены на два типа: Базовые пакеты (в ответе "base": true) и Дополнительные пакеты (в ответе "base": false).
Некоторые базовые пакеты уже включают в себя некоторые дополнительные (максимальный тариф “Всё включено” содержит в себе все дополнительные тарифы).
https://api.24h.tv/v2/doc/provider#!/Packets/get_packets
Будут выведены все пакеты провайдера, в том числе неопубликованные. Пакеты с флагом is_public=false
не будут показываться абоненту в приложении.
На первом уровне списка — базовые пакеты. Чтобы увидеть дополнительные пакеты в виде дерева, добавьте аргумент includes=availables
. Дополнительные пакеты будут в ключе «availables» каждого пакета
Возможные значения параметра includes
:
availables
— получение возможных пакетов для подключения
includes
— получение включенных дополнительных пакетов в базовые
videos
— включение в ответ информации о видеоисточниках, включенных в пакет
Значения includes
можно комбинировать через запятую: includes=availables,videos
В ответ будет возвращены данные в json формате о пакетах провайдера:
[ { "id": <ID пакета>, "name": "<Название пакета>", "description": "<Описание пакета>", "price": "<Стоимость пакета>", "base": true, "videos": [], "available": [ { "id": <ID пакета>, "name": "<Название пакета>", "description": "<Описание пакета>", "price": "<Стоимость пакета>", "base": false, "videos": [], "available": [] }, ... - вырезано для краткости { "id": <ID пакета>, "name": "<Название пакета>", "description": "<Описание пакета>", "price": "<Стоимость пакета>", "base": false, "videos": [], "available": [] } ] }, .... - вырезано для краткости ] |
Без параметра includes
будет возвращен список базовых тарифов.
<http или https>://api.24h.tv/v2/packets?token=<TOKEN>
В ответ будет возвращены данные в json формате о пакетах провайдера:
[ { "id": <ID пакета>, "name": "<Название пакета>", "description": "<Описание пакета>", "price": "<Стоимость пакета>", "base": true }, ... - вырезано для краткости { "id": <ID пакета>, "name": "<Название пакета>", "description": "<Описание пакета>", "price": "<Стоимость пакета>", "base": true } ] |
https://api.24h.tv/v2/doc/provider#!/Packets/get_packets_flat
При запросе с указанием провайдерского токена token
будут выведены все пакеты провайдера, в том числе неопубликованные
При запросе с указанием пользовательского токена access_token
будут выведены только пакеты, видимые этому пользователю
Если нужны только базовые пакеты, добавьте аргумент фильтра is_base=true
. Если только дополнительные, добавьте is_base=false
Описание - https://api.24h.tv/v2/doc/provider#!/Users/post_users_user_id_subscriptions
Тип запроса: POST
<http или https>://api.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/subscriptions?token=<TOKEN>
Передаваемые параметры:
[ { "packet_id": <ID пакета>, "start_at": "2017-09-04T20:15:30.000Z", "end_at": "2017-10-04T20:15:29.000Z", "renew": true, "is_paused": true, "pauses": [ {} ], "message": "string" } ] |
Обязательные параметры:
packet_id - id пакета
renew - включать автопродление подписки true или нет false
В ответ будет возвращен json с информацией о подписке:
Response Code - 200
[{ "id": "<ID подписки>", # Идентификатор подписки "renew": true, # Автообновление подписки "is_paused": false, # Стоит ли подписка на паузе "packet": { "id": <ID пакета>, "name": "<Описание пакета>", # Название пакета "price": "<Стоимость пакета>" # Цена пакета }, "start_at": "2017-09-04T20:15:30.000Z", # Время начала подписки "end_at": "2017-10-04T20:15:29.000Z" # Время окончания подписки (Время должно быть на секунду меньше относительно времени старта) }] |
В случае ошибки:
Response Code - 400
{ "error": { "message": "['You need billing account for subscription.']" }, "status_code": 400, "detail": [ "You need billing account for subscription." ] |
Описание - https://api.24h.tv/v2/doc/provider#!/Users/delete_users_user_id_subscriptions_subscription_id
Тип запроса: DELETE
<http или https>://api.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/subscriptions/<ID подписки>?token=<TOKEN>
В ответ будет возвращен json с информацией о приостановленной подписке:
Response Code - 200
[{ "id": "<ID подписки>", # Идентификатор подписки "renew": true, # Автообновление подписки "is_paused": false, # Стоит ли подписка на паузе "packet": { "id": <ID пакета>, "name": "<Описание пакета>", # Название пакета "price": "<Стоимость пакета>" # Цена пакета }, "start_at": "2017-09-04T20:15:30.000Z", # Время начала подписки "end_at": "2017-10-04T20:15:29.000Z" # Время окончания подписки }] |
В случае ошибки:
Response Code - 400
[] |
Для получения текущих подписок пользователя используется вызов API платформы 24ТВ:
Описание - https://api.24h.tv/v2/doc/provider#!/Users/get_users_user_id_subscriptions
Тип запроса: GET
<http или https>://api.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/subscriptions/current?token=<TOKEN>
В ответе будет содержаться список текущих подписок пользователя в формате json:
[ { "id": "<ID подписки>", "packet": { "id": <ID пакета>, "name": "<Название пакета>", "description": "<Описание пакета>", "price": "<Стоимость пакета>", "base": false }, "start_at": "2017-09-25T16:09:56.000000Z", "end_at": "2017-10-25T16:09:55.000000Z", "renew": true, "is_paused": true, "pauses": [] }, { "id": "<ID подписки>", "packet": { "id": <ID пакета>, "name": "<Название пакета>", "description": "<Описание пакета>", "price": "<Стоимость пакета>", "base": false }, "start_at": "2017-09-24T12:00:00.000000Z", "end_at": "2017-10-24T11:59:59.000000Z", "renew": true, "is_paused": false, "pauses": [] } ]
Для получения списка всех когда либо назначенных подписок используется запрос:
Тип запроса: GET
<http или https>://api.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/subscriptions?token=<TOKEN>
В ответе будет содержаться список всех подписок пользователя в формате json.
Используется при необходимости персонализировать название, описание или цену пакета для любого абонента.
Описание - https://api.24h.tv/v2/doc/provider#!/Packets/post_users_user_id_packets
Тип запроса: POST
<http или https>://api.24h.tv/v2/users/<ID пользователя в платформе 24часаТВ>/packets?token=<TOKEN>
Передаваемые параметры:
{
"name": "<Название пакета для абонента>",
"price": "<Отображаемая стоимость для абонента>",
"description": "<Отображаемое описание пакета для абонента>",
"packet_id": <ID пакета для персонализации>
}
В ответе будет содержаться информация о пакете:
{
"name": "<Название пакета для абонента>",
"description": "<Отображаемое описание для абонента>",
"price": "<Отображаемая стоимость для абонента>",
"packet": {
...
Информация о пакете
}
В случае, если пользователь провайдера желает приостановить свои платные подписки на неопределенное время возможна установка паузы у подписок.
Получение списка подписок установленных на паузу:
Описание - https://api.24h.tv/v2/doc/provider#!/Users/get_users_user_id_subscriptions_subscription_id_pauses
Тип запроса: GET
<http или 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
<http или 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
<http или 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 }
Тип запроса DELETE
<http или 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
<http или 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
<http или 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
<http или 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": "Не найдено." }
Есть возможность отображать баланс напрямую из биллинга интеграционным запросом BALANCE. Данный запрос будет отправлен в сторону провайдера при входе абонента в личный кабинет или настройки в тв приложении. Запрос BALANCE описан ниже в следующем разделе.
Согласно договору необходимо реализовать:
AUTH запрос - автоматический поиск пользователя в биллинговой системе по IP-адресу (реальному или «серому») и привязку пользователя к учетной записи (метод AUTH - аутентификации). Данный функционал должен быть доступен для любого пользователя постоянно
В случае использования «серых» IP-адресов в сети и NAT (преобразование сетевых адресов) - наличие proxy-сервера для направления запросов к Сервису для определения фактических IP-адресов Пользователей (инструкция Установка proxy сервера на стороне провайдера при работе клиентов через NAT)
PACKET запрос - отработку со стороны системы биллинга запросов пользователей на подключение ТВ-пакетов из приложений (метод PACKET). Данный функционал должен быть постоянно включен для всех пользователей. Запросы должны отрабатываться для любых пакетов , кроме бандлов, при наличии положительного баланса на счету пользователя.
списание оплаты за подключаемые из приложения продукты с основного счета пользователя в системе биллинга
На стороне 24ТВ прописываются IP адреса провайдера. При регистрации абонента в 24ТВ с этих IP-адресов, он автоматически попадает/соотносится к провайдеру, после чего оплата возможна только провайдеру. Если абонент ранее зарегистрирован и числится за другим провайдером при этом не имеет платных подписок, то при трёхкратном подряд в сутки запуске приложения с указанных IP адресов, он будет автоматически соотнесен к провайдеру - владельцу IP адресов.
Цель AUTH запроса - установить соответствие у пользователя между системой 24ТВ и биллингом провайдера, в дальнейшем <provider_user_id> будет сообщаться провайдеру в запросе PACKET. При входе в приложение метод AUTH (запрос на получение идентификатора пользователя) придёт в API провайдера, если у пользователя не заполнено поле <provider_user_id> и используется биллинговая схема "simple_auth" (схема устанавливается службой поддержки 24ТВ по запросу провайдера). [cм. также файл “Схема обратной интеграции”]
На указанный провайдером интеграционный URL 24ТВ отправляет POST-запрос (параметры передаются в строке запроса):
<http или https>://<url для интеграции>:<порт>/auth?ip=<ip_address>&phone=<phone>&mbr_id=<user_id>&provider_id=<provider_id>
где:
url для интеграции: порт - url и порт указанный провайдером. Должен заканчиваться на "/" так как далее к этому URL добавляется "auth?ip=..." или "packet?user_id=..." или "cont?user_id=..."
ip_address - ip адрес абонента.
phone - номер мобильного телефона, с которого зарегистрировался абонент.
mbr_id (user_id) - id учетной записи в 24ТВ.
provider_id - id провайдера (админки) в 24ТВ.
Платформа 24ТВ ожидает ответ в формате json:
В случае удачного идентификации абонента в биллинговой системе провайдера id учетной записи или договора:
{ "user_id": <provider_user_id> }
В случае неудачи необходимо вернуть:
{ "status": -1, "err": <код ошибки>, "errmsg": "<Описание ошибки>" }
Список кодов ошибок "err":
-1 Пользователь не найден.
-2 Ошибка регистрации.
Описание ошибки - любое текстовое сообщение.
Данный запрос производится от 24ТВ к биллинговой системе провайдера, когда пользователь желает подключить платный пакет через ТВ-приложение.
Запрос синхронный. Биллинговая система провайдера после получения данного запроса определяет возможность подключения желаемого платного пакета, подключает платный пакет через API платформы 24ТВ (используя метод /v2/users/<user_id>/subscriptions) и возвращает положительный ответ в успешном случае или отрицательный ответ с текстом сообщения об ошибке, которое транслируется в приложение пользователю.
Обращаем внимание, что в сервисе 24ТВ пакеты подключаются на месяц. Поэтому при смене базового пакета должна быть реализована следующая логика:
Если у абонента уже подключен базовый пакет с большей стоимостью - необходимо отменить его автопродление (установкой флага renew=false) и подключить новый пакет с даты окончания текущего.
Если у абонента подключен базовый пакет с меньшей стоимостью - необходимо подключить новый с текущего времени. Для этого необходимо сначала остановить старый базовый пакет путем отправки запроса DELETE /users/{user-id}/subscriptions, после этого отправить запрос в 24часаТВ на подключение нового пакета.
Тип запроса: POST
Запрос: <http или https>://<Интергационный урл>/packet?user_id=<Provider_user_id>&trf_id=<ID платного пакета в платформе 24часаТВ>
В теле запроса будет json такого типа:
{ "user": {
"id": <ID пользователя в платформе 24часаТВ>, "phone": "<Номер телефона пользователя>", "email": "<email пользователя>",
"provider_uid": "<Provider user id – id из биллинговой системы провайдера>", "last_name": "<Фамилия пользователя>",
"username": "<UserName пользователя>", "timezone": "Часовой пояс пользователя, например: Indian/Mauritius", "first_name": "<Имя пользователя>" }, "type": "packet", "packet": { "id": <ID желаемого платного пакета в платформе 24часаТВ>, "price": "<Стоимость пакета>", "is_base": <Тип пакета: true – Базовый, false – дополнительный пакет>, "name": "<Название пакета>" }
}
Можно ориентироваться как на параметры URL, так и на json в теле запроса.
В ответ платформа 24ТВ ожидает json с параметрами - status = 1 - в случае успеха или status != -1 и errmsg c описанием ошибки, которое транслируется в тв приложение
Положительный ответ в json формате:
{"status":1}
Отрицательный ответ в json формате:
{"status":-1,"errmsg":"Недостаточно средств на счету"}
Важно! В случае нехватки денежных средств, запрос PACKET всегда должен возвращать status = -1
В случае других причин используйте любые другие коды с отрицательным значением (-2, -3 и т.п.)
Данный запрос производится от 24ТВ к биллинговой системе провайдера, когда в ТВ приложении на пакете абонент нажимает кнопку "Отключить".
Запрос синхронный. Биллинговой системе провайдера после получения данного запроса определяет возможность отключения желаемого платного пакета, отключает платный пакет через API платформы 24ТВ и возвращает положительный ответ в успешном случае или отрицательный ответ с текстом сообщения об ошибке, которое транслируется в приложение пользователю.
Обращаем внимание, что в сервисе 24часаТВ по агентской схеме пакеты подключаются на срок не менее месяца. Поэтому биллинговая система при запросе пользователя на отключение должен снять автопродление пакета в собственной базе и проинформировать об этом сервис установкой флага renew=false в соответствующей подписке.
Тип запроса: POST
Запрос: <http или https>://<Интергационный урл>/delete_subscription?user_id=<Provider_user_id>&sub_id=<ID подписки в платформе 24часаТВ>
В теле запроса будет json такого типа:
{
"type": "delete_sub",
"user": {
"id": <ID пользователя в платформе 24часаТВ>,
"provider_uid": "<Provider user id - id из биллинговой системы провайдера>",
"username": "<UserName пользователя>",
"first_name": "<Имя пользователя>",
"last_name": "<Фамилия пользователя>",
"phone": "<Номер телефона пользователя>",
"email": "<email пользователя>",
"timezone": "Часовой пояс пользователя, например: Indian/Mauritius",
},
"subscription": {
"packet": {
"id": <ID желаемого платного пакета в платформе 24часаТВ>,
"name": "<Название пакета>"
"price": "<Стоимость пакета>",
"is_base": <Тип пакета: true - Базовый, false - дополнительный пакет>,
},
"start_at": "2018-10-31T18:00:27.953951Z",
"end_at": "2018-11-30T18:13:43.208460Z",
"renew": true,
"is_paused": false
}
}
Положительный ответ в json формате:
{"status":1}
Отрицательный ответ в json формате:
{"status":-1,"errmsg":"<Причина ошибки>"}
Данный запрос отправляется в биллинг провайдера при входе абонента в личный кабинет 24ТВ или настройки приложения. Для включения данного запроса в сторону провайдера необходимо о этом сообщить службе поддержки 24ТВ.
Запрос: <http или https>://<Интергационный урл>/balance?user_id=<Provider_user_id>
В теле запроса будет json такого типа:
{
"type": "balance",
"user": {
"id": <ID пользователя в платформе 24часаТВ>,
"provider_uid": "<Provider user id - id из биллинговой системы провайдера>",
"username": "<UserName пользователя>",
"first_name": "<Имя пользователя>",
"last_name": "<Фамилия пользователя>",
"phone": "<Номер телефона пользователя>",
"email": "<email пользователя>",
"timezone": "Часовой пояс пользователя, например: Indian/Mauritius",
}
}
Положительный ответ в json формате:
{
"status": 1,
"balance": 100.00
}
В случае такого ответа в личном кабинете 24ТВ или в настройках тв приложения будет отображен баланс 100.00 рублей.
Отрицательный ответ в json формате:
{"status":-1,"errmsg":"<Причина ошибки>"}
Посмотреть логи по запросам в биллинг провайдера можно в панели администратора открыв раздел Инструменты https://24htv.platform24.tv/admin/api-requests/
Таймаут по запросам в биллинг провайдера составляет 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 | Проверка корректного отображения баланса из биллинга в тв-приложении | Должен отображаться правильный баланс из билинга в тв-приложении |