# Segway API-Max Plus X
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
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
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 location
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
This API is used to get the scooter's battery information.
GET
/api/v2/vehicle/query/current/battery-info
curl -X GET \
https://api_domain:port/api/v2/vehicle/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 |
| controllerVoltage | String | controller voltage,412->4.12V |
| batteryData | list | Object list: 'battery data' |
attached：'battery data'
| field | type | description |
|---|---|---|
| batteryPercent | Number | batterypercent, unit/80->80% |
| cycleTimes | Number | cycleTimes |
| temperatrue1 | Number | temperatrue1, unit/℃ |
| temperatrue2 | Number | Temperatrue2, unit/℃ |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "success",
"data": {
"iotCode": "{iotCode}",
"charging": true,
"controllerVoltage": 26,
"batteryData": [
{
"batteryPercent": 52,
"cycleTimes": 23,
"temperatrue1": 25,
"temperatrue2": 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
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"
}
# get component status
This API is used to obtain the the current status of components.
GET
/api/v2/vehicle/query/component-status
curl -X GET \
https://api_domain:port/api/v2/vehicle/query/component-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 |
| helmetLockStatus | Number | 0:Unlocked 1:locked |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "success",
"data": {
"iotCode": "{iotCode}",
"helmetLockStatus": "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 helmet lock info
This API is used to obtain the the Bluetooth info(MAC address and key) of the helmet lock.
GET
/api/v2/vehicle/query/helmet-lock-info
curl -X GET \
https://api_domain:port/api/v2/vehicle/query/chelmet-lock-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 |
|---|---|---|
| searchKey | String | IoT IMEI or helmet lock MAC address |
| searchBy | Number | 0: IoT IMEI 1: helmet lock MAC address |
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 |
| bleMAC | String | helmet lock Bluetooth MAC address, with colon ":". if there is no helmet lock bind to this vehicle, this field will be the empty string. |
| bleKey | String | helmet lock Bluetooth Key if there is no helmet lock bind to this vehicle, this field will be the empty string. |
HTTP/1.1 200 OK
{
"code": 0,
"msg": "success",
"data": {
"iotCode": "{iotCode}",
"bleMAC": "12:34:56:78:90:AB",
"bleKey": "12345678",
},
"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 |
HTTP/1.1 200 OK
{
"code": 15102,
"msg": "device not found",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# Control
# unlock
This API is used to unlock the vehicle
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 | 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
This API is used to lock the vehicle
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 | 15996 | device lock failed: denied by geofence strategy |
| 14 | 15997 | device lock failed: unable to lock while riding |
| 15 | 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"
}
# light
This API is used to turn the vehicle's light flicker on/off.
POST
/api/v2/vehicle/control/light
curl -X POST \
https://api_domain:port/api/v2/vehicle/control/light \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode": "861477038719116",
"headLight": 0,
"tailLight": 0
}'
Header
| field | type | description |
|---|---|---|
| Content-Type | String | allowed: "application/json" |
| Authorization | String | allowed: "bearer access_token" |
Parameter
| field | type | description |
|---|---|---|
| iotCode | String | IoT IMEI |
| headLight(optional) | Number | 0→ off, 1→ on, 2→flicker |
| tailLight(optional） | Number | 0→ off, 1→ on, 2→flicker |
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"
}
# throttle response
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"
}
# battery component
This API is used to open the battery compartment.
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 |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# mech lock
This API is used to open the mech lock.
POST
/api/v2/vehicle/control/mech-lock
curl -X POST \
https://api_domain:port/api/v2/vehicle/control/mech-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 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 |
HTTP/1.1 200 OK
{
"code": 15302,
"msg": "device response timeout",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# sound
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→driving out of Geo-fence. 2→toot. 3→low battery percentage 10→custom sound1 11→custom sound2 12→custom sound3 13→custom sound4 14→custom sound5 15→custom sound6 16→custom sound7 17→custom sound8 18→custom sound9 |
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"
}
# ambient
This API is used to set the atmosphere lamp effect, it will works immediatelly until the next time the vehicle’s status is switched or the next time you set.
POST
/api/v2/vehicle/control/ambient
curl -X GET \
https://api_domain:port/api/v2/vehicle/control/ambient \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode" : 862785041281554,
"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 |
| bright | Number | 1:Low 2:Medium 3:High |
| mode | Number | 0:Auto 1:Off 2:Always on 4:Breathing |
| 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 | 15303 | command send failed |
| 8 | 15500 | device upgrading: command can not be executed |
HTTP/1.1 200 OK
{
"code": 15300,
"msg": "inactive device",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# wireless charging
Wireless charging for mobile phones is enabled when the vehicle is unlocked by default. Through this interface you can turn it off if you want to close this function during this unlocking period.
POST
/api/v2/vehicle/control/wireless-charging
curl -X GET \
https://api_domain:port/api/v2/vehicle/control/wireless-charging \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode" : 862785041281554,
"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 | 15303 | command send failed |
| 8 | 15500 | device upgrading: command can not be executed |
HTTP/1.1 200 OK
{
"code": 15300,
"msg": "inactive device",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# transport mode
This API is used to set the vehicle into the transportation mode in which vehicle will be powered off. Vehicle in transportation mode will be in offline state. We suggest using this command when your scooters won't be deployed and will be kept in the warehouse for months
POST
/api/v2/vehicle/control/whole-shutdown
curl -X GET \
https://api_domain:port/api/v2/vehicle/control/whole-shutdown \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode" : 862785041281554
}'
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 | 15303 | command send failed |
| 8 | 15500 | device upgrading: command can not be executed |
HTTP/1.1 200 OK
{
"code": 15300,
"msg": "inactive device",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# helmet
This API is used to control the helmet component.
POST
/api/v2/vehicle/control/helmet
curl -X GET \
https://api_domain:port/api/v2/vehicle/control/helmet \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode" : 862785041281554
}'
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 (optional) | Integer | 0→ unlock (default) 1→ lock |
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 | 15611 | device unlock command failed |
HTTP/1.1 200 OK
{
"code": 15300,
"msg": "inactive device",
"data": null,
"t": 1593333694412,
"opId": "3de041d2-7f1e-4cb2-a7be-483378727c56"
}
# Setting
# switch setting
This API is used to turn on or off the switch.
POST
/api/v2/vehicle/setting/switch
curl -X POST \
https://api_domain:port/api/v2/vehicle/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 |
| alertSensitivity(optional) | Number | strength range: 1-3 |
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 vehicles.
POST
/api/v2/vehicle/setting/able-switch
curl -X POST \
https://api_domain:port/api/v2/vehicle/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 |
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"
}
# extra-switch enable
This API is used to enable or disable the extra switch of vehicles.
POST
/api/v2/vehicle/setting/extra-able-switch
curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/extra-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 |
| zoneFlickerFreq(optional) | Number | the frequency of zone indicator flicker, 4 level, 0-3, 0 is the slowest, 3 is the most frequent. |
| ambientFlickerFreq(optional) | Number | the frequency of dashboard status light flicker and tube-side atmosphere light flicker, 4 level, 0-3, 0 is the slowest, 3 is the most frequent. |
| brakeTailLight(optional) | Number | used to enable or disable the tail light when the brake is hold. 1→off. 2→on 3→flicker |
| brakeAmbientLight(optional) | Number | used to enable or disable the tube-side atmosphere light when the brake is hold. 1→off(auto). 3→flicker |
| turnAmbientLight(optional) | Number | used to enable or disable the tube-side atmosphere light when the brake is hold. 1→off(auto). 5→iridescent |
| batteryDisplayEnable(optional) | Number | used to enable or disable the battery level indicator when the vehicle is unlocked. 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"
}
# scooter settings
This API is used to set the scooter’s parameters.
POST
/api/v2/vehicle/setting/scooter
curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/scooter \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode" : "861477038719116",
"bssDisplay": 0,
"cruiseControl" : 1,
"buttonSwitchSpeedMode" : 0,
"lowSpeedLimit":6,
"mediumSpeedLimit":18,
"highSpeedLimit":25
}'
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) | String | displayed as bbs(British Standard speed). 0→ turn off. 1→ turn on |
| cruiseControl(optional) | Number | 0→ turn off. 1→ turn on |
| buttonSwitchSpeedMode(optional) | Number | use button to switch speed mode. 0→ turn off. 1→ turn on |
| lowSpeedLimit(optional) | Number | Size range: 6-25. unit：km/h |
| mediumSpeedLimit(optional) | Number | size range: 6-25. unit：km/h |
| highSpeedLimit(optional) | Number | size range: 6-25. 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"
}
# 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": 0,
"lockedMode": {
"mode": 1
},
"readyMode": {
"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 |
| bright | Number | Common atmosphere lamp brightness of each mode. 0:Default Brightness |
| lockedMode | Object | An object that indicates the atmosphere lamp effect |
| readyMode | Object | An object that indicates the atmosphere lamp effect |
| faultMode | Object | An object that indicates the atmosphere lamp effect |
attached:'lockedMode,readyMode,faultMode'
| field | type | description |
|---|---|---|
| mode | Number | 1:Off 2:Always on 4:Breathing |
| bright (Optional) | Number | 1:Low 2:Medium 3:High |
| 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"
}
# zone indicator setting
This API is used to set relevant parameters of the vehicles.
POST
/api/v2/vehicle/setting/zone-indicator
curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/zone-indicator \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode":"8612345678901",
"bright": 0,
"noDrivingZone": {
"mode": 1
},
"noParkingZone": {
"mode": 2,
"color": 1
},
"limitSpeedZone": {
"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 |
| bright | Number | Common atmosphere lamp brightness of each mode. 0:Default Brightness |
| noDrivingZone | Object | An object that indicates the atmosphere lamp effect |
| noParkingZone | Object | An object that indicates the atmosphere lamp effect |
| limitSpeedZone | Object | An object that indicates the atmosphere lamp effect |
attached:'noDrivingZone,noParkingZone,limitSpeedZone'
| field | type | description |
|---|---|---|
| mode | Number | 1:Off 2:Always on 3:Blinking |
| 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 | Number | Volume (1-3）: 1 is the smallest and 3 is largest. |
| sctoMask(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:'sctoMask'
| field | type | description |
|---|---|---|
| powerOn (optional) | Number | 0:disable 1:enable 2:keep original |
| powerOff (optional) | Number | 0:disable 1:enable 2:keep original |
| locked (optional) | Number | 0:disable 1:enable 2:keep original |
| unlocked (optional) | Number | 0:disable 1:enable 2:keep original |
| lostHeartbeat (optional) | Number | 0:disable 1:enable 2:keep original |
| outofGeofence (optional) | Number | 0:disable 1:enable 2:keep original |
| intoGeofence (optional) | Number | 0:disable 1:enable 2:keep original |
| alarm (optional) | Number | 0:disable 1:enable 2:keep original |
| locating (optional) | Number | 0:disable 1:enable 2:keep original |
| beep (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 |
| 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"
}
# speed mode
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
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"
}
# NFC
This API is used to set the NFC work-mode and its tag info.
POST
/api/v2/vehicle/setting/nfc
curl -X POST \
https://api_domain:port/api/v2/vehicle/setting/nfc \
--header 'Authorization: bearer f3bbd782-04c7-42e5-bed9-524cde3eb415' \
--header 'Content-Type: application/json' \
--data '{
"iotCode" : "861477038719116",
"workMode": 0,
"tagData" : "aHR0cDovL2V4YW1wbGUuY29tL3FyY29kZS9BMTIzNDU="
}'
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 | 0→ NFC card emulation.1→NFC reader/writer. |
| tagData | String (Optional) | A standard (RFC 4648 §4) base64 encoded string which indicated the NFC Tag information, with its max length 140 bytes. e.g. Step1: Original info, with its max length 140 bytes. Suppose you original tag info is http://example.com/qrcode/A12345 Step2: Standard (RFC 4648 §4) base64 encode. aHR0cDovL2V4YW1wbGUuY29tL3FyY29kZS9BMTIzNDU= Step3: Got your tagData value, { "tagData": "aHR0cDovL2V4YW1wbGUuY29tL3FyY29kZS9BMTIzNDU="} |
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 | 15998 | The data length of the NFC Tag information exceeds the maximum limit |
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
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. 13->brake line looseness detection 14->tandem riding detection available disappeared alert code: 1->illegal moving. 2->vehicle fell down. 3->illegal dismantling. 13->brake line looseness detection 14->tandem riding detection |
| 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
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
This API should be exposed by your application system to receive the vehicle's location. When the scooter is unlocked, its location will be pushed once every 10 seconds. When the scooter 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
This API should be exposed by your application system to receive the changes of the scooter's status. When the scooter 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 | scooter 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 scooter 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
}
# mech-lock status
This API should be exposed by your application system to receive the status of mechanical lock.
POST
/v2/vehicle/mech-lock
https://business:port/v2/vehicle/mech-lock \
-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 |
| statusUtcTime | Number | timestamp |
| status | Number | 0→ mechanical lock pin is inserted |
| 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: 8→helmet lock 9→steel cable lock |
| status | Number | operation status: 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
}
# NFC event report
This API should be exposed by your application system to receive the event when the authorization card swiped the NFC reader of the vehicle.
POST
/v2/vehicle/nfc-event
curl -X POST \
https://business:port/v2/vehicle/nfc-event \
-header 'Content-Type: application/x-www-form-urlencoded' \
-data 'iotCode={iotCode}&platformCode={platformCode}&signature={signature}&eventUtcTime={eventUtcTime}&eventType={eventType} \
&tagId={tagId}'
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 |
| eventUtcTime | Number | timestamp |
| eventType | Number | 0->authorization card swiped The vehicle has been unlocked or locked operation at this time generally. |
| tagId | Number | The ID of NFC Card which was authorized to lock and unlock the vehicle. |
| 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 |
# Appendix 2：Fault code list
| 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 | / | Abnormal communication between instrument panel and main control |
| 11 | motor | Abnormal A phase current sampling of the motor |
| 12 | motor | Abnormal B phase current sampling of the motor |
| 13 | motor | Abnormal C phase current sampling of the motor |
| 14 | / | Abnormal accelerator Hall |
| 15 | / | Abnormal left brake Hall |
| 16 | / | Abnormal right brake Hall, this error only would occur on MAX 2.3 plus |
| 17 | / | Undefined |
| 18 | / | Abnormal motor Hall |
| 19 | BMS | Battery abnormality in voltage detection |
| 20 | / | Undefined |
| 21 | BMS | Battery abnormality in communication |
| 22 | BMS | Battery password is wrong |
| 23 | BMS | Battery is in default serial number |
| 24 | ECU | System voltage detection abnormality |
| 25 | ECU | Undefined |
| 26 | ECU | Flash save error |
| 27 | ECU | Master control password is wrong |
| 28 | / | Undefined |
| 29 | / | Undefined |
| 30 | / | Undefined |
| 31 | / | Program skip error |
| 32 | / | IOT and scooter communication timeout error |
| 33 | / | Undefined |
| 34 | / | Undefined |
| 35 | / | Vehicle is in default serial number |
| 36 | / | Undefined |
| 37 | / | Charging base failure or battery charging wire failure |
| 38 | / | Undefined |
| 39 | / | Battery temperature sensor abnormality |
| 40 | / | Controller temperature sensor abnormality |
| 41 | / | Over temperature of motor |
| 50 | / | Verfication between battery and controller failed |
| 51 | / | Main controller and goose head doesn’t match with each other |
| 52 | / | The identify code of main controller is not matched with swappable battery lock |
| 54 | / | The communication status between main controller and swappable |