API
Интеграция с сторонними системами управления
Документация и подключение к REST API
Документация к API встроена в платформу, вы можете ее найти по адресу: http://<адрес вашего TMS>/api/provider/swagger-ui.html

Методы API доступны по адресу http://<адрес вашего TMS>/api/provider/

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

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

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

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

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

HTTP методы:
GET - получение
POST - создание и изменение
DELETE - удаление

При обновлении (изменении) сущности, json объект может содержать только изменяемые свойства, поля не требующие изменений могут быть опущены. При обновлении необходимо в json объекте указывать id изменяемой сущности, при создании объекта поле id не используется.
Авторизация в API
При выполнении вызовов к методам API необходимо использовать basic авторизацию, ниже дан пример ее получения и выполнения.
Важно в header выставлять поле Accept: application/json
# получаем связку Login - пароль для авторизации
echo -ne login:password | base64
bG9naW46cGFzc3dvcmQK 

#проверяем, вызовом метода получения списка аккаунтов
curl -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 \
--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
}'

# ответ от сервера
{
    "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
}
Результат выполнения команды можно увидеть в панели администратора

Добавление подписки пользователю
Поля, необходимые для создания подписки:

account - id пользователя в TMS (полученный в предыдущем шаге)
start - дата начала предоставления услуги
tarif - id тарифа для услуги (создать тариф и уточнить его Id можно в панели администратора)

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

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

/api/provider/account_subscriptions?account=4333
В ответе будет содержаться json ответ, содержащий массив подписок.
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
}'

# ответ от сервера

{
    "start": "2020-05-19T00:00:00+0300",
    "stop": null,
    "tarif": 69,
    "id": 13592,
    "account": 4333,
    "tarif_dto": null,
    "account_dto": null
}
Результат выполнения запроса на создание тарифного плана

Отключение подписки пользователю
Для управления подпиской (к примеру отключение), необходимо модифицировать ее:
id - id подписки в TMS (полученный в предыдущем шаге)
stop - изменяемое поле, устанавливаем дату окончания подписки

Успешный ответ сервера - json объект подписки с обновленными полями.
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"
}'
# ответ сервера
{
    "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
}
Отключение подписки

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

Отключение аккаунта
По id пользователя в TMS выставляем флаг enabled: false
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
}'

# ответ от сервера

{
    "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
}
Результат отключения аккаунта

Контакты
Санкт-Петербург, Серебристый бульвар дом 17 корпус 1
Phone:
+7 (812) 670-46-56
E-mail: sales@tviplabs.com