Подключение к REST API:

Внимание

В этой статье не описываются все возможные поля сущностей, полный список доступен в документации.

При использовании API ваша система должна проходить простую basic авторизацию, используя логин и пароль администратора, советуем создать для этих целей отдельного администратора в TMS.

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

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

Рекомендуется использовать API для периодической синхронизации вашей системы управления и TVIP TMS.

HTTP методы:

  • GET - получение;

  • POST - создание и изменение;

  • DELETE - удаление.

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

Авторизация в API

При выполнении вызовов к методам API необходимо использовать basic авторизацию, ниже дан пример ее получения и выполнения. Важно в header выставлять поле Accept: application/json.

 # get Login - password for authorization
 echo -ne login:password | base64
 bG9naW46cGFzc3dvcmQK

 # check by calling account list receiving method
c url -X GET --header 'Authorization: Basic bG9naW46cGFzc3dvcmQK' --header 'Accept: application/json' 'https://tms.example.com/api/provider/accounts'

Создание аккаунта через API

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

id:

id пользователя в TVIP TMS, при создании пользователя, данный параметр опускается, при обновлении он обязателен.

enable:

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

login:

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

pin_md5:

пароль пользователя, захешированный md5, используется для авторизации устройств пользователем.

fullname:

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

provider:

id провайдера.

Успешный результат выполнения команды - json объект, в котором содержаться все свойства клиента, включая id пользователя, данный id будет использован в следующих шагах.

Пример отправки запроса на создание аккаунта с помощью curl:

curl \
--location \
--request POST 'http://tms.example.com/api/provider/accounts' \
--header 'Authorization: Basic bG9naW46cGFzc3dvcmQK' \
--header 'Content-Type: application/json' \
--data '{
"enabled": true,
"login": "user",
"pin_md5":"25d55ad283aa400af464c76d713c07ad",
"fullname":"First name Last name",
"provider" : 212
}'

В ответе будет содержаться json-структура, содержащая параметры созданного аккаунта:

{
"id": 4333,
"login": "user",
"remote_custom_field": null,
"fullname": "First name Last name",
"pin_md5": null,
"contract_info": null,
"main_address": null,
"account_desc": null,
"provider": 212,
"provider_dto": null,
"region_tag": null,
"region_dto": null,
"enabled": true,
"devices_per_account_limit": null
}

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

../../_images/api_account.png

Добавление подписки пользователю

Поля, необходимые для создания подписки:

account:

id пользователя в TMS (полученный в предыдущем шаге).

start:

дата начала предоставления услуги.

tarif:

id тарифа для услуги (создать тариф и уточнить его Id можно в панели администратора).

Успешный ответ сервера - json объект подписки, id подписки необходимо использовать для управления этой подпиской.

Все подписки клиента можно получить выполнив метод:

/api/provider/account_subscriptions?account=4333

Пример отправки запроса на добавление подписки с помощью curl:

curl \
--location \
--request POST 'http://tms.example.com/api/provider/account_subscriptions' \
--header 'Authorization: Basic bG9naW46cGFzc3dvcmQK' \
--header 'Content-Type: application/json' \
--data '{
"account": 4333,
"start": "2020-05-19T00:00:00+0300",
"tarif": 69
}'

В ответе будет содержаться json-структура, содержащая массив подписок:

{
    "start": "2020-05-19T00:00:00+0300",
    "stop": null,
    "tarif": 69,
    "id": 13592,
    "account": 4333,
    "tarif_dto": null,
    "account_dto": null
}

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

../../_images/api_tariff.png

Отключение подписки пользователю

Для управления подпиской (к примеру отключение), необходимо модифицировать ее:

id:

id подписки в TMS (полученный в предыдущем шаге).

stop:

изменяемое поле, устанавливаем дату окончания подписки.

Пример отправки запроса на отключение подписки с помощью curl:

curl \
--location \
--request POST 'http:/tms.example.com/api/provider/account_subscriptions' \
--header 'Authorization: Basic bG9naW46cGFzc3dvcmQK' \
--header 'Content-Type: application/json' \
--data '{
  "id" : 13592,
  "stop": "2020-05-20T00:00:00+0300"
}'

В ответе сервера будет содержаться json-объект подписки с обновленными полями:

{
    "start": "2020-05-19T00:00:00+0300",
    "stop": "2020-05-20T00:00:00+0300",
    "tarif": 69,
    "id": 13592,
    "account": 4333,
    "tarif_dto": null,
    "account_dto": null
}

Результат выполнения команды можно увидеть в настройках аккаунта:

../../_images/subscript_1.png

После обновления информации по подпискам устройство перепроверяет все доступные тарифы, в случае если в учетной записи пользователя нет активных подписок - устройство сообщит об этом соответствующим сообщением. Это же сообщение появится при отключении аккаунта.

../../_images/subscript_2.png

Отключение аккаунта

По id пользователя в TMS выставляем флаг enabled: false. Например с помощью curl это можно сделать следующим образом:

curl \
--location --request POST 'http://tms.example.com/api/provider/accounts' \
--header 'Authorization: Basic bG9naW46cGFzc3dvcmQK' \
--header 'Content-Type: application/json' \
--data '{
"enabled": false,
"id": 4333
}'

В ответе сервера будет содержаться json-объект аккаунта с обновленными полями:

{
"id": 4333,
"login": "user",
"remote_custom_field": null,
"fullname": "First name Last name",
"pin_md5": null,
"contract_info": null,
"main_address": null,
"account_desc": null,
"provider": 212,
"provider_dto": null,
"region_tag": null,
"region_dto": null,
"enabled": false,
"devices_per_account_limit": null
}

Результат выполнения команды можно увидеть в настройках аккаунта:

../../_images/disconnection.png

Отправка команд на устройства через API

С помощью Provider API возможно отправлять команды на клиентские устройства. Для этого необходимо отправить на сервер TMS запрос на выполнение команды, после чего запрос будет проанализирован и на обозначенные в нём клиентские устройства со стороны TMS по вебсокет-соединению будет отправлена эта команда. Для отправки с помощью Provider API доступны следующие команды:

user_message:

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

refresh_channel_list:

Cлужит для обновления списка каналов на устройстве: после получения этой команды устройство с помощью TVIP API запрашивет у TMS список доступных для него каналов через эндпоинт channles.json.

reinit:

Повторная инициализация устройства на серверe TMS - при выполнении команды устройсво повторно проходит аутентификацию, запрашивает информацию о сервере, аккаунте и списке доступных каналов.

restart:

Перезапуск медиа-центра Tvip. При отправке на другие типы клиентских устройств будет проигнорированно.

switch_to_channel:

Переключение канала на устройстве.

В общем виде URL отправки команд выглядит следующим образом:

POST https://<tms_server>/api/provider/commands/send/<recipients>?broadcast=false

где <tms_server> - доменное имя сервера TMS, а <recipients> - класс получателей сообщения, который может быть одним из следущих:

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

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

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

Обобщённое тело запроса отправки команды выглядит следующим образом:

{
  "ids": [
    <ids>
  ],
  "commands": [
    {
      "command": "<command_name>"
      ...
    }
  ]
}

В структуре тела запроса основными атрибутами являются массивы ids и commands.

Массив ids содержит в себе идентификаторы сущностей, класс которых выбран в качестве получателя в URL запроса. Таким образом, он конкретизирует список тех, кому отправляется команда. Например в случае, если в качестве получателя в URL запроса указан accounts, а в массиве ids перечислены идентификаторы 2, 6, 51, то команда будет выполнена на всех клиентских устройствах, связанных в TMS с пользователями, идентификаторы которых - 2, 6 и 51, при условии, что эти устройства в момент отправки команды будут подключены к TMS. Но в случае если в качестве получателя в URL запроса указан devices, то при тех же идентификаторах, перечисленных в массиве ids, команда будет выполнена только на устройствах c идентификаторами 2, 6, 51 (также при условии наличия соединения между ними и TMS в момент отправки команды).

В массиве commands содержатся объекты команд, отправляемых на клиентское устройство - таким образм в теле запроса может быть задана как одна команда, так и несколько. Кажды такой объект содержит наименование команды, и праметры её применения:

command:

Наименование команды.

type:

Тип отправляемого сообщения - notfy или confirm. Свойство актуально только для команды user_message.

post_time:

Время в формате YYYY-MM-DDThh:mm:ss по GMT не ранее которого команда должна быть отправлена на клиентские устройства. Свойство актуально только при отложенном времени выполнения команды.

ttl:

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

Предупреждение

На данный момент при работе с отправкой команд через Provider API поле ttl должно заполнятся в формате Unix timestamp.

text:

Текст отправляемого пользователю сообщения. Свойство актуально только для команды user_message.

title:

Заголовок отправляемого пользователю сообщения. Свойство актуально только для команды user_message c типом confirm.

delay:

Время в секундах в течении которого сообщение отображается на дисплее клиентского утсройства. Свойство актуально только для команды user_message c типом notify.

channel:

Идентификатор канала, на который который осуществляется переключение. Свойство актуально только для команды switch_to_channel.

use_as_push:

Свойство управляющее тем, будут ли отправляемые сообщения отображаться на устройствах в виде push-уведомлений. Свойство актуально только для команды user_message.

Пример отправки команды для обновения списка каналов

В этом примере команда будет отправлена нескольким пользователям, идетификаторы которых в TMS - 3 и 11. Пусть доменное имя сервера будет tms.example.com.

Так как команда должна быть выполнена для конкретных пользователей, то в эндпоинте запроса в качестве класса получателя будет указан accounts:

POST https://tms.example.com/api/provider/commands/send/accounts?broadcast=false

Как упоминалось выше, для обновления списка каналов используестя команда refresh_channel_list. Так как в нашем случае команда refresh_channel_list должна быть отправлена немедленно, то время отправки для неё не задаётся и единственным параметром являетcя наименование самой команды. Тело запроса для отправки этой команды будет выглядеть следующим образом:

{
  "ids": [
    3, 11
  ],
  "commands": [
    {
      "command": "refresh_channel_list"
    }
  ]
}

В этой json-структуре поле ids - массив идентификаторов сущностей, класс которых выбран в качестве получателя: в нашем случае это идентификаторы пользователей. Таком образом, команда обновления списка каналов будет получена и выполнена всеми клиетскими устройствами пользователей 3 и 11, которые будут связаны с TMS websocket-соединением.

Вот как выглядит отправка запроса на выполнение этой комманды c помощью curl:

curl -X 'POST' \
  'https://tms.example.com/api/provider/commands/send/accounts?broadcast=false' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "ids": [
    3, 11
  ],
  "commands": [
    {
      "command": "refresh_channel_list"
    }
  ]
}'

В случае успешной обработки запроса, в качестве ответа от сервера будет получен json-объект с соотвестующим параметром:

{
  "response": true
}

Пример отправки сообщения на клиентские устройства

В этом примере сообщение будет отправлено всем пользователям провайдера, идентификатор которого в TMS - 1. Сообщение будет требовать подтверждения перед закрытием на клиентском устройстве. Пусть в нашем случае сообщение должно быть отправлено после наступлнения конкретного времени - например 31 декабря 2025 года 12:00 по GMT. Заголовок сообщения - «Дорогие абоненты!», текст сообщения - «С наступающими праздниками!».

Так как команда должна быть выполнена для всех пользователей провайдера, то в эндпоинте запроса в качестве класса получателя будет указан providers:

POST https://tms.example.com/api/provider/commands/send/providers?broadcast=false

В теле нашего запроса на отправку сообщения массив ids содержит в себе единственный идентификатор провайдера. В массиве commands будет записан один объект команды - для отправки сообщения пользователю используется команда user_message. Помимо наименования команды, в случае отправки сообщения также требуется указать тип сообщения (type) - так как мы используем сообщение с подтверждением, то в данном случае его типом будет confirm. Для сообщения с подтверждением также требуется указывать текст сообщения (text) и его заголовок (title).

Примечание

При отправке сообщения типа notify прописывать в структуре команды заголовок сообщения(title) не требуется - при его наличии в теле запроса он будет проигнорирован и не отобразится на клиентском устройстве.

Также помимо этого в нашем случае требуется указать время, после которого команда должна быть отправлена пользователям (post_time). Таким образом, заполнив эти параметры значениями, соотвествующими нашим условиям, мы получаем следующее тело запроса на отправку сообщений:

{
  "ids": [
    1
  ],
  "commands": [
    {
      "command": "user_message",
      "type": "confirm",
      "title": "Дорогие абоненты!",
      "text": "С наступающими праздниками!",
      "post_time": "2025-12-31T12:00:00"
    }
  ]
}

Вот как выглядит отправка запроса на выполнение этой комманды c помощью curl:

curl -X 'POST' \
  'https://tms.example.com/api/provider/commands/send/providers?broadcast=false' \
  -H 'accept: */*' \
  -H 'Authorization: Basic c2VnYWw6bkVmQzlkczQmZE5FXlFw' \
  -H 'Content-Type: application/json' \
  -d '{
  "ids": [
    1
  ],
  "commands": [
    {
      "command": "user_message",
      "type": "confirm",
      "title": "Дорогие абоненты!",
      "text": "С наступающими праздниками!",
      "post_time": "2025-12-31T12:00:00"
    }
  ]
}'

Как и в предыдущеем примере, в качестве ответа на успешный запрос будет получен следующий ответ:

{
  "response": true
}