Skip to content

Integration Guide⚓︎

Want to integrate CloudBoxx?

Currently, you can only access your CloudBoxx-equipped vehicles with the CloudBoxx API but not yet through the INVERS OneAPI. We are actively working on making all CloudBoxx features available in the INVERS OneAPI.

Learn More

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 Messaging API, which is based on AMQP and follows a different authentication mechanism for your message consumers (see Messaging).

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 (mainly sending commands or receiving vehicle messages), you need to add your vehicles to your OneAPI fleet. For now, this can be done by using the Vehicle Lifecycle API and soon, also within FleetControl directly. In order to get you started, we recommend you have a look at the Vehicle Lifecycle page. There, you can find a list of required and additional/optional properties needed for adding vehicles to your fleet as well as an example request.

Note that currently only CloudConnect vehicles are supported within the INVERS OneAPI. All CloudBoxx-equipped vehicles can be configured and tested for usage with the CloudBoxx API using the SmartControl app.

Send commands to your vehicles⚓︎

Once you have added your CloudConnect 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.

Vehicle Management API

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, associated telematics unit of a vehicle
  • Add, change, or remove custom fields of multiple vehicles at once in a bulk operation

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, CloudBoxx, or CloudConnect.

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).

Vehicle master data synchronization flow

In combination with our asynchronous Messaging 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” message 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 Messaging 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 Messaging 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” messages of the Messaging 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 Messaging API to achieve this.

As soon as your vehicles transmit new information, you will receive a VehicleStateReceived message containing a new vehicle state with all of the information that was just transmitted by the vehicle. Of course, the vehicle state within this message has the same format as everywhere else within the INVERS OneAPI, taking into account the vehicle’s state capabilities.

Vehicle state synchronization flow

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 Messaging API as described here instead!

Back to top