Подключение к 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 \
--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
}'
# server response
{
"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

В ответе будет содержаться 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
}'

# server response

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

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

Успешный ответ сервера - 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"
}'
# server response
{
    "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 \
--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
}

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

../../_images/disconnection.png