1 General
This documents introduces WECON V-BOX HTTP API. And this document also shows some examples. All example is tested from postman application.
Transport protocol: HTTP protocol
Server address:
China:
Asean:
Europe:
For ASEAN server V-BOX, now can use http, the server address is api.asean.v-box.net.
The common KEY is:
comid=2
comkey=589625dce895454dbff9782c299db156
screctkey=f1cd9351930d4e589922edbcf3b09a7c
For EU server V-BOX, now can use http, the server address is api.eu.v-box.net.
The common KEY is:
comid=100
comkey=8919244ff15d441bae4b944b112a33ea
screctkey=f1cd9351930d4e589922edbcf3b09a7c
1.1 Interface parameter description
Global parameters
The following acturls need to have global parameters (The global parameter client is put into the JSON format and placed in the common parameters of the Headers)
The returned result represented by Json and case sensitive:
1).Abnormal
{"code" : 403, "msg" : "SessionID (user session ID) invalid", "reqId": "1502074141465"}
2).Normal
{"code" : 200 , "result": {}, "msg" : "ok", "reqId":"1502074141465"}
State code description
1.2 Example key and value
1).comid=2
2).comkey=589625dce895454dbff9782c299db156
3).screctkey=f1cd9351930d4e589922edbcf3b09a7c
4).ts=1573897380
2 Basic API
2.1 Login operation
2.1.1 Parameters
| Acturl | we-data/login | |
| Function | Login with username, email, phone number | |
| Parameters | Items | Description |
| alias | Username, email, phone number | |
| password | Password (Encrypted with md5) | |
| Return value | Items | Description |
| utype | User Type: 1-Manage Account, 2-Viewer Account | |
| sid | User session ID | |
2.1.2 Operating procedures
Setp1: Set http: http://api.v-box.net/box-data/api/we-data/login
Setp2: Set parameters on Params
alias: weconuser
password: 599a3c736c04e196c58a29f43778f7ea(Wecon159)
Step3: Get sign
alias=weconuser&comid=2&compvtkey=589625dce895454dbff9782c299db156&password=599a3c736c04e196c58a29f43778f7ea&ts=1573897380&key=f1cd9351930d4e589922edbcf3b09a7c
MD5 value: 997513ff1320862f0cbb9ce19d0bd253
Step4: Set common of header
{"comid":"2","compvtkey":"589625dce895454dbff9782c299db156","ts":"1573897380","sign":"997513ff1320862f0cbb9ce19d0bd253"}
2.1.3 Result
{
"code": 200,
"msg": "ok",
"reqId": "1573899119000",
"result": {
"utype": 1,
"ztRole": 1,
"sid": "2d7bfd344aa64d8ebc9beea0e4dad8ad"
}
}
3 Service data APIs
3.1 V-Box list
3.1.1 Parameters
3.1.2 Operating procedures
Step1: Set http: http://api.v-box.net/box-data/api/we-data/boxs
Step2: Set parameters on Params
No parameters for this acturl, so no need to set.
Step3: Get sign
comid=2&compvtkey=589625dce895454dbff9782c299db156&sid=2d7bfd344aa64d8ebc9beea0e4dad8ad&ts=1573897380&key=f1cd9351930d4e589922edbcf3b09a7c
MD5 value: 8fb4fbf99fcc1331c3274e708a403034
Step4: Set common of header
{"sid":"2d7bfd344aa64d8ebc9beea0e4dad8ad","comid":"2","compvtkey":"589625dce895454dbff9782c299db156","ts":"1573897380","sign":"8fb4fbf99fcc1331c3274e708a403034"}
3.1.3 Result
{
"code": 200,
"msg": "ok",
"reqId": "1573900361203",
"result": {
"list": [
{
"groupName": "",
"boxList": [
{
"machineCode": "V01001171116005027a279eb001",
"devModel": "V-BOX S-00",
"isAlarm": 0,
"boxName": "Treatment Systems",
"remark": "",
"state": "1",
"map": "78.178613,9.177124",
"boxId": "913"
},
…………
{
"machineCode": "Vir001171116005027a27201908",
"devModel": "V-BOX S-00",
"isAlarm": 0,
"boxName": "(Smart farm)",
"remark": "",
"state": "1",
"map": "88.637476,50.415074",
"boxId": "973"
}
]
},
……………………
{
"groupName": "(Manufacturing)",
"boxList": [
{
"machineCode": "Vir001171116005027a27201904",
"devModel": "V-BOX S-00",
"isAlarm": 0,
"boxName": "(Adjustment)",
"remark": "",
"state": "1",
"map": "109.316038,33.749868",
"boxId": "957"
},
………………
{
"machineCode": "Vir001171116005027a27201915",
"devModel": "V-BOX S-00",
"isAlarm": 0,
"boxName": "",
"remark": "",
"state": "1",
"map": "121.357068,24.312132",
"boxId": "975"
}
]
}
]
}
}
3.2 Real-time group list
3.2.1 Parameters
| acturl | we-data/realgroups | ||
| Functions | Get V-BOX’s tags group list | ||
| Parameters | Parameter | Description | |
| boxId | VBoxID ("None" means custom grouping) | ||
| Return value | Field name | Description | |
| list | Group list | ||
| groupId | Group ID | ||
| groupName | Group name | ||
3.2.2 Operating procedures
Step1: Set http: http://api.v-box.net/box-data/api/we-data/realgroups
Step2: Set parameters on Params
"boxId": "973"
Step3: Get sign
boxId=973&comid=2&compvtkey=589625dce895454dbff9782c299db156&sid=2d7bfd344aa64d8ebc9beea0e4dad8ad&ts=1573897380&key=f1cd9351930d4e589922edbcf3b09a7c
MD5 value: 9b267b7549083167954b7ede30916ff5
Step4: Set common of header
{"boxId":"973","sid":"2d7bfd344aa64d8ebc9beea0e4dad8ad","comid":"2","compvtkey":"589625dce895454dbff9782c299db156","ts":"1573897380","sign":"9b267b7549083167954b7ede30916ff5"}
3.2.3 Result
{
"code": 200,
"msg": "ok",
"reqId": "1573901906667",
"result": {
"list": [
{
"groupName": "Temperature",
"groupId": 7325
},
{
"groupName": "Humidity",
"groupId": 7326
},
{
"groupName": "Button switch",
"groupId": 7327
}
]
}
}
3.3 Real-time tags configuration list
3.3.1 Parameters
| acturl | we-data/realcfgs | ||
| Functions | Get the tags configuration information in the specified group in V-BOX. | ||
| Parameters | Parameter | Description | |
| boxId | VBoxID(“None” means custom tags grouping) | ||
| groupId | Group ID (Required) | ||
| pageSize | Number of each page, 10 by default | ||
| pageIndex | Number of current page, start from 1 | ||
| Return value | Field name | Description | |
| cfgList | monitorId | Tags ID | |
| monitorName | Tags name | ||
| updTime | Last update time | ||
| dataId | type of data 100: 16-bit binary 101: 16-digit octal Refer to Appendix 1 | ||
| addr | Address | ||
| addrType | 0: bit address 1: byte address 2: word address 3: double word | ||
| digitCount | Integer digits, decimal places | ||
| digitBinary | Data type and integer digits, decimal places | ||
| dataLimit | Data range | ||
| rid | Address | ||
| roleType | Permission: 1-read only, 2-write only, 3-read-write | ||
| totalPage | Total pages | ||
| totalRecord | Total record number | ||
| currentPage | Current page number | ||
3.3.2 Operating procedures
Step1: Set http: http://api.v-box.net/box-data/api/we-data/realcfgs
Step2: Set parameters on Params
"boxId":"973"
"groupId":"7325"
"pageSize":"5"
"pageIndex":"2"
Step3: Get sign
boxId=973&comid=2&compvtkey=589625dce895454dbff9782c299db156&groupId=7325&pageIndex=2&pageSize=5&sid=2d7bfd344aa64d8ebc9beea0e4dad8ad&ts=1573897380&key=f1cd9351930d4e589922edbcf3b09a7c
MD5 sign: 0769228e66c945eed5431c41a96949f2
Step4: Set common of header
{"boxId":"973","groupId":"7325","pageSize":"5","pageIndex":"2","sid":"2d7bfd344aa64d8ebc9beea0e4dad8ad","comid":"2","compvtkey":"589625dce895454dbff9782c299db156","ts":"1573897380","sign":"0769228e66c945eed5431c41a96949f2"}
3.3.3 Result
{
"code": 200,
"msg": "ok",
"reqId": "1573903822419",
"result": {
"cfgList": [
{
"monitorId": 91545,
"dataId": 105,
"monitorName": "Temp_9",
"updTime": 1571965761000,
"dataLimit": "0 7999",
"digitBinary": "十进制",
"addr": "9",
"rid": "D",
"roleType": 3,
"digitCount": "5,0",
"addrType": 2
},
……………
{
"monitorId": 91541,
"dataId": 105,
"monitorName": "Temp_5",
"updTime": 1571965761000,
"dataLimit": "0 7999",
"digitBinary": "十进制",
"addr": "5",
"rid": "D",
"roleType": 3,
"digitCount": "5,0",
"addrType": 2
}
],
"totalPage": 3,
"totalRecord": 15,
"currentPage": 2
}
}
3.4 Tags data list
3.4.1 Parameters
| acturl | we-data/realdata | ||
| Functions | Get the tags data in the specified group in V-BOX. | ||
| Parameters | Parameter | Description | |
| boxId | VBoxID(“None” means custom tag grouping) | ||
| groupId | Group ID (Required) | ||
| pageSize | Number of each page, 10 by default | ||
| pageIndex | Number of current page, start from 1 | ||
| Return value | Field name | Description | |
| List | Real-time data list | ||
| com | Communication port ID | ||
| monitorId | Tag ID | ||
| monitorName | Tag name | ||
| state | status | ||
| value | Value | ||
| groupId | Group ID | ||
| totalPage | Total pages | ||
| totalRecord | Total record | ||
| currentPage | current page | ||
3.4.2 Operating procedures
Step1: Set http: http://api.v-box.net/box-data/api/we-data/realdata
Step2: Set parameters on Params
"boxId":"973"
"groupId":"7325"
"pageSize":"5"
"pageIndex":"2"
Step3: Get sign
boxId=973&comid=2&compvtkey=589625dce895454dbff9782c299db156&groupId=7325&pageIndex=2&pageSize=5&sid=2d7bfd344aa64d8ebc9beea0e4dad8ad&ts=1573897380&key=f1cd9351930d4e589922edbcf3b09a7c
MD5 sign: 0769228e66c945eed5431c41a96949f2
{"boxId":"973","groupId":"7325","pageSize":"5","pageIndex":"2","sid":"2d7bfd344aa64d8ebc9beea0e4dad8ad","comid":"2","compvtkey":"589625dce895454dbff9782c299db156","ts":"1573897380","sign":"0769228e66c945eed5431c41a96949f2"}
3.4.3 Result
{
"code": 200,
"msg": "ok",
"reqId": "1573905679365",
"result": {
"totalPage": 3,
"list": [
{
"com": 2939,
"monitorId": 91545,
"monitorName": "Temp_9",
"groupId": 0,
"state": "1",
"value": "90"
},
…………
},
{
"com": 2939,
"monitorId": 91541,
"monitorName": "Temp_5",
"groupId": 0,
"state": "1",
"value": "87"
}
],
"totalRecord": 15,
"currentPage": 2
}
}
3.5 Modify tag data
3.5.1 Parameters
| acturl | we-data/updrealdata | |
| Functions | Modify tag data | |
| Parameters | Parameter | Description |
| monitorId | Tag ID | |
| value | value | |
| Return value | None | |
3.5.2 Operating procedures
Step1: Set http: http://api.v-box.net/box-data/api/we-data/updrealdata
Step2: Set parameters on Params
"monitorId":"91541"
"value":"60"
Step3: Get sign
comid=2&compvtkey=589625dce895454dbff9782c299db156&monitorId=91541&sid=2d7bfd344aa64d8ebc9beea0e4dad8ad&ts=1573897380&value=60&key=f1cd9351930d4e589922edbcf3b09a7c
MD5 sign: 4119b1abc9176a187f781bece04a5296
Step4: Set common of header
{"monitorId":"91541","value":"60","sid":"2d7bfd344aa64d8ebc9beea0e4dad8ad","comid":"2","compvtkey":"589625dce895454dbff9782c299db156","ts":"1573897380","sign":"4119b1abc9176a187f781bece04a5296"}
3.5.3 Result
{
"code": 200,
"msg": "ok",
"reqId": "1573907138803",
"result": {}
}
3.6 Historical tags name list
3.6.1 Parameters
| acturl | we-data/monitors | ||
| Functions | Get a list of historical tags | ||
| Parameters | Parameter | Description | |
| boxId | VBoxID (Not required) | ||
| Return value | Field name | Description | |
| list | Tag list | ||
| monitorId | tag ID | ||
| monitorName | tag name | ||
3.6.2 Operating procedures
Step1: Set http: http://api.v-box.net/box-data/api/we-data/monitors
Step2: Set parameters on Params
"boxId":"973"
Step3: Get sign
boxId=973&comid=2&compvtkey=589625dce895454dbff9782c299db156&sid=2d7bfd344aa64d8ebc9beea0e4dad8ad&ts=1573897380&key=f1cd9351930d4e589922edbcf3b09a7c
MD5 sign: 9b267b7549083167954b7ede30916ff5
Step4: Set common of header
{"boxId":"973","sid":"2d7bfd344aa64d8ebc9beea0e4dad8ad","comid":"2","compvtkey":"589625dce895454dbff9782c299db156","ts":"1573897380","sign":"9b267b7549083167954b7ede30916ff5"}
3.6.3 Result
{
"code": 200,
"msg": "ok",
"reqId": "1573907813693",
"result": {
"list": [
{
"monitorId": 91576,
"monitorName": "Hum",
"groupId": 7328
},
{
"monitorId": 91577,
"monitorName": "Temp",
"groupId": 7328
}
]
}
}
3.7 Historical tag data list
3.7.1 Parameters
| acturl | we-data/historydata | ||
| Functions | Get historical data | ||
| Parameters | Parameter | Description | |
| monitorId | tag ID, (Required) | ||
| monitorBeginTime | Monitoring start time, (Not required) | ||
| monitorEndTime | Monitoring end time, (Not required) | ||
| pageSize | Number of each page, 10 by default | ||
| pageIndex | Number of current page, start from 1 | ||
| Return value | Field name | Description | |
| list | Historical data list | ||
| monitorName | tag name | ||
| monitorTime | Monitoring time | ||
| value | Value | ||
| totalPage | Total pages | ||
| totalRecord | Total records | ||
| currentPage | Current page | ||
3.7.2 Operating procedures
Step: Set http: http://api.v-box.net/box-data/api/we-data/historydata
Step2: Set parameters on Params
"monitorId": 91577
"monitorBeginTime":"2019-11-16 10:45:44.000"
"monitorEndTime":"2019-11-16 20:45:44.000"
"pageSize":"10"
"pageIndex":"2"
Step3: Get sign
comid=2&compvtkey=589625dce895454dbff9782c299db156&monitorBeginTime=2019-11-16 10:45:44.000&monitorEndTime=2019-11-16 20:45:44.000&monitorId=91577&pageIndex=2&pageSize=10&sid=2d7bfd344aa64d8ebc9beea0e4dad8ad&ts=1573897380&key=f1cd9351930d4e589922edbcf3b09a7c
MD5 sign: feeae8ddb4014951cfc2c02de4744bc4
Step4: Set common of header
{"monitorId":"91577","monitorBeginTime":"2019-11-16 10:45:44.000","monitorEndTime":"2019-11-16 20:45:44.000","pageSize":"10","pageIndex":"2","sid":"2d7bfd344aa64d8ebc9beea0e4dad8ad","comid":"2","compvtkey":"589625dce895454dbff9782c299db156","ts":"1573897380","sign":"feeae8ddb4014951cfc2c02de4744bc4"}
3.7.3 Result
{
"code": 200,
"msg": "ok",
"reqId": "1573909705772",
"result": {
"totalPage": 12,
"list": [
{
"monitorTime": 1573905337000,
"groupName": "His",
"monitorTime_show": "2019-11-16 19:55:37.000",
"monitorName": "Temp",
"groupId": 7328,
"value": "914"
},
……………
{
"monitorTime": 1573902637000,
"groupName": "His",
"monitorTime_show": "2019-11-16 19:10:37.000",
"monitorName": "Temp",
"groupId": 7328,
"value": "422"
}
],
"totalRecord": 120,
"currentPage": 2
}
}
3.8 Alarm tags data list
3.8.1 Parameters
| acturl | we-data/alarmdata | ||
| Function | Get alarm data | ||
| Parameters | Parameter | Description | |
| boxId | VBoxID, (Required) | ||
| monitorBeginTime | Monitoring start time, (Not required) | ||
| monitorEndTime | Monitoring end time, (Not required) | ||
| pageSize | Number of each page, 10 by default | ||
| pageIndex | Number of current page, start from 1 | ||
| state | Status 1-unconfirmed, 2-confirm | ||
| alarmType | Alarm events: 1-trigger alarm, 0-disarm (Not necessary) | ||
| alarmLevel | Alarm level: 1 general alarm, 2 serious alarm, 3 particularly serious alarm (Not necessary) | ||
| Return value | Field name | Description | |
| List | Alarm data list | ||
| monitorId | tag ID | ||
| monitorName | tag name | ||
| state | status | ||
| value | Value | ||
| monitorTime | Monitoring time | ||
| alarmType | Alarm event | ||
| alarmLevel | Alarm level | ||
| totalPage | Total pages | ||
| totalRecord | Total records | ||
| currentPage | Current page | ||
3.8.2 Operating procedures
Step1: Set http: http://api.v-box.net/box-data/api/we-data/alarmdata
Step2: Set parameters on Params
"monitorId":"91931"
"monitorBeginTime":"2019-11-16 20:30:44.000"
"monitorEndTime":"2019-11-16 21:30:44.000"
"pageSize":"10"
"pageIndex":"1"
"state":"2"
Step3: Get sign
comid=2&compvtkey=589625dce895454dbff9782c299db156&monitorBeginTime=2019-11-16 20:30:44.000&monitorEndTime=2019-11-16 21:30:44.000&monitorId=91931&pageIndex=1&pageSize=10&sid=2d7bfd344aa64d8ebc9beea0e4dad8ad&state=2&ts=1573897380&key=f1cd9351930d4e589922edbcf3b09a7c
MD5 sign: 4056006bbc71bd80a3c632987626e15b
Step4: Set common of header
{"monitorId":"91931","monitorBeginTime":"2019-11-16 20:30:44.000","monitorEndTime":"2019-11-16 21:30:44.000","pageSize":"10","pageIndex":"1","state":"2","sid":"2d7bfd344aa64d8ebc9beea0e4dad8ad","comid":"2","compvtkey":"589625dce895454dbff9782c299db156","ts":"1573897380","sign":"4056006bbc71bd80a3c632987626e15b"}
3.8.3 Result
{
"code": 200,
"msg": "ok",
"reqId": "1573911745258",
"result": {
"totalPage": 1,
"list": [
{
"monitorTime": 1573910934000,
"alarmType": 0,
"monitorId": 4437,
"monitorTime_show": "2019-11-16 21:28:54",
"monitorName": "Temperature alarm",
"alarmLevel": 2,
"state": 2,
"text": "The temperature is too high",
"value": "1",
"alarm_role": 0
},
…………
{
"monitorTime": 1573910855000,
"alarmType": 1,
"monitorId": 4437,
"monitorTime_show": "2019-11-16 21:27:35",
"monitorName": "Temperature alarm",
"alarmLevel": 2,
"state": 2,
"text": "The temperature is too high",
"value": "18",
"alarm_role": 0
}
],
"totalRecord": 6,
"currentPage": 1
}
}
3.9 Get device state
3.9.1 Parameters
| acturl | we-data/getDeviceState | ||
| Function | Get vbox state based on machine code | ||
| Parameters | Parameter | Description | |
| machineCode | machineCode(required) | ||
| Return value | Field name | Description | |
| state | vbox state: 1-online, 0-offline | ||
3.10 Send switch to device
3.10.1 Parameters
| acturl | we-data/sendSwitchToDevice | ||
| Function | Enable vbox reports real-time data, because now the vbox has added a real-time data switch function, only in the real-time data page vbox will report real-time data, otherwise it will not be reported. So if you need to keep to get real-time data, you need to call this interface first, and call it every 20 seconds, so that the vbox will continue to report real-time data. | ||
| Parameters | Parameter | Description | |
| boxId | boxId(required) | ||
| Return value | Field name | Description | |
4 Appendix
4.1 Data type
100: 16-bit binary
101: 16-bit octal
102: 16-bit hexadecimal
103: 16-bit BCD code
104: 16-bit signed decimal
105: 16-bit unsigned decimal
200: 32-bit binary
201: 32-bit octal
202: 32-bit hexadecimal
203: 32-bit BCD
204: 32-bit signed decimal
205: 32-bit unsigned decimal
206: 32-bit floating
400: 64-bit binary
401: 64-bit octal
402: 64-bit hexadecimal
403: 64-bit BCD
404: 64-bit signed decimal
405: 64-bit unsigned decimal
406: 64-bit floating
1000: string
Version: V1.1.0
Date: Nov 2019