Vehicle Models⚓︎
Vehicle models are used to describe the behavior and capabilities of every vehicle in the INVERS OneAPI. When adding a vehicle to your fleet directly through our API, you need to provide the ID of the corresponding vehicle model. Choosing the correct vehicle model is important since the vehicle model describes how the telematics unit needs to be configured in order to provide the correct vehicle commands and vehicle state values.
Important
For most use cases, it is sufficient to use our FleetControl UI or our SmartControl app to add or remove vehicles to/from your fleet. You only need to read this page if you would like to integrate your software stack even deeper with the INVERS API, e.g. if you would like to query vehicle model information from within your own applications.
Get all available vehicle models⚓︎
The INVERS OneAPI supports a range of vehicle models from which you can choose. To find the right model, you can use the endpoint GET /telematics-brands/{brand}/available-vehicle-models
of the Vehicle Lifecycle API.
Here is an example of what the response payload might look like when using CLOUDBOXX
as telematics brand:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 |
|
Once you have found the right model, you can use its ID in the POST /vehicles
request as described in the Vehicle Lifecycle API.
Model Extensions⚓︎
Info
Model extensions are supported by cars connected via OEM integrations or by two-wheeler vehicles connected via OEM integration or with a built-in CloudBoxx.
Basic capabilities for your vehicle are defined by the model’s capabilities. Those capabilities only describe the most basic configuration of the vehicle. Just like the vehicle may have optional accessories, e.g. a top case, the vehicle model supports optional extensions. These supported extensions describe what accessories the vehicle can have, as well as what capabilities are associated with each one of them. When a vehicle is created, its actual capabilities are those of the vehicle model combined with those from the selected model extensions.
When calling GET /telematics-brands/{brand}/available-vehicle-models
, the vehicle models in the response payload contain a property called supported_extensions
. This property lists all supported extensions for a vehicle model including their capabilities.
The following extensions are available (depending on the model):
SELF_LOCKING_TOP_CASE
can be used for top cases that lock automatically when closedREMOTE_LOCKING_TOP_CASE
can be used for top cases that need to be locked via the APISUNROOF
can be used for vehicles with a sunroof (only supported by OEM integrations)
Adding a vehicle with model extensions⚓︎
When creating a vehicle, you can select the model extensions for the vehicle by adding the property model_extensions
to the setup
when using the endpoint POST /vehicles
of the Vehicle Lifecycle API.
Example
The example below shows the API call to add a single vehicle with model extensions. In the example, a vehicle is added which has a top case that can be locked remotely using the Vehicle Commands API.
curl -X POST \
https://api.invers.com/vehicles \
-H 'Authorization: Bearer ❰access_token❱' \ # (1)!
-H 'Content-Type: application/json' \
-d '{
"telematics_unit": {
"id": "NBSG7D2A50742X0F",
"brand": "NIU",
"setup": {
"vehicle_model_id": "01F4XW6QHWKT4HMSFDZ9CCQH1G",
"model_extensions": [
"REMOTE_LOCKING_TOP_CASE"
]
},
"authentication": {
"credentials_id": "01F62857KMPG2NE2GK1W2N3QYS"
}
},
"master_data": {
"vin": "R1NBDNB16J1000135",
"license_plate": "RKL-832",
"brand": "NIU",
"model": "N1",
"custom_name": "MyNiuN1",
"fuel_type": "ELECTRIC",
"year_of_production": "2020",
"transmission": "AUTOMATIC",
"vehicle_type": "MOPED",
"remark": "Our customers like that scooter very much."
},
"custom_fields": {
"seats": "2",
"color": "black"
}
}'
- Don’t forget to fill in your access token.
In the response body of this request, the created vehicle contains the additional capabilities from the selected extension (REMOTE_LOCKING_TOP_CASE
):
LOCK_TOP_CASE
andUNLOCK_TOP_CASE
as command capabilitiesTOP_CASE_LID
andTOP_CASE_LOCK
as vehicle state capabilities
Updating model extensions of an existing vehicle⚓︎
Model extensions can also be added to an existing vehicle. To update the model extensions of an existing vehicle simply use the PUT /vehicles/:id/telematics-unit/setup
endpoint and provide the extensions you want to select using the property model_extensions
in the setup
object.
Warning
Keep in mind that this endpoint will override all selected extensions that where previously assigned to the vehicle. Always provide all required information when calling the telematics unit setup endpoint.