OPEN API

You can get Open API service from your service provider.

←Back

1.1 Parameter encoding

Parameter encoding is UTF-8 as standard.

Please refer to: http://en.wikipedia.org/wiki/UTF-8

←Back

1.2 Time format

Time format is UNIX timestamp.

Please refer to: https://en.wikipedia.org/wiki/Unix_time

←Back

1.3 HTTP MIME

application/json; charset=UTF-8

←Back

1.4 The response JSON format

{"code":0,"message":""}

If code != 0, it means request is error ,please refer to Chapter 3.

Message is the code description, or it’s empty.

←Back

2.1 Get access token

Purpose

Get access token for the others requests, each api must contain the access token. The access token is valid for 2 hours, so we don't need refresh it frequently. We suggest refreshing the access token in every 90 minutes. When you request a new access token, the old one will be invalid immediately.

Request type

GET

Parameters

Parameter Type Required Description
time long true The time when the client sends request
account string true Account
signature string true Encrypted signature,the algorithm is:md5(md5(password) + time),md5 use 32 lower-case characters.

URI

/api/authorization

Example

The password=Abc@34590，md5(md5(Abc@34590) + 1556243443) will calculate out the result signature=3844afd2c3bf68f0f3f4aa0a9ee8ee6c

So the request is: http://api.vitanalog.com.br/api/authorization?time=1556243443&account=test&signature=3844afd2c3bf68f0f3f4aa0a9ee8ee6c

Response Description

JSON KEY Value type Description
record Object
access_token string The access token
expires in long access_token expire time in seconds

Response JSON demo

{
    "record": {
        "access_token": "ACCESS_TOKEN",
        "expires_in": 7200
    },
    "code": 0
}
←Back

2.2 Track

Purpose

Get the latest coordinate data for tracking device.

Request type

GET

Parameters

Parameter Type Required Description
access_token string true The accesstoken
imeis string true Target IMEI list, separated by comma, max 100 IMEIs in one request.

URI

/api/track

Example

http://api.vitanalog.com.br/api/track?access_token={ACCESS_TOKEN}&imeis=358899051025339,355139000000234

Response description

JSON KEY Value type Description
imei string The imei of the target
servertime long Current server time
gpstime long Gps time
hearttime long Heart time, the last time when the target sent data.
systemtime long The system time when the target sent gps data.
longitude double Longitude
latitude double latitude
course int course(Noth is 0, clockwise increase ,max 360.)
speed int speed(KM/H)
acctime long ACC status kept time interval in seconds
accstatus int ACC status
1:ACC ON，
0:ACC OFF,
-1:No acc status
doorstatus int Door status
1:Door open，
0:Door closed，
-1:No door status
chargestatus int Charging status
1:Charging，
0:Not in charging，
-1:No such status
oilpowerstatus int Fuel status，
1:Fuel supply ok，
0:Fuel supply off，
-1:No such status
defencestatus int Defence status
1:Defence on，
0:Defence off，
-1:No such status
datastatus int 1:Never online,
2:OK,
3:Expired,
4:Offline,
5:Block
battery int The battery
-1:No battery status
mileage int mileage(unit:m)
-1:No mileage.
todaymileage long todaymileage(unit:m)
-1:No todaymileage.

Response JSON demo

{
    "record": [
        {
        "imei": "358899051025339",
        "course": 195,
        "systemtime": 1419905754,
        "gpstime": 1419906052,
        "speed": 0,
        "hearttime": 1419906952,
        "servertime": 1420964313,
        "longitude": 113.909813,
        "latitude": 22.583197,
        "acctime": 1400,
        "accstatus": 1,
        "doorstatus": 0,
        "chargestatus": 0,
        "oilpowerstatus": 1,
        "defencestatus": 0,
        "datastatus": 2,
        "battery": 100,
        "mileage": 51654
        "todaymileage": 15654
        }
    ],
    "code": 0
}

More info

To get device's status, you can follow the flow chart below:

track flow

←Back

2.3 Playback

Purpose

Get the GPS data of the target in the time period.

Request type

GET

Parameters

Parameter Type Required Description
access_token string true The access token
imei string true Target's IMEI
begintime long true Begin time
endtime long true End time

URI

/api/playback

Example

http://api.vitanalog.com.br/api/playback?access_token={ACCESS_TOKEN}&imei=358899051025339&begintime=1406746394&endtime=1407746394

Response description

JSON KEY Value type Description
record String Data is separated by semicolon，the data in each group is:
longitude,latitude,gpstime,speed,course

Response JSON demo

{
"record": "113.97196,22.568616,1406858664,0,228;113.97196,22.56861,1406858684,0,228;113.97196,22.56861,1406858704,0,228;113.97196,22.56861,1406858724,0,228;113.97196,22.56861,1406858724,0,228;113.97196,22.56861,1406858724,0,228;113.97196,22.56861,1406858724,0,228;113.971934,22.568583,1406858780,0,61;113.971925,22.568585,1406858800,0,61",
"code": 0
}

Remark

This api max return 1000 GPS records at one time, when the client get 1000 records, the client has to request next 1000 records, in this request ,the begin time is the last 1000th record’s gpstime, until client get the records less than 1000. When you get the records less than 1000, it means you’ve got all the GPS records.

←Back

2.4 Create Geofence

Purpose

Create a circle geofence.

Request type

POST

Parameters

Parameter Type Required Description
access_token string true The access token
imei string true Target's IMEI
efencename string true The name of Geofence
alarmtype int true Alarm type(0:out,1:in,2:in/out)
longitude double true The longitude of the geofence center
latitude double true The latitude of the geofence center
radius int true Geofence radius(100~5000,unit:meter)

URI

/api/geofence/create

Example

http://api.vitanalog.com.br/api/geofence/create?access_token={ACCESS_TOKEN}&imei=358899051025339&efencename=home&alarmtype=0&longitude=113.97196&latitude=22.56861&radius=300

Response JSON demo

{"code":0}

How to send a command?

First call the send command api(2.5) to get command id. then call the query command status api(2.6) in loop until the command status is 1(Respond), max try 30 times, and then we consider the command is timeout.

←Back

2.5 Send command

Purpose

send a command to device from server.

Request type

POST

Parameters

Parameter Type Required Description
access_token string true The access token
imei string true Target's IMEI
command string true

The command

RELAY,1: Stop Engine

RELAY,0: Restore Engine

RESET: Reset device

LOCKDOOR : Lock Door

UNLOCKDOOR : Unlock Door

SET_MILEAGE : Set Mileage
paramData string false

When you choose to set mileage, you must to fill in paramData

example: {"mileage":"30"}

URI

/api/command/send

Example

http://api.vitanalog.com.br/api/command/send?access_token={ACCESS_TOKEN}&imei=358899051025339&command=RELAY,1

Response description

JSON KEY Value type Description
record Object
commandid string The id to query command response.

Response JSON demo

{
    "record": {
        "commandid": "1B454"
    },
    "code": 0
}
←Back

2.6 Query command response

Purpose

query the command response.

Request type

POST

Parameters

Parameter Type Required Description
access_token string true The access token
commandid string true The id returned from send command

URI

/api/command/query

Example

http://api.vitanalog.com.br/api/command/query?access_token={ACCESS_TOKEN}&commandid=1B454

Response description

JSON KEY Value type Description
record Object
response string The command response
commandstatus int

Command status

1: has received response from device

0: not receive response from device

Response JSON demo

{
    "record": {
        "response": "Cut off the fuel supply: Success! Speed: 2km/h.",
        "commandstatus": 1
    },
    "code": 0
}

Remark

This api query once every 1 second, up to 30 seconds.

←Back

2.7 Get device list

Purpose

Get device list. (Return maximum 500pcs devices for each account.)

Request type

GET

Parameters

Parameter Type Required Description
access_token string true The access token
account string false Account

URI

/api/device/list

Example

http://api.vitanalog.com.br/api/device/list?access_token={ACCESS_TOKEN}&account=demo

Response description

JSON KEY Value type Description
record Object
imei string Target's IMEI
devicename String Device name
devicetype String Device model
platenumber String Licence plate number
onlinetime long Device first online time
platformduetime long Device platform expire time
simcard String SIM card
iccid String ICCID
activatedtime long Device activated time
userduetime long Device user expire time

Response JSON demo

{
    "code": 0,
    "record": [
        {
            "imei": "512345678901234",
            "devicename": "VT05S-01234",
            "devicetype": "VT05S",
            "platenumber": "TheOne",
            "onlinetime": 0,
            "platformduetime": 0,
            "simcard": "7557862586",
            "iccid": "89966415211160402250",
            "activatedtime": 0,
            "userduetime": 0
        },
        {
            "imei": "123456789123456",
            "devicename": "VT05S-23456",
            "devicetype": "VT05S",
            "platenumber": "",
            "onlinetime": 1419905754,
            "platformduetime": 1588603848,
            "simcard": "",
            "iccid": "",
            "activatedtime": 1419805754,
            "userduetime": 1589603848
        }
    ]
}
←Back

2.8 Get device alarm information

Purpose

Get the device(s) alarm information in the time period.

Request type

GET

Parameters

Parameter Type Required Description
access_token string true The access token
imei string true Target IMEI
begintime long true Begin time
endtime long true End time

URI

/api/alarm/list

Example

http://api.vitanalog.com.br/api/alarm/list?access_token={ACCESS_TOKEN}&imei=358899051025339&begintime=1406746394&endtime=1407746394

Response description

JSON KEY Value type Description
record String Data is separated by semicolon，the data in each group is: alarm type, longitude, latitude, gpstime, system time,speed,course, Geo-fence ID

Response JSON demo

{
    "code": 0,
    "record": "27,113.885888,22.580592,1541575497,1541575507,40,40,0"
}

Note:

This API max return 100 alarm records at one time, when the client get 100 records, the client has to request next 100 records, in this request ,the begin time is the last 100th record's system time, until client get the records less than 100. When you get the records less than 100, it means you’ve got all the alarm records.

Alarm type Description Remark
1 sosAlarm
2 lowBatteryAlarm
3 powerDisconnectAlarm
4 vibrationAlarm
5 geoFenceInAlarm
6 geoFenceOutAlarm
7 speedingAlarm
8 carMoveAlarm
9 engineOn
10 engineOff
11 tireTemperatureAlarm
12 tireLeakPressureAlarm
13 tireLowPressureAlarm
14 tireHighPressureAlarm
15 gpsDeadZoneInAlarm
16 gpsDeadZoneOutAlarm
17 obdDtcAlarm
18 disassembleAlarm
19 powerOffAlarm
20 collisionAlarm
21 dropAlarm
22 routeAlarm
23 rapidAccelerationAlarm
24 rapidDecelerationAlarm
25 sharpTurnAlarm
26 dooropenAlarm
27 doorcloseAlarm
28 offlineAlarm
29 engineIdleAlarm
30 parkingAlarm
31 oilLeakAlertAlarm
32 oilTheftAlertAlarm
33 jammingAlarm
34 restrictedDrivingAlarm
35 lowTemperatureAlarm
36 highTemperatureAlarm
37 dumpSwitchOnAlarm
38 dumpSwitchOffAlarm
39 armAlarm
40 rolloverAlarm
41 fatigueDrivingAlarm
42 lackBreakFatigueDrivingAlarm
43 lowOilAlarm
44 lowExternalBatteryAlarm
←Back

2.9 Block an account

Purpose

Block an account.

Request type

POST

Parameters

Parameter Type Required Description
access_token string true The access token
account string true Account

URI

/api/user/block

Example

http://api.vitanalog.com.br/api/user/block?access_token={ACCESS_TOKEN}&account=demo

Response JSON demo

{
    "code": 0
}
←Back

2.10 Unblock an account

Purpose

Unblock an account.

Request type

POST

Parameters

Parameter Type Required Description
access_token string true The access token
account string true Account

URI

/api/user/unblock

Example

http://api.vitanalog.com.br/api/user/unblock?access_token={ACCESS_TOKEN}&account=demo

Response JSON demo

{
    "code": 0
}
←Back

2.11 Get account information

Purpose

Get the account's brief information.

Request type

GET

Parameters

Parameter Type Required Description
access_token string true The access token
account string true Account

URI

/api/user/info

Example

http://api.vitanalog.com.br/api/user/info?access_token={ACCESS_TOKEN}&account=demo

Response description

JSON KEY Value type Description
record Object
account String Account
username String User name
email String Email address
mobile String Mobile number
telephone String Telephone
createtime long Create time
roletype int 1 Distributor, 2 End user, 3 Virtual account
blockstatus int 0:block
1:unblock

Response JSON demo

{
    "code": 0,
    "record": {
        "createtime": 1562570435,
        "mobile": "",
        "telephone": "",
        "roletype": 1,
        "account": "demo",
        "email": "openapidemo@gmail.com",
        "blockstatus": 1,
        "username": "openapidemo"
     }
}
←Back

2.12 Get device basic information by IMEIs

Purpose

Get the device(s) basic information according to IMEIs. (Maximum 100pcs in one request.)

Request type

GET

Parameters

Parameter Type Required Description
access_token string true The access token
imeis string true Target IMEI list, separated by comma, max 100 IMEIs in one request.

URI

/api/device/detail

Example

http://api.vitanalog.com.br/api/device/detail?access_token={ACCESS_TOKEN}&imeis=358899051025339,355139000000234

Response description

JSON KEY Value type Description
record Object
imei string Target's IMEI
devicename String Device name
devicetype String Device model
platenumber String Licence plate number
onlinetime long Device first online time
platformduetime long Device platform expire time
simcard String SIM card
iccid String ICCID
activatedtime long Device activated time
userduetime long Device user expire time

Response JSON demo

{
    "code": 0,
    "record": [
        {
            "imei": "512345678901234",
            "devicename": "VT05S-01234",
            "devicetype": "VT05S",
            "platenumber": "TheOne",
            "onlinetime": 0,
            "platformduetime": 0,
            "simcard": "7557862586",
            "iccid": "89966415211160402250",
            "activatedtime": 0,
            "userduetime": 0
        },
        {
            "imei": "123456789123456",
            "devicename": "VT05S-23456",
            "devicetype": "VT05S",
            "platenumber": "",
            "onlinetime": 1419905754,
            "platformduetime": 1588603848,
            "simcard": "",
            "iccid": "",
            "activatedtime": 1419805754,
            "userduetime": 1589603848
        }
    ]
}
←Back

2.13 Send message

Purpose

Send message to account.

Request type

POST

Parameters

Parameter Type Required Description
access_token string true The access token
accounts string true Account list, separated by comma, max 200 accounts in one request.
content string true Max. of 300 characters.

URI

/api/message/send

Example

http://api.vitanalog.com.br/api/message/send?access_token={ACCESS_TOKEN}&accounts=test,name&content=Hello

Response JSON demo

{
    "code": 0
}
←Back

2.14 Mileage report

Purpose

Get mileage report of devices in the time period.

Request type

GET

Parameters

Parameter Type Required Description
access_token string true The access token
imeis string true Target IMEI list, separated by comma, max 100 IMEIs in one request.
begintime long true Begin time. The minute of begintime can only be 0 or 30, for example 01:00, 02:30.
endtime long true End time. The minute of endtime can only be 0 or 30, for example 01:00, 02:30.

* The begintime is included ,endtime is not included.
* The maximum interval between begintime and endtime is 7 days.

URI

/api/device/mileage

Example

http://api.vitanalog.com.br/api/device/mileage?access_token={ACCESS_TOKEN}&imeis=351000091413001,351000091413002,351000091413003,351000091413004&begintime=1631721600&endtime=1631808000

Response Description

JSON KEY Value type Description
record Array
imei string Device imei
mileage double mileage of device, in km

Response JSON demo

{
    "record": [
        {
            "imei": "351000091413001",
            "mileage": 338.21
        },
        {
            "imei": "351000091413002",
            "mileage": 500.56
        },
        {
            "imei": "351000091413003",
            "mileage": 280.87
        },
        {
            "imei": "351000091413004",
            "mileage": 621.21
        }
    ],
    "code": 0
}
←Back

2.15 Get sub-customer list

Purpose

Get sub-customer list. (Return maximum 500pcs users.)

Request type

GET

Parameters

Parameter Type Required Description
access_token string true The access token
account string false Account

URI

/api/user/list

Example

http://api.vitanalog.com.br/api/user/list?access_token={ACCESS_TOKEN}&account=demo

Response description

JSON KEY Value type Description
record Object
account String Account
username String User name
email String Email address
mobile String Mobile number
telephone String Telephone
createtime long Create time
roletype int 1 Distributor, 2 End user, 3 Virtual account
blockstatus int 0:block
1:unblock

Response JSON demo

{
"code": 0,
"record": [
        {
           "createtime": 1562570435,
           "mobile": "",
           "telephone": "",
           "roletype": 1,
           "account": "demo",
           "email": "openapidemo@gmail.com",
           "blockstatus": 1,
           "username": "openapidemo"
        },
        {
           "createtime": 1562670132,
           "mobile": "",
           "telephone": "",
           "roletype": 1,
           "account": "demotest",
           "email": "demotest@gmail.com",
           "blockstatus": 1,
           "username": "demotest name"
        }
    ]
}
←Back

2.16 Modify sub-customer password

Purpose

Modify sub-customer password.

Request type

POST

Parameters

Parameter Type Required Description
access_token string true The access token
account string true Account
password string true the algorithm is:md5(password),md5 use 32 lower-case characters.

URI

/api/user/password/set

Example

If the new password is Abc@34590，then md5(Abc@34590) will calculate out the parameter password=9d591136280b3ec563e3062dbb6f915b

http://api.vitanalog.com.br/api/user/password/set?access_token={ACCESS_TOKEN}&account=monitorcenter&password=9d591136280b3ec563e3062dbb6f915b

Response JSON demo

{
    "code": 0,
}

3. Error code

Code Description Remark
10000 System error
10001 Unknown request
10002 Login timeout
10003 Not login yet
10004 Parameter error
10005 Missing required parameter
10006 The parameter is out of range
10007 Permission denied
10009 Request is too frequency
10010 Access token doesn’t exist
10011 Access token is invalid
10012 Access token is out of date
10013 IMEI is not authorized
10014 Request time error
10016 Account is blocked
20001 Account or password error
20005 Target doesn't exist.
20017 Device is offline.
20018 Send command fail.
20023 No Data.
20046 Target is expired.
20048 Unsupported command.
20089 Device is blocked.
Vitana Logistica