Page Comparison

...

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

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

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

...

{
  "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 пустым, это поле можно в параметрах не указывать.

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

...

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

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

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

...

[
  {
    "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=.

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

...

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

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

...

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

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часаТВ>/packets?token=<TOKEN>

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

{
    "name": "<Название пакета для абонента>",
    "price": "<Отображаемая стоимость для абонента>",
    "description": "<Отображаемое описание пакета для абонента>",
    "packet_id": <ID пакета для персонализации>
}

...

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

Параметры:

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

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

...

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

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

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

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

https://<API URL>/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":"<Причина ошибки>"} 

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

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

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

...

В случае использования «серых» 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 учетной записи или договора:

{
    "user_id": <provider_user_id>
}

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

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

Список кодов ошибок "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 такого типа:

{
    "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

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

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

...

, он описан в следующем разделе.

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

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

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

• 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 учетной записи или договора:

{
    "user_id": <provider_user_id>
}

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

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

Список кодов ошибок "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 такого типа:

{
    "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

Запрос: https://<API URL>/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ТВ (включается опция “Запрашивать баланс абонентов из биллинга”).

https://<API URL>/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":"<Причина ошибки>"} 

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

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

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

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

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

...

...