Integration Guide⚓︎
Basics⚓︎
The INVERS OneAPI consists of several parts, all of which are designed to serve a specific use case or task. For example, the Vehicle Commands API provides separate endpoints for each vehicle command that is supported by the INVERS OneAPI. The Vehicle Management API on the other hand provides you with endpoints to view and manage the vehicles within your fleet. For a complete list of the available APIs, go to API Reference.
Most of the APIs of the INVERS OneAPI are RESTful APIs and can all be used by your application with one set of credentials (see Access Management). The only exception is the Events API, which is based on AMQP and follows a different authentication mechanism for your event consumers (see Events).
Prerequisites⚓︎
Before you start your integration with the INVERS OneAPI, you need client credentials to be able to authenticate and authorize your application against our REST APIs. You can create and manage your client credentials through FleetControl - simply go to “Administration” -> “Auth Clients”. For security purposes, we recommend that you use separate client credentials for each application that you wish to integrate with the INVERS OneAPI.
Permissions
Depending on the use case and tasks of your particular application, we recommend that you restrict the access of the associated client – e.g. by not allowing to send commands to vehicles if the application in question does not need to do so.
You can find additional information in the Access Management section of this documentation. Please contact INVERS Support if you require assistance or additional information on this topic.
Workflows⚓︎
The following workflows assume that you have a basic knowledge of vehicles, vehicle state, vehicle commands, and vehicle capabilities.
Add vehicles to your fleet⚓︎
Before you can interact with your vehicles via INVERS OneAPI, you need to add your vehicles to your OneAPI fleet. This can always be done by using the Vehicle Lifecycle API. However, unless you have an advanced workflow where you would like to add vehicles right from within your own application, it is more convenient to use one of our user interfaces for this task:
- If you need to add a vehicle connected through OEM Integrations, simply use the “adding vehicle assistant” in FleetControl
- If you would like to add a CloudBoxx-equipped vehicle to your fleet, use our SmartControl app
We recommend that you have a look at the Vehicle Lifecycle page if you would like to know more about the “adding vehicle process”. You’ll also find a list of required and additional/optional properties that you need to successfully add vehicles to your fleet. In case you would like to go “all in” directly and use our API to add your vehicles, you’ll also find example requests there.
Send commands to your vehicles⚓︎
Once you have added your vehicles to your OneAPI fleet, use the Vehicle Commands API to send commands to those vehicles. Besides the command that you would like to execute, e.g. unlock-central-lock, the only thing you need is the unique vehicle_id, which is created for each vehicle when it is added to your fleet.
Go to Vehicle Commands to get additional information on commands as well an an example request that will help you get started with your own implementation.
Manage your fleet’s vehicles⚓︎
The main API for managing the vehicles in your fleet is the Vehicle Management API. Use it to store additional information about the vehicles which you have added to your INVERS OneAPI fleet (see above). All of the information that you add to your vehicles through the Vehicle Management API will also be visible in FleetControl and help you identify and manage your vehicles.
These are the main tasks you can use the Vehicle Management API for:
- List all vehicles within your fleet, including paged search and filtering mechanisms
- Alter the master data (VIN, license plate, vehicle type, transmission, etc.), custom fields, or operation status of a vehicle
- Retrieve the most recent vehicle state, the vehicle’s capabilities, master data, custom fields, operation status, or associated telematics unit of a vehicle
Go to Vehicle Management for more detailed information about managing your vehicles, as well as an example request to get you started.
Keep your vehicle master data in sync⚓︎
Depending on your use cases and software stack, you might want to have at least some parts of your vehicle data stored within your own software and the corresponding databases. This is mainly the case for those vehicle properties that are relevant to your business workflows. After all, you need those properties frequently and fast, and do not necessarily want to store them only “externally” and then have to retrieve them every time you need them.
Of course, this is perfectly fine. Almost all of the properties that can be stored for your vehicles via the Vehicle Management API are not mandatory. If you do not wish to store additional information about your vehicles within the INVERS OneAPI, such as license plate, vehicle type, transmission, custom fields, etc., you do not have to. However, there are a lot of advantages coming your way if you push those properties, which you might initially only need within your own domain, into the OneAPI representation of your vehicle. The main reason for this is FleetControl, our fleet management tool that comes with INVERS OneAPI (independently from the telematics brand you are using in your vehicles).
Since FleetControl uses the same Vehicle Management API as you do to manage your vehicles within OneAPI, keeping the data in sync between your own application(s) and the INVERS OneAPI means that you have the same data available within FleetControl as you have in your own application(s). This enables your authorized employees and support personnel to support your business workflows that rely on FleetControl and to always find and identify the correct vehicles for their tasks.
We have kept the process of keeping the data in sync between your application(s) and the INVERS OneAPI as easy and light-weight as possible. You can simply update your vehicles using the Vehicle Management API each time you update relevant properties of the vehicle within your own application(s).
In combination with our asynchronous Events API, this synchronization process also works in reverse. For example, if your employees make changes to a vehicle’s master data through FleetControl, you can simply consume the “VehicleChanged” event for your fleet in order to get notified about these changes immediately and then reflect the changes in your own database.
Oftentimes, you might also begin creating a vehicle within FleetControl in order to assign it to a telematics unit. In that case, you can use the Events API to subsequently also create the vehicle within your own application(s) - without the need to enter all the data again.
Advanced
If you are running multiple applications that all need to access the vehicle’s masterdata, you could even make use of the synchronization process based on the Events API in order to keep your own application(s) in sync.
Let’s say you have an application that is being used by your field service or maintenance team, and they need to flag one of your vehicles as “broken”. This application could simply make this change through the Vehicle Management API and your other application(s), e.g. the one that handles your vehicle bookings, would be made aware of this change simply by consuming all “VehicleChanged” events of the Events API.
Always know the current state of your vehicles⚓︎
Whether you always want to display the vehicle’s current state of charge to your customers or create an alert for your employees as soon as one of your vehicles leaves a predefined area: these are just two examples where you always need the most up-to-date state of your vehicles delivered right to your own application. The INVERS OneAPI offers you an Events API to achieve this.
As soon as your vehicles transmit new information, you will receive a VehicleStateRecorded event containing a new vehicle state with all of the information that was just transmitted by the vehicle. Of course, the vehicle state within this event has the same format as everywhere else within the INVERS OneAPI, taking into account the vehicle’s state capabilities.
Syncing the states of your vehicles between INVERS OneAPI and your application is completely optional. But if you need or want to keep your applications up-to-date, this is the way to go!
Warning
It is not recommended to use the latest-vehicle-state endpoint of the Vehicle Management API to achieve this task. Please do not regularly poll this endpoint and use the Events API as described here instead!
React to certain events directly⚓︎
In addition to the raw vehicle state (see above), the INVERS OneAPI offers you additonal, dedicated events if certain vehicle state values change. This is the case for all discrete values of the vehicle state, e.g., CentralLockChanged, WindowsStatusChanged, and so on. You’ll also find events for non-discrete values, like the VehicleRechargedOrRefueled event.
Depending on your use case or type of application, it might make more sense for you to consume all of the raw VehicleStateRecorded events. However, let’s say you have an application that should only listen to and monitor any changes of maintenance and indicator lights within your vehicles, then consuming the VehicleMaintenanceAndIndicators topic will easily achieve just that. Go to our event topic list to find out which event topics exist and what type of events are contained in each topic.
Remove vehicles from your fleet⚓︎
Sometimes it may be necessary to remove a vehicle from your fleet. The most convenient way to remove a vehicle is to find the vehicle in FleetControl, and then to simply archive it.
An archived vehicle can be added back to your OneAPI fleet at a later time, if needed. Once a vehicle has been archived, we retain the vehicle and vehicle states in our vehicle archive for 90 days. Once this timespan has passed, the vehicle and all historical data (e.g., vehicle states) are deleted irreversibly.
If, instead of using FleetControl, you would like to remove vehicles using our API, check out the Vehicle Lifecycle page for more details.