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 will receive your individual client credentials from INVERS Support. For security purposes, we recommend that you use a separate client 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 the “adding vehicle assistant” within FleetControl. In order to get you started on the adding vehicle topic, we recommend you have a look at the Vehicle Lifecycle page where you can find a list of required and additional/optional properties you need to 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.
It is currently not possible to add CloudBoxx-equipped vehicles to your fleet via FleetControl. Configure and test your CloudBoxx vehicles using our SmartControl app.
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.
The main tasks you can use the Vehicle Management API for are:
- List all vehicles within your OneAPI 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 master data, custom fields, operation status, most recent vehicle state, the vehicle’s capabilities, or associated telematics unit of a vehicle
For detailed information on the underlying concepts as well as an example request to help you get started, go to Vehicle Management.
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, 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 also 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, independantly 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 the 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!
Remove vehicles from your fleet⚓︎
Sometimes it may be necessary to remove a vehicle from your OneAPI fleet. This may be the case, for example, when a vehicle is sold or temporarily suspended. This can always be done by using the Vehicle Lifecycle API or the more convenient way via FleetControl.
These vehicles can be added back to your OneAPI fleet at a later time. When a vehicle is removed from the fleet, its data is stored in our vehicle archive for 90 days.
If, instead of using FleetControl, you would like to remove vehicles with our API directly, check out the Vehicle Lifecycle page