API
Integration with third-party management systems
Documentation and connection to the REST API
API documentation is built into the platform, you can find it at: http://<your TMS address>/api/provider/swagger-ui.html
API methods are available at http://<your TMS address>/api/provider/
This article does not describe all possible entity fields; a complete list is available in the documentation.
When using the API, your system should undergo simple basic authorization using the administrator login and password, we recommend creating a separate administrator for these purposes in TMS.
The following are examples of curl requests, the examples are given only for information, in real integrations you can use the convenient http client of your programming language.
In real integrations, it is necessary to consider the possible loss of connectivity to the API, error handling and other exceptional cases.
It is recommended to use the API to periodically synchronize your management system and TVIP TMS.
HTTP methods:
GET - getting
POST - create and modify
DELETE - delete
When updating (changing) an entity, a json object can contain only mutable properties, fields that do not require changes can be omitted. When updating, it is necessary to indicate the id of the entity being changed in the json object; when creating the object, the id field is not used.
API methods are available at http://<your TMS address>/api/provider/
This article does not describe all possible entity fields; a complete list is available in the documentation.
When using the API, your system should undergo simple basic authorization using the administrator login and password, we recommend creating a separate administrator for these purposes in TMS.
The following are examples of curl requests, the examples are given only for information, in real integrations you can use the convenient http client of your programming language.
In real integrations, it is necessary to consider the possible loss of connectivity to the API, error handling and other exceptional cases.
It is recommended to use the API to periodically synchronize your management system and TVIP TMS.
HTTP methods:
GET - getting
POST - create and modify
DELETE - delete
When updating (changing) an entity, a json object can contain only mutable properties, fields that do not require changes can be omitted. When updating, it is necessary to indicate the id of the entity being changed in the json object; when creating the object, the id field is not used.
API authorization
When making calls to API methods, you should use basic authorization, an example of its receipt and implementation is given below.
Important to set in header field Accept: application/json
Important to set in header field Accept: application/json
# get Login - password for authorization
echo -ne login:password | base64
bG9naW46cGFzc3dvcmQK
# check by calling account list receiving method
curl -X GET --header 'Authorization: Basic bG9naW46cGFzc3dvcmQK' --header 'Accept: application/json' 'https://tms.example.com/api/provider/accounts' Creating an account through the API
To create an account, you need to create json with an account description, the minimum data necessary for the account is next:
id - user id in TVIP TMS, when creating a user this parameter is omitted, when updating it is required
enable - the property of the account that is responsible for the status of the service, if enable is set to false devices will be authorized, but services will not be available, this flag has to be used in your business logic to enable and disable the service.
login - username that is unique within the provider and is used to authorize devices by the user.
pin_md5 - user password, hashed by md5, is used to authorize devices by the user..
fullname - username, will be displayed on devices after user log-in
provider - provider id
The successful result of the command is a json object, which contains all client properties, including user id, this id will be used in the next steps.
id - user id in TVIP TMS, when creating a user this parameter is omitted, when updating it is required
enable - the property of the account that is responsible for the status of the service, if enable is set to false devices will be authorized, but services will not be available, this flag has to be used in your business logic to enable and disable the service.
login - username that is unique within the provider and is used to authorize devices by the user.
pin_md5 - user password, hashed by md5, is used to authorize devices by the user..
fullname - username, will be displayed on devices after user log-in
provider - provider id
The successful result of the command is a json object, which contains all client properties, including user id, this id will be used in the next steps.
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
}You can see the result of the command in the admin panel
Adding users subscription
Fields required for adding a subscription:
account - user id in TMS (watch the previous step)
start - start date of the service
tarif - tariff id for the service (you can create a tariff and specify its Id in the admin panel)
A successful server response is a json subscription object, the subscription id has to be used to manage this subscription.
All client subscriptions can be obtained by :
/api/provider/account_subscriptions?account=4333
The response will contain a json response containing an array of subscriptions.
account - user id in TMS (watch the previous step)
start - start date of the service
tarif - tariff id for the service (you can create a tariff and specify its Id in the admin panel)
A successful server response is a json subscription object, the subscription id has to be used to manage this subscription.
All client subscriptions can be obtained by :
/api/provider/account_subscriptions?account=4333
The response will contain a json response containing an array of subscriptions.
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
}
The result of the request for tariff plan creation
Subscription cancelling
To manage a subscription (for example, unsubscribe the user), you need to modify:
id - subscription id in TMS (watch in previous step)
stop - field for setting end date of the subscription
A successful server response is a json subscription object with updated fields.
id - subscription id in TMS (watch in previous step)
stop - field for setting end date of the subscription
A successful server response is a json subscription object with updated fields.
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
}Subscription cancelling
After there are no active subscriptions in account, device reports this message. The same message will appear when account is disabled
Account disconnection
User id in TMS should be - 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
}'
# 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": false,
"devices_per_account_limit": null
}Account disconnection result
Contacts
E-mail: sales@tviplabs.com