Segway API-E-moped

Welcome to the Segway API of Gateway. This API reference provides information on available endpoints and how to interact with them. Using the Segway API of Gateway, you can integrate vehicle data and control into your applications.
The API uses JSON formatted requests and responses.

Note1: please request the relevant domian according to the first letter of your platformcode

platformCode	region	domain
A*****	apac	https://apac-api.segwaydiscovery.com
E*****	europe	https://eu-api.segwaydiscovery.com
U*****	americas	https://us-api.segwaydiscovery.com
C*****	china	https://cn-api.segwaydiscovery.com

Auth

request token common for all models

The access_token is the globally unique credential for calling APIs, and needs to be updatad periodically. The validity period of access_token is expressed in the returned expires_in, and its available value is within 86400 seconds. Your server needs to updata access_token in advance based on this validity period. During the updata, it may continue to output old access_token values. In this case, the SEGWAY backend will ensure that both new and old access_token values are available within 300 seconds(expires_in≤300), so that third-party services are smoothly transitioned.

POST

/oauth/token

curl -X POST \
https://api_domain:port/oauth/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=A20081' \
--data-urlencode 'client_secret=e2651be5-12d3-48f3-ba6c-bc2b04a447b6' \
--data-urlencode 'grant_type=client_credentials'

Header

field	type	description
Content-Type	String	allowed: "application/x-www-form-urlencoded"

Parameter

field	type	description
client_id	String	get from business system
client_secret	String	get from business system
grant_type	String	allowed: "client_credentials"

Success

field	type	description
access_token	String	token
token_type	String	allowed values: "bearer"
expires_in	Int	expiration duration seconds.
scope	String	scope.

HTTP/1.1 200 OK
{
    "access_token": "83efe135-8203-404c-b489-b5fbf8050d3d",
    "token_type": "bearer",
    "expires_in": 43199,
    "scope": "read write trust"
}

False

1.0 HTTP/1.1 401 Unauthorized
{ 
    "error": "invalid_client",
    "error_description": "Bad client credentials"
}

Query

get current status common for all models

This API is used to obtain the realtime status information.

GET

/api/v2/vehicle/query/current/status

curl -X GET \
https://api_domain:port/api/v2/vehicle/query/current/status?iotCode=861477038719116 \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415'

Header

field	type	description
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	IoT IMEI

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

attached:'data'

field	type	description
iotCode	String	IoT IMEI
online	Boolean	true→ connected to SEGWAY Cloud. false→ disconnected
locked	Boolean	true→ lock. false→ unlock
lockVoltage	Number	lock voltage, unit/mV
networkSignal	Number	network signal. range: 2-32. 2 shows the signal is weakest, 32 shows the signal is strongest.
charging	Boolean	true→charging. false→ no charging
powerPercent	Number	battery percentage, 80->80%.
speedMode	Number	speed mode (1: low speed; 2: medium speed; 3: high speed
speed	Number	current speed
odometer	Number	total odometer (unit is 1m, so 1230 means 1.23km)
remainingRange	Number	remaining range (unit is 10m, so 1230 means 12.3km)
totalRidingSecs	Number	total riding seconds.
statusUtcTime	Number	timestamp

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": {
        "iotCode": "{iotCode}",
        "online": true,
        "locked": true,
        "lockVoltage": 342,
        "networkSignal": 22,
        "charging": true,
        "powerPercent": 10,
        "speedMode": 1,
        "speed": 20,
        "odometer": 9000,
        "remainderRange": 3000,
        "totalRidingSecs": 110,
        "statusUtcTime": 1591067719
    },
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

get current extra-status only for E-moped

This API is used to obtain the realtime Mopeds information.

GET

/api/v2/mopeds/query/current/extra-status

curl -X GET \
https://api_domain:port/api/v2/mopeds/query/current/extra-status?iotCode=861477038719116 \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415'

Header

field	type	description
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	IoT IMEI

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

attached:'data'

field	type	description
iotCode	String	IoT IMEI
seatCaskHelmet	Number	helmet count in seat cask： 0-2
tailboxHelmet	Number	helmet count in tailbox： 0-2
peopleSat	Number	0→no, 1→ yes
cruiseStatus	Number	0:Unlock 1:lock
saddleStatus	Number	0:Unlock 1:lock
tailboxStatus	Number	0:Unlock 1:lock
handlebarStatus	Number	0:unlock 1:lock
kickstand	Number	0:close 1:open

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": {
        "iotCode": "862869030338078",
        "seatCaskHelmet": 2,
        "tailboxHelmet": 0,
        "peopleSat": 0,
        "cruiseStatus": 0,
        "saddleStatus": 0,
        "tailboxStatus": 1,
        "handlebarStatus": 0,
        "kickstand": 0
    },
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

get current location common for all models

This API is used to obtain the location information.

GET

/api/v2/vehicle/query/current/location

curl -X GET \
https://api_domain:port/api/v2/vehicle/query/current/location?iotCode=861477038719116 \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415'

Header

field	type	description
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	IoT IMEI
realTimeLocation(optional)	Boolean	true-> will get real time location information

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

attached:'data'

field	type	description
iotCode	String	IoT IMEI
latitude	Double	latitude (WGS84).
longitude	Double	longitude (WGS84).
satelliteNumber	Number	gps satellite Number.
hdop	Number	gps hdop, more lower is the value, the higher is the accuracy.
altitude	Number	altitude (height from sea level), Unit Meter
gpsUtcTime	Number	timestamp

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "success",
    "data": {
        "iotCode": "{iotCode}",
        "latitude": 22.634228,
        "longitude": 114.125962,
        "satelliteNumber": 6,
        "hdop": 1.38,
        "altitude": 10.1,
        "gpsUtcTime": "1591067719"
    },
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15400	latest location not found via device

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

get battery Info common for Moped(Ebike C80,E-moped)

This API is used to get the Mopeds battery information.

GET

/api/v2/mopeds/query/current/battery-info

curl -X GET \
https://api_domain:port/api/v2/mopeds/query/current/battery-info?iotCode=861477038719116 \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415'

Header

field	type	description
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	IoT IMEI

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

attached:'data'

field	type	description
iotCode	String	IoT IMEI
charging	Boolean	true→charging. false→ no charging
vehiclePercent	Number	battery percent, unit:80->80%
batteryCount	Number	count: 1～3
drivingVoltage	Number	unit: 80->80V
currentPower	Number	current power of vehicle, unit: W
iotPercent	Number	iot battery percent, unit:80->80%
iotVoltage	Number	current voltage of IoT: 411->4.11V
batteryData	list	Object list: 'battery data'

attached：'battery data'

field	type	description
batteryPort	Number	allowed: 1,2,3
batteryPercent	Number	batterypercent, unit/80->80%
batteryVoltage	Number	battery voltage,40->40V
cycleTimes	Number	cycleTimes
temperatrue	Number	temperatrue1, unit/℃

HTTP/1.1 200 OK
{
	"code": 0,
	"msg": "success",
	"data": {
		"iotCode": "{iotCode}",
		"charging": true,
		"vehiclePercent": 80,
		"batteryCount": 2,
		"drivingVoltage": 80,
		"currentPower": 260,
		"iotPercent": 100,
		"iotVoltage": 412,
		"batteryData": [{
				"batteryPort": 1,
                "batteryPercent": 52,
                "batteryVoltage": 48,
				"cycleTimes": 23,
				"temperatrue": 25
			},
			{
				"batteryPort": 2,
                "batteryPercent": 20,
                "batteryVoltage": 48,
				"cycleTimes": 40,
				"temperatrue": 25
			}
		]
	},
	"t": 1593333694412,
	"resId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "resId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

get bluetooth key common for all models

This API is used to get IoT's bluetooth key

GET

/api/v2/vehicle/query/current/bluetooth-key

curl -X GET \
https://api_domain:port/api/v2/vehicle/query/current/bluetooth-key?iotCode=861477038719116 \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415'

Header

field	type	description
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	IoT IMEI

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

attached:'data'

field	type	description
iotCode	String	IoT IMEI
key	String	8 digit letters and Numbers. eg:'abcd1234'

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "success",
    "data": {
        "iotCode": "{iotCode}",
        "key": "abcd1234"
    },
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15400	latest location not found via device

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

Control

startRental only for E-moped

This uses of this API are-start a rental and design a group-command to replace multiple interactions between the client server and SEGWAY backend. In this way, the Mopeds ECU will assess whether the conditions are met to start a rental order.
Notes: Please use rental setting to configure the parameter that are used as the critical condition for starting the Rental order.

POST

/api/v2/mopeds/control/startRental

curl -X POST \
https://api_domain:port/api/v2/mopeds/control/startRental \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
    "iotCode" : "861477038719116" 
}'

Header

field	type	description
Content-Type	String	allowed: "application/json"
Authorization	String	allowed: "bearer token"

Parameter

field	type	description
iotCode	String	IoT IMEI

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": null,
    "t": 1593331167570,
    "opId": "d5aa020d-77ae-439c-892c-a781c71eb836"

}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15500	device upgrading: command can not be executed
10	15620	startRental failed
11	15621	startRental failed: network error
12	15622	startRental failed：handlebar failed
13	15623	startRental success, but saddle failed
14	15624	startRental success, but tailbox failed
15	15625	startRental success, but tailbox and saddle failed

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

endRental only for E-moped

This uses of this API are-end a rental and design a group-command to replace multiple interactions between the client server and SEGWAY backend. In this way, the Mopeds ECU will assess whether the conditions are met to end a rental order.
Notes: Please use rental setting to configure the parameter that are used as the critical condition for ending the Rental order.

POST

/api/v2/mopeds/control/endRental

curl -X POST \
https://api_domain:port/api/v2/mopeds/control/endRental \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
    "iotCode" : "861477038719116"
}'

Header

field	type	description
Content-Type	String	allowed: "application/json"
Authorization	String	allowed: "bearer token"

Parameter

field	type	description
iotCode	String	IoT IMEI

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": null,
    "t": 1593333983900,
    "opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15500	device upgrading: command can not be executed
10	15627	endRental failed: vehicle is riding
11	15628	endRental failed
12	15629	endRental: network error
13	15630	endRental failed: handlebar lock failed
14	15631	endRental failed: no return helmet
15	15632	endRental failed: saddle lock failed
16	15633	endRental failed: tailbox lock failed
17	15634	endRental failed: tailbox and saddle lock failed

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

unlock common for all models

This API is used to unlock the Mopeds.

POST

/api/v2/vehicle/control/unlock

curl -X POST \
https://api_domain:port/api/v2/vehicle/control/unlock \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
    "iotCode" : "861477038719116"
}'

Header

field	type	description
Content-Type	String	allowed: "application/json"
Authorization	String	allowed: "bearer token"

Parameter

field	type	description
iotCode	String	IoT IMEI

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": null,
    "t": 1593331167570,
    "opId": "d5aa020d-77ae-439c-892c-a781c71eb836"

}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15500	device upgrading: command can not be executed
10	15611	device unlock command failed
11	15612	device unlock failed: network error
12	15613	handlebar unlock failed
13	15990	API call is restricted, please contact Segway related personnel

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

lock common for all models

This API is used to lock the Mopeds.

POST

/api/v2/vehicle/control/lock

curl -X POST \
https://api_domain:port/api/v2/vehicle/control/lock \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
    "iotCode" : "861477038719116"
}'

Header

field	type	description
Content-Type	String	allowed: "application/json"
Authorization	String	allowed: "bearer token"

Parameter

field	type	description
iotCode	String	IoT IMEI

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": null,
    "t": 1593333983900,
    "opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15500	device upgrading: command can not be executed
10	15600	lock failed: vehicle is riding
11	15601	device lock command failed
12	15602	device lock failed: network error
13	15603	handlebar lock failed
14	15996	device lock failed: denied by geofence strategy
15	15997	device lock failed: unable to lock while riding
16	15990	API call is restricted, please contact Segway related personnel

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

throttle response common for all models

This API is used to turn the vehicle's throttle response on/off.

POST

/api/v2/vehicle/control/throttle-response

curl -X POST \
https://api_domain:port/api/v2/vehicle/control/throttle-response \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
    "iotCode" : "861477038719116",
    "controlType" : 1
}'

Header

field	type	description
Content-Type	String	allowed: "application/json"
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	IoT IMEI
controlType	Number	0→ turn off. 1→ turn on

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": null,
    "t": 1593333983900,
    "opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15500	device upgrading: command can not be executed

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

saddle only for E-moped

This API is used to open the saddle components while in unlocking.

POST

/api/v2/mopeds/control/saddle

curl -X POST \
https://api_domain:port/api/v2/mopeds/control/saddle \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
    "iotCode" : "861477038719116"
}'

Header

field	type	description
Content-Type	String	allowed: "application/json"
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	iot imei

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": null,
    "t": 1593333983900,
    "opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15500	device upgrading: command can not be executed
10	15635	open failed: please operate when mopeds is unlocking
11	15638	device execute failure

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

tailbox only for E-moped

This API is used to open the tailbox while in unlocking.

POST

/api/v2/mopeds/control/tailbox

curl -X POST \
https://api_domain:port/api/v2/mopeds/control/tailbox \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
    "iotCode" :  "861477038719116"
}'

Header

field	type	description
Content-Type	String	allowed: "application/json"
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	iot imei

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": null,
    "t": 1593333983900,
    "opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15500	device upgrading: command can not be executed
10	15635	open failed: please operate when mopeds is unlocking
11	15638	device execute failure

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

battery component common for （MaxPro,MaxPlus,E-moped)

This API is used to open the battery components while in unlocking.

POST

/api/v2/vehicle/control/battery-cover

curl -X POST \
https://api_domain:port/api/v2/vehicle/control/battery-cover  \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
    "iotCode" :  "861477038719116"
}'

Header

field	type	description
Content-Type	String	allowed: "application/json"
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	iot imei

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": null,
    "t": 1593333983900,
    "opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15500	device upgrading: command can not be executed
10	15635	open failed: please operate when mopeds is unlocking
11	15638	device execute failure

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

sound common for all models

This API is used to sound the vehicle.

POST

/api/v2/vehicle/control/sound

curl -X POST \
https://api_domain:port/api/v2/vehicle/control/sound \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
    "iotCode" : "861477038719116",
    "controlType" : 3
}'

Header

field	type	description
Content-Type	String	allowed: "application/json"
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	IoT IMEI
controlType	Number	1→sound1 2→sound2(toot) 3→sound3

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": null,
    "t": 1593333983900,
    "opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15500	device upgrading: command can not be executed

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

Setting

rental setting only for E-moped

This API is designed to configure the critical conditions that will be used at startRental and endRental. However, this action is not required at every startRental and endRental.

POST

/api/v2/mopeds/setting/rental

curl -X POST \
https://api_domain:port/api/v2/mopeds/setting/rental \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{

}'

Header

field	type	description
Content-Type	String	allowed: "application/json"
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	IoT IMEI
saddleSwitch(optional)	Number	used at startRental. 0→ no setting. 1→ open saddle. 2→ open saddle only there are helmets in seat cask. 3→ do not open saddle. eg. if set to 1, the saddle will be opened at startRental
tailboxSwitch(optional)	Number	used at startRental. 0→ no setting. 1→ open tailbox. 2→ open tailbox only there are helmets in tailbox. 3→ do not open tailbox.
helmetCheck(optional)	Number	used at endRental. 0→ no setting. 1→ open, check whether all helmets are returned. 2→ close, not check helmet. eg. if set to 2, the Mopeds ECU will not check whether all helmets are returned.
saddleCheck(optional)	Number	used at endRental. 0→ no setting. 1→open, check if saddle is locked at endRental. 2→ close, no check.
tailboxCheck(optional)	Number	used at endRental. 0→ no setting. 1→open, check if tailbox is locked at endRental. 2→ close, no check.

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": null,
    "t": 1593333983900,
    "opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15500	device upgrading: command can not be executed

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

switch setting only for E-moped

This API is used to turn on or off the switch.

POST

/api/v2/mopeds/setting/switch

curl -X POST \
https://api_domain:port/api/v2/mopeds/setting/switch \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{

}'

Header

field	type	description
Content-Type	String	allowed: "application/json"
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	IoT IMEI
bssDisplay(optional)	Number	displayed as bbs(British Standard speed) 0→ no setting 1→off. 2→on
alertCheck(optional)	Number	alertCheck at lock status 0→ no setting 1→off. 2→on
berLevel(optional)	Number	brake energy regeneration level 0→ no setting 1→ off. 2→low level . 3→ high level
alertSensitivity(optional)	Number	strength range: 1-3
lowPowerValue(optional)	Number	Mopeds will upload the prompt if the vehicle percent is less than lowPowerValue range: 10-30 default:10
displayTime(optional)	Number	display time on E-moped panel 0→ no setting 1→off. 2→on
displayODO(optional)	Number	ODO display setting on the panel 0→ no setting 1→off. 2→totalRange
lowSpeedLimit(optional)	Number	Size range: 6-42. unit：km/h
mediumSpeedLimit(optional)	Number	Size range: 6-42. unit：km/h
highSpeedLimit(optional)	Number	Size range: 6-42. unit：km/h

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": null,
    "t": 1593333983900,
    "opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15500	device upgrading: command can not be executed

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

switch enable

This API is used to enable or disable the switch of mopeds.

POST

/api/v2/mopeds/setting/able-switch

curl -X POST \
https://api_domain:port/api/v2/mopeds/setting/able-switch \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{

}'

Header

field	type	description
Content-Type	String	allowed: "application/json"
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	IoT IMEI
assistedMode(optional)	Number	Power-assisted manual push mode switch 0→ no setting 1→off. 2→on
crashWarning(optional)	Number	Crash warning switch 0→ no setting 1→off. 2→on
kickstandCheck(optional)	Number	0→ no setting 1→off. 2→on
cruiseSwitch(optional)	Number	0→ no setting 1→off. 2→on
speedModeSwitch(optional)	Number	0→ no setting 1→off. 2→on
handlebarSwitch(optional)	Number	0→ no setting 1→off. 2→on
lowPowerSwitch(optional)	Number	0→ no setting 1→off. 2→on
saddleCheck(optional)	Number	0→ no setting 1→off. 2→on

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": null,
    "t": 1593333983900,
    "opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15500	device upgrading: command can not be executed

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

light setting deprecated, please see to the endpoint of atmosphere lamp setting

This API is used to set relevant parameters of the Mopeds.

POST

/api/v2/mopeds/setting/light

curl -X POST \
https://api_domain:port/api/v2/mopeds/setting/light \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{

}'

Header

field	type	description
Content-Type	String	allowed: "application/json"
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	IoT IMEI
brightness	Number	Ambient light brightness 0 →no setting, range:1-3
faultIndicator	Number	Fault light indicator 0 →no setting, 1:Green 2:Red 3:Orange 4:Blue 5:Cyan 6:Violet 7:White
readyIndicator	Number	Ready to use indicator 0 →no setting, 1:Green 2:Red 3:Orange 4:Blue 5:Cyan 6:Violet 7:White
pushIndicator	Number	Push or cruise light indicator 0 →no setting, 1:Green 2:Red 3:Orange 4:Blue 5:Cyan 6:Violet 7:White
parkingIndicator	Number	Parking light indicator 0 →no setting, 1:Green 2:Red 3:Orange 4:Blue 5:Cyan 6:Violet 7:White
lockIndicator	Number	Lock light indicator 0 →no setting, 1:Green 2:Red 3:Orange 4:Blue 5:Cyan 6:Violet 7:White

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": null,
    "t": 1593333983900,
    "opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15500	device upgrading: command can not be executed

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

atmosphere lamp setting

This API is used to set relevant parameters of the vehicles.

POST

/api/v2/vehicle/setting/ambient

curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/ambient \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
    "iotCode":"8612345678901",
    "bright": 1,
    "readyMode": {
        "mode": 2,
        "color": 1
    },
    "parkingMode": {
        "mode": 2,
        "color": 3
    }
}'

Header

field	type	description
Content-Type	String	allowed: "application/json"
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	IoT IMEI
brightrequired	Number	Common atmosphere lamp brightness of each mode. 1:Low 2:Medium 3:High
parkingModerequired	Object	An object that indicates the atmosphere lamp effect
cruiseMode(optional)	Object	An object that indicates the atmosphere lamp effect
readyMode(optional)	Object	An object that indicates the atmosphere lamp effect
faultMode(optional)	Object	An object that indicates the atmosphere lamp effect

attached:'parkingMode,cruiseMode,readyMode,faultMode'

field	type	description
mode	Number	1:Off 2:Always on
color	Number	1:Green 2:Red 3:Orange 4:Blue 5:Cyan 6:Violet 7:White

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": null,
    "t": 1593333983900,
    "opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15500	device upgrading: command can not be executed

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

sound setting

This API is used to set relevant parameters of the vehicle.

POST

/api/v2/vehicle/setting/sound

curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/sound \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
    "iotCode": "861477038719116",
    "workMode":2,
    "volume":3
}'

Header

field	type	description
Content-Type	String	allowed: "application/json"
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	IoT IMEI
workMode	Number	used to set the device sound 0 →no setting, 1→off, 2→on
volume(optional)	Number	Volume (1-3）: 1 is the smallest and 3 is largest.
moeqMask(optional)	Object	An object to indicate whether it's on or off for each sound of the vehicle. Each element in the object indicates a certain sound.

attached:'moeqMask'

field	type	description
unlocked (optional)	Number	0:disable 1:enable 2:keep original
locked (optional)	Number	0:disable 1:enable 2:keep original
openBoxes (optional)	Number	0:disable 1:enable 2:keep original
kickstand (optional)	Number	0:disable 1:enable 2:keep original
helmet (optional)	Number	0:disable 1:enable 2:keep original
turning (optional)	Number	0:disable 1:enable 2:keep original
ready (optional)	Number	0:disable 1:enable 2:keep original
unReady (optional)	Number	0:disable 1:enable 2:keep original
gearUp (optional)	Number	0:disable 1:enable 2:keep original
gearDown (optional)	Number	0:disable 1:enable 2:keep original
enterCruise (optional)	Number	0:disable 1:enable 2:keep original
exitCruise (optional)	Number	0:disable 1:enable 2:keep original
setSuccess (optional)	Number	0:disable 1:enable 2:keep original
setFailed (optional)	Number	0:disable 1:enable 2:keep original
defenseOn (optional)	Number	0:disable 1:enable 2:keep original
error (optional)	Number	0:disable 1:enable 2:keep original
lowPower (optional)	Number	0:disable 1:enable 2:keep original
batteryInserted (optional)	Number	0:disable 1:enable 2:keep original

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": null,
    "t": 1593333983900,
    "opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15500	device upgrading: command can not be executed

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

speed mode common for (ES,Max,MaxPro,MaxPlus,E-moped)

This API is used to set speed mode.

POST

/api/v2/vehicle/setting/speed-mode

curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/speed-mode \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
    "iotCode": "861477038719116",
    "speedMode":1
}'

Header

field	type	description
Content-Type	String	allowed: "application/json"
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	IoT IMEI
speedMode	Number	1→ low speed. 2→ medium speed. 3→ high speed

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": null,
    "t": 1593333983900,
    "opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15500	device upgrading: command can not be executed

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

bluetooth key common for all models

This API is used to set IoT's bluetooth key

POST

/api/v2/vehicle/setting/bluetooth-key

curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/bluetooth-key \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
    "iotCode": "861477038719116",
    "key": "4BKNwi77"
}'

Header

field	type	description
Content-Type	String	allowed: "application/json"
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	IoT IMEI
key	String	8 digit letters and Numbers. eg 'abcd1234'

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": null,
    "t": 1593333983900,
    "opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15500	device upgrading: command can not be executed

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

upload interval

This API is used to set the upload interval of status and location

POST

/api/v2/vehicle/setting/interval

curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/interval \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
    
}'

Header

field	type	description
Content-Type	String	allowed: "application/json"
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	IoT IMEI
locationInterval	Object	request data
statusInterval	Object	request data

attached:'locationInterval'

field	type	description
unlockStatus	Number	interval range: 10-65535
lockStatus	Number	interval range: 10-65535

attached:'statusInterval'

field	type	description
ridingStatus	Number	interval range: 10-65535
nonRiding	Number	interval range: 10-65535
lockStatus	Number	interval range: 10-65535

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": null,
    "t": 1593333983900,
    "opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15500	device upgrading: command can not be executed
10	15707	NOT supported by this vehicle or its firmware

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

time adjust only for E-moped

This API is used to adjust the time on display.

POST

/api/v2/vehicle/setting/time-adjust

curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/time-adjust \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{

}'

Header

field	type	description
Content-Type	String	allowed: "application/json"
Authorization	String	allowed: "bearer access_token"

Parameter

field	type	description
iotCode	String	IoT IMEI
utcOffset	Number	UTC Offset in seconds, the offset from UTC (in seconds) for a specific location. This does not take into effect daylight savings. eg: 28800 for the zone of UTC/GMT+08:00 range: -43200 ~ 43200
dstOffset	Number	DST Offset in seconds, the offset for daylight-savings time in seconds. allowed value:: 0 and 3600

Success

field	type	description
code	Number	status code
msg	String	messages
data	Object	response data
t	Number	timestamp
opId	String	operation Id

HTTP/1.1 200 OK
{
    "code": 0,
    "msg": "Success",
    "data": null,
    "t": 1593333983900,
    "opId": "bf84e6aa-8787-4b2d-8461-e91aba35b07e"
}

False

sn	code	error
1	15101	token verification failed
2	15004	parameter error
3	15001	server error
4	15102	device not found
5	15300	inactive device
6	15301	offline device
7	15302	device response timeout
8	15303	command send failed
9	15500	device upgrading: command can not be executed

HTTP/1.1 200 OK
{
    "code": 15302,
    "msg": "device response timeout",
    "data": null,
    "t": 1593333694412,
    "opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}

Push

If your server has received any one of the following types of pushes and successfully processes it, please return an HTTP response code of 200. Otherwise, our server will retry in 5 seconds, this retry will only be done once.

signature generation algorithm
Note: All received parameters except signature are involved in the verification process.
Step 1: If the received data is a String, use “&” and “=” to split the String into several key-value pairs. If the received data is an array, dict, or similar data type, continue as usual and order the received key-value pairs sequentially by ASCII.
Step 2: Convert the sorted dict back into a String in “key1=value1&key2=value2” form.
Step 3: Append “&client_secret=” to the String created during step 2.
Step 4: Use MD5 to calculate the hash value (finally converted into 32-bit hexadecimal characters) of the String created during step 3. The newly calculated value is your digital signature.
Next, compare this value with your signature. If they are the same, the signature verification was successful. • When performing signature verification, do not enumerate the signature fields according to the port documentation list.
All received parameters except signature are involved in the verification process. When performing signature verification, do not enumerate the signature fields according to the port documentation list. This will cause use many problems if new fields are created.

vehicle alert common for all models

This API should be exposed by your application system to receive the vehicle’s alerts.

POST

/v2/vehicle/alert

curl -X POST \
https://business:port/v2/vehicle/alert\
-header 'Content-Type: application/x-www-form-urlencoded' \
-data 'iotCode={iotCode}&platformCode={platformCode}&statusUtcTime={tinmstamp}&code={code}'

Header

field	type	description
Content-Type	String	allowed: "application/x-www-form-urlencoded"

Parameter

field	type	description
iotCode	String	IoT IMEI
platformCode	String	client_id
statusUtcTime	Number	timestamp
alertStatus	Number	0→ appearing. 1->disappeared
code	Number	available appearing alert code: 1->illegal moving. 2->vehicle fell down when locked. 3 ->illegal dismantling. 4->vehicle fell down when unlocked. 10->battery1 token out. 11->battery2 token out. 12->low power available disappeared alert code: 1->illegal moving. 2->vehicle fell down. 3 ->illegal dismantling. 10->battery1 token out. 11->battery2 token out. 12->low power
signature	String	more info

response

field	type	description
message(optional)	String	-
code	Number	allowed: 0

HTTP/1.1 200 OK
{        
        “message”:success，
        “code”: 0
}

vehicle fault common for all models

This API should be exposed by your application system to receive the vehicle’s fault codes

POST

/v2/vehicle/fault

curl -X POST \
https://business:port/v2/vehicle/fault \
-header 'Content-Type: application/x-www-form-urlencoded' \
-data 'iotCode={iotCode}&platformCode={platformCode}&statusUtcTime={tinmstamp}&faultStatus={disappered}&code={code}'

Header

field	type	description
Content-Type	String	allowed: "application/x-www-form-urlencoded"

Parameter

field	type	description
iotCode	String	IoT IMEI
platformCode	String	client_id
statusUtcTime	Number	timestamp
faultStatus	Number	0→ appearing. 1->disappeared
code	Number	fault code
signature	String	more info

response

field	type	description
message(optional)	String	-
code	Number	allowed: 0

HTTP/1.1 200 OK
{        
        “message”:success，
        “code”: 0
}

vehicle location common for all models

This API should be exposed by your application system to receive the vehicle's location. When the Mopeds is unlocked, its location will be pushed once every 10 seconds. When the Mopeds is locked, its location will be pushed every 900 seconds.

POST

/v2/vehicle/location

curl -X POST \
https://business:port/v2/vehicle/location \
-header 'Content-Type: application/x-www-form-urlencoded' \
-data 'iotCode={iotCode}&platformCode={platformCode}&locationStatus={valid}&latitude={latitude}&longitude={longitude}&satelliteNumber={satelliteNumber}&hdop={hdop}&altitude={altitude}&gpsUtcTime={gpsUtcTime}'

Header

field	type	description
Content-Type	String	allowed: "application/x-www-form-urlencoded"

Parameter

field	type	description
iotCode	String	IoT IMEI
platformCode	String	client_id
locationStatus	String	allowed: 'invalid' and 'valid'
latitude	Double	latitude (WGS84).
longitude	Double	longitude (WGS84).
satelliteNumber	Number	longitude (WGS84).
hdop	Number	gps hdop, more lower is the value, the higher is the accuracy.
altitude	Number	altitude (height from sea level), Unit Meter
gpsUtcTime	Number	timestamp
signature	String	more info

response

field	type	description
message(optional)	String	-
code	Number	allowed: 0

HTTP/1.1 200 OK
{        
        “message”:success，
        “code”: 0
}

vehicle status common for all models

This API should be exposed by your application system to receive the changes of the Mopeds status. When the Mopeds is riding, its status will be pushed once every 10 seconds.

POST

/v2/vehicle/status

curl -X POST \
https://business:port/v2/vehicle/status \
-header 'Content-Type: application/x-www-form-urlencoded' \
-data 'iotCode={iotCode}&platformCode={platformCode}&signature={signature}&online={online}&locked={locked} \
&lockVoltage={lockVoltage}&networkSignal={networkSignal}&charging={charging}&powerPercent={powerPercent}&speedMode={speedMode} \
&speed={speed}&odometer={odometer}&remainderRange={remainderRange}&totalRidingSecs={totalRidingSecs} \
&statusUtcTime={statusUtcTime}'

Header

field	type	description
Content-Type	String	allowed: "application/x-www-form-urlencoded"

Parameter

field	type	description
iotCode	String	IoT IMEI
platformCode	String	client_id
online	Boolean	true→ connected to SEGWAY Cloud. false→ disconnected
locked	Boolean	true→ lock. false->unlock
lockVoltage	Number	lock voltage, 412->4.12V
networkSignal	Number	network signal. range: 2-32. 2 shows the signal is weakest, 32 shows the signal is strongest.
charging	Boolean	true→charging. false→ no charging
powerPercent	Number	battery percentage, 80->80%.
speedMode	Number	speed mode (0: unification status; 1: low speed; 2: medium speed; 3: high speed;)
speed	Number	Mopeds current speed.
odometer	Number	total odometer (unit is 1m, so 1230 means 1.23km
remainingRange	Number	remaining range (unit is 10m, so 1230 means 12.3km
totalRidingSecs	Number	total riding seconds.
statusUtcTime	Number	get Mopeds status info's UTC time.
signature	String	more info

response

field	type	description
message(optional)	String	-
code	Number	allowed: 0

HTTP/1.1 200 OK
{        
        “message”:success，
        “code”: 0
}

components lock

This API should be exposed by your application system to receive the components status.

POST

/v2/vehicle/components

https://business:port/v2/vehicle/components \
-header 'Content-Type: application/x-www-form-urlencoded' \
-data 'iotCode={iotCode}&platformCode={platformCode}&statusUtcTime={tinmstamp}&status={0}'

Header

field	type	description
Content-Type	String	allowed: "application/x-www-form-urlencoded"

Parameter

field	type	description
iotCode	String	IoT IMEI
platformCode	String	client_id
type	Number	type: 1→saddle 2→tailbox 4→helmet check in tailbox(unlock->helmet token in, lock->token out) .
status	Number	operation status: 1→ unlock(not applicable for saddle or tailbox). 2→ lock.
statusUtcTime	Number	timestamp
signature	String	more info

response

field	type	description
message(optional)	String	-
code	Number	allowed: 0

HTTP/1.1 200 OK
{        
        “message”:success，
        “code”: 0
}

Appendix 1：Status code description

sn	code	error
1	15101	token verification failed
2	15100	incorrect platform info
3	15004	parameter error
4	15001	server error
5	15102	device not found
6	15300	inactive device
7	15301	offline device
8	15302	device response timeout
9	15303	command send failed
10	15400	latest location not found via device
11	15500	device upgrading: command can not be executed
12	15600	lock failed: vehicle is riding
13	15601	device lock command failed
14	15602	device lock failed: network error
15	15611	device unlock command failed
16	15612	device unlock failed: network error
17	15620	startRental failed
18	15621	startRental failed: network error
19	15622	startRental failed：handlebar failed
20	15623	startRental success, but saddle failed
21	15624	startRental success, but tailbox failed
22	15625	startRental success, but tailbox and saddle failed
23	15627	endRental failed: vehicle is riding
24	15628	endRental failed
25	15629	endRental: network error
26	15630	endRental failed: handlebar lock failed
27	15631	endRental failed: no return helmet
28	15632	endRental failed: saddle lock failed
29	15633	endRental failed: tailbox lock failed
30	15634	endRental failed: tailbox and saddle lock failed
31	15603	handlebar lock failed
32	15613	handlebar unlock failed
33	15635	open failed: please operate when mopeds is unlocking
34	15638	device execute failure

Appendix 2：Fault code list only for E-moped

code	system	description
E0	IoT	ECU communication error
E1	IoT	Backup battery abnormality
E2	IoT	RTC clock error
E3	IoT	File system error
E4	IoT	I2C communication error
E5	IoT	GNSS communication error
E6	IoT	4G Modem communication error
E7	IoT	Bluetooth communication error
E8	IoT	NFC communication error
E9	IoT	G-Sensor communication error
10	centralControl	ECU (Electronic Control Unit) communication error, please check the ECU, dashboard and the connecting cables
11	drive	Motor controller undervoltage protection, please charge before use
12	drive	Motor Hall failure, please check the motor, motor controller and the connecting cables
13	drive	MOS tube malfunction, please check the motor, motor controller and the connecting cables
14	drive	Throttle malfunction, please check the throttle handle, motor controller and the connecting cables
15	drive	he brake switch is abnormal, please check the brake lever, motor controller and the connecting cables
16	centralControl	An error occurred when saving the configuration， please replace the ECU
17	centralControl	Dashboard communication error, please check the LCD cables in the dashboard
18	BMS	Reserved
19	BMS	Lithium-ion battery 1 temperature sensor error, please check the battery
20	BMS	Lithium-ion battery 1 communication error, please check the dashboard, battery and the connecting cables
21	BMS	Lithium-ion battery 1 has the default serial number, please confirm whether it is a genuine battery
22	BMS	Lithium-ion battery 1 password error, please confirm whether it is a genuine battery
23	BMS	Lithium-ion battery 2 temperature sensor error, please check the battery
24	BMS	Lithium-ion battery 2 communication error, please check the dashboard, battery and the connecting cables
25	BMS	Lithium-ion battery 2 has the default serial number, please confirm whether it is a genuine battery
26	BMS	Lithium-ion battery 2 password error, please confirm whether it is a genuine battery
27	BMS	Reserved
28	BMS	Reserved
29	BMS	Reserved
30	BMS	Reserved
31	centralControl	The vehicle has the default serial number, please confirm whether it is a genuine product
32	centralControl	Vehicle password error, please confirm whether it is a genuine product
33	centralControl	Program error. The dashboard program upgrade has failed
34	centralControl	Abnormal vehicle temperature detection, please check the dashboard temperature sensor
35	centralControl	Dashboard and ECU communication error, please check the ECU, dashboard and the connecting cables
36	centralControl	Reserved
37	centralControl	Reserved
38	centralControl	Electric lock malfunction, please check whether the cables are short-circuited or broken
39	centralControl	The storage compartment is not locked
40	centralControl	Reserved
41	centralControl	The handlebar lock is not in place. Please restart the vehicle and move the handlebar so that the lock pin is retracted
42	centralControl	The tail box is not locked
43	centralControl	Reserved
44	centralControl	Reserved
45	centralControl	Reserved
46	centralControl	Reserved
47	centralControl	Battery compartment is unlocked