07 HTTP API

Version 18.1 by Mora Zhou on 2023/12/22 10:06

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:

http://api.v-box.net

Asean:

http://api.asean.v-box.net

Europe:

http://api.eu.v-box.net

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

✎Note: If it is for Virtual Deployment, the comid and comkey would not be the same with values above. Try to get the actual value from HTTP access (V-NET--Services--HTTP access)

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"}

Status Code

Example key and value

1).comid=2

2).comkey=589625dce895454dbff9782c299db156

3).screctkey=f1cd9351930d4e589922edbcf3b09a7c

4).ts=1573897380

Basic API

Login operation

2.1.1 Parameters

Acturl	we-data/login
Function	Login with username, email, phone number
Parameters	Items	Description
	alias	Must be username, registered email will fail to login
	password	32bit password (MD5 encryption)
	domain(Optional)	3rd party interface domain(Only available for Virtual Deployment)
Return value	Items	Description
	utype	User Type: 1-Manage Account, 2-Viewer Account
	sid	User session ID (Only available for 12 hours)

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(The md5 encryption result of Wecon159)

Step3: Get sign

alias=weconuser&comid=2&compvtkey=589625dce895454dbff9782c299db156&password=599a3c736c04e196c58a29f43778f7ea&ts=1573897380&key=f1cd9351930d4e589922edbcf3b09a7c

Put the whole string above encrypted by MD5, so will get the value of "sign"

"sign":"997513ff1320862f0cbb9ce19d0bd253"

✎Note: For Virtual Deployment, the sign string should be append with domain, so the format would be like following:

alias=xxx&comid=xxx&compvtkey=xxx&domain=xxx&password=xxx&ts=1657682972386&key=f1cd9351930d4e589922edbcf3b09a7c

The timestamp must be unit as Millisecond level

Step4: Set common of header

{"comid":"2","compvtkey":"589625dce895454dbff9782c299db156","ts":"1573897380","sign":"997513ff1320862f0cbb9ce19d0bd253"}

Result

{

"code": 200,

"msg": "ok",

"reqId": "1573899119000",

"result": {

"utype": 1,

"ztRole": 1,

"sid": "2d7bfd344aa64d8ebc9beea0e4dad8ad"

}

Service data APIs

V-Box list

Parameters

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"}

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"

}

]

}

]

}

Real-time group list

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

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"}

Result

{

"code": 200,

"msg": "ok",

"reqId": "1573901906667",

"result": {

"list": [

{

"groupName": "Temperature",

"groupId": 7325

{

"groupName": "Humidity",

"groupId": 7326

{

"groupName": "Button switch",

"groupId": 7327

}

]

}

V-BOX HTTP manual_html_2445c358293d621.png

Real-time tags configuration list

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

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"}

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

}

Tags data list

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

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

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

}

Modify tag data

Parameters

acturl	we-data/updrealdata
Functions	Modify tag data
Parameters	Parameter	Description
	monitorId	Tag ID
	value	value
Return value	None

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"}

Result

{

"code": 200,

"msg": "ok",

"reqId": "1573907138803",

"result": {}

}

Historical tags name list

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

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"}

Result

{

"code": 200,

"msg": "ok",

"reqId": "1573907813693",

"result": {

"list": [

{

"monitorId": 91576,

"monitorName": "Hum",

"groupId": 7328

{

"monitorId": 91577,

"monitorName": "Temp",

"groupId": 7328

}

]

}

Historical tag data list

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

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"}

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

}

Alarm tags data list

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

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"}

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

}

Get device state

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

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

Appendix

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

07 HTTP API

General

Interface Parameter Description

Example key and value

Basic API

Login operation

Service data APIs

V-Box list

Real-time group list

Real-time tags configuration list

Tags data list

Modify tag data

Historical tags name list

Historical tag data list

Alarm tags data list

Get device state

Send switch to device

Appendix

Data type

Navigation

Table of Contents