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

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

Полное описание (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/

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

1. Создание/изменение пользователя (договора/учётки/услуги)

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

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

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

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

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

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

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

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

Службе поддержки https://t.me/help24htv необходимо предоставить интеграционный URL (API URL) на который платформа 24ТВ будет отправлять запросы.

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

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

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

• После окончания срока действия любого пакета происходит его автоматическое автопродление (если не снят флаг автопродления у этого пакета). При этом по схеме интеграции "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 }

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

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

Тип запроса 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ТВ заложена возможность трансляции баланса из биллинговой системы провайдера в приложения пользователей. При любом изменении баланса у пользователя в биллинговой системе, провайдер может обновить его и в платформе 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 в сторону провайдера из системы 24ТВ.

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

• 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 Ошибка регистрации.

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

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

Данный запрос производится от 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 и т.п.)

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

Данный запрос производится от 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":"<Причина ошибки>"}

Запрос к провайдеру BALANCE.

Данный запрос отправляется в биллинг провайдера при входе абонента в личный кабинет 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”.

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