Skip to content

Migration Guide: How to start using OneAPI endpoints as CloudBoxx API customer⚓︎

This page is intended for all INVERS customers which are using our CloudBoxx API and now would like to either partially or fully migrate to our new generation of APIs (often called “OneAPI”). This new API generation offers a lot of advantages, enabling new and exclusive features that were not possible with the device-centric CloudBoxx API, while still being fully compatible with the INVERS CloudBoxx. Feedback from customers like you has been incorporated into these new APIs.

Due to the paradigm shift from having a device-centric API (qnr as identifier) to a vehicle-centric API (vehicle_id as identifier) there are some important changes you should know about before you start using our new generation of APIs. There is no need to completely change your integration with INVERS. Both APIs can be used in parallel, and there are no plans to deprecate the CloudBoxx API at the moment. However, some new features will only be added to our new APIs, as they require their vehicle-centric approach.

Advantages of new APIs⚓︎

The vehicle is at the center of your business, and should ultimately be the main entity in our APIs. This opens up new possibilities and simplifies processes:

  • Vehicle entity hides complexity of telematics unit
  • Keep vehicle data and history when replacing a telematics unit
  • Combine multiple telematics units (data sources) into one vehicle. Examples:
    • Add maintenance data retrieved via OEM API to a vehicle equipped with a CloudBoxx
    • Add additional backup tracker to a vehicle equipped with a CloudBoxx
  • Improve synchronization of data between your software stack and INVERS (read our integration guide or see below for details)
    • In addition to license plate and vehicle identification number, several additional masterdata fields are supported by our new Vehicle Management API

Differences to CloudBoxx API⚓︎

Authentication & URL⚓︎

Our OneAPI endpoints use the OAuth 2.0 standard for authentication and authorization. The API keys you know from our CloudBoxx API will not work here. Instead, you’ll need client credentials to retrieve an access token and successfully use endpoints of our OneAPI. Look at our authentication section for details. Once we have enabled OneAPI access for your fleet, you can create API Clients (client credentials) on your own in FleetControl. Have a look at our FleetControl manual for details.

URL & Documentation

The base URL of all our OneAPI endpoints is https://api.invers.com/. You can find detailed documentation about all our OneAPI endpoints in the API reference section.

Identifier: vehicle_id vs. qnr⚓︎

When using our device-centric CloudBoxx API, you need the unique identifier of the CloudBoxx (qnr) to address a certain CloudBoxx. Our new API generation puts your vehicle into the center, and we create an alpha-numeric vehicle_id for each vehicle. As soon as you install a CloudBoxx into a vehicle and perform a setup, we will automatically create a vehicle with a globally-unique vehicle_id in our vehicle inventory. Subsequently, this vehicle keeps its identifier until it is archived by you. Replacing the telematics unit, changing vehicle model configuration, or adding a second telematics unit to it won’t change its vehicle_id so you always have a representation of your real-world vehicle in the INVERS ecosystem.

Most likely, you are currently storing the QNR of the CloudBoxx associated with a vehicle in your booking system. Going forward, you’ll need to store the vehicle_id instead of, or in addition to the QNR. This depends on whether you fully migrate to our new generation of APIs right now or later. This change might sound like a bigger challenge than it is, as we have greatly improved how to keep the vehicles and vehicle data in sync between INVERS and your booking software - mainly using a new, event-driven approach (see below).

How to synchronize vehicles⚓︎

Before you can effectively use our new vehicle-centric API endpoints, your booking system needs to learn the vehicle_id for each of your vehicles. This needs to happen once for all your existing vehicles, and then continuously for all newly added vehicles - similar to how you attached a CloudBoxx QNR to each vehicle in your booking software up until now. In this section, we give recommendations for both, the initial one-time sync and the continuous sync of vehicles. Although this might sound like a lot of work, we assure you it is actually not that complex. The suggested synchronization process comes with a lot of advantages, and most likely removes the previous need to manually link CloudBoxx QNRs with vehicles in your booking system.

Initial one-time sync⚓︎

We recommend that you initially retrieve the required data by exporting your vehicles from the Vehicles Page in FleetControl (see “Export Preset Data”). Make sure to add the columns “Vehicle ID” and “Telematics Unit ID (QNR)” to the table view before exporting your vehicles. You can use the telematics unit identifier (QNR) to match each line of the export with the correct vehicle in your database and add the corresponding vehicle_id to it.

Another, more programmatic option for an initial synchronization is to use the GET /vehicles endpoint (API reference). You can iterate through the paged results (depending on your fleet size), and specifically look at id (vehicle_id), telematics_unit.id (QNR), and optionally masterdata.vin and masterdata.license_plate if you also would like to synchronize these properties whilst you are at it.

Continuous vehicle sync⚓︎

Our new OneAPI architecture helps you to ensure vehicle data always stays in sync between your booking system and the INVERS platform. This is achieved by using a combination of:

  • A REST API endpoint (see API reference) which you can use to inform the INVERS platform of any changes to your vehicle’s masterdata (e.g., VIN, license plate, tags)
  • Asynchronous events (RabbitMQ) that you can consume to get notified of any changes to your vehicles through the INVERS platform (e.g., a new vehicle is created by installing and configuring a CloudBoxx, or a license plate is updated via FleetControl)

Additional details

This synchronization flow is explained in more detail in our integration guide.

The asynchronous events you need to consume can be found on our VehicleChange topic. The INVERS platform publishes an event each time a vehicle is created, changed or archived (see below for more details). View the documentation here and read through our events section to find out how you can consume those events. If you are already consuming our CloudBoxx API events via RabbitMQ, adding the VehicleChange topic is pretty straightforward. Although we publish the VehicleChange topic on another RabbitMQ instance, you can reuse your entire implementation as the authentication mechanism and general setup of both instances are identical. You can manage your event consumers for this RabbitMQ instance yourself via FleetControl (find out how).

Relevant event types⚓︎

The VehicleCreated event is published when a CloudBoxx was installed into a vehicle and a setup was triggered using SmartControl, or via our APIs. The event contains the created vehicle entity in its entirety. Important properties to look out for are:

  • vehicle_id: main identifier of the vehicle
  • telematics_unit.id: CloudBoxx QNR (main identifier of the telematics unit)
  • masterdata.*: vehicle masterdata like VIN and license plate (you can synchronize those into your booking system)

The VehicleChanged event is published if, subsequently, changes are made to the vehicle - either through FleetControl, SmartControl, or our APIs. It helps you to keep your vehicle data in sync between the INVERS platform and your own software stack. Look out for the reason provided as part of the event to find out why the event was generated. Some common reasons are:

  • MASTER_DATA_CHANGED: VIN, license plate, or other masterdata of the vehicle has been changed
  • LIFE_STATUS_CHANGED: the life status of the vehicle has changed (e.g. once the setup of the installed CloudBoxx is completed, the life status changes from SETUP to ONLINE)
  • TELEMATICS_UNIT_REPLACED: the CloudBoxx previously installed into the vehicle was replaced by another CloudBoxx (using SmartControl or indicated by you through our APIs)

The VehicleArchived event tells you that a CloudBoxx was uninstalled from a vehicle and the vehicle was archived. This needs to be done either by using FleetControl, SmartControl, or our dedicated API endpoint. We will automatically archive an existing vehicle if we detect that the CloudBoxx that has been installed into that vehicle is now being used in another vehicle (a setup was performed using a different VIN, for example).

Using OneAPI endpoints⚓︎

Once you are able to authenticate to our new generation of APIs (see above) and your booking system is aware of the vehicle_id of all your vehicles (see above) you are ready to go. You can use our most recent API endpoints and the features they offer. Some examples:

  • The rental status of each vehicle can be used as trip trigger, to optimize the firmware update process, and more. Find out more under rental status or typical rental flow.
  • With FleetShare you can share your vehicles with other operators to increase utilization. See FleetShare to find out more.

Asynchronous Events⚓︎

In our OneAPI infrastructure we have also improved the structure of our asynchronous Events API. The message queues of the CloudBoxx API, which you know and might have integrated, offers three event topics: events, trackings, heartbeats. These topics are rather close to the technical way how our CloudBoxx works, and all events contained in those topics are generated directly by the CloudBoxx. In contrast, the Events API and message queue of our OneAPI infrastructure offers a broader range of event topics, and they are organized with your use cases and workflows in mind. We recommend having a look at the full list of topics and events to get a better idea of the differences. Detailed documentation of all events listed there can be found here.

Like with our REST APIs, we do not have any plans to deprecate or shutdown the CloudBoxx message queues at this point in time. You can continue to use our existing CloudBoxx message queues without any changes. However, we recommend looking at our new generation of Events APIs as well, especially if you are working on your existing implementation anyways or add additional services to your software stack that serve a specific task. In those cases, we might offer a dedicated event topic for that purpose that helps you reducing your implementation complexity and consumer load (by only consuming the specific events required for a specific task). You can use the current and new event infrastructure side-by-side. If you are already using our asynchronous events for trips or speeding, then you are already using a part of our new event infrastructure.

Examples for differences between previous and new Events API

  • More independent from telematics unit protocol: events, trackings, heartbeats of CloudBoxx all result in a VehicleStateRecorded event with unified structure
  • CloudBoxx events with reasons like central_lock_changed or windows_changed are additionally published in dedicated VehicleOperation topic (e.g., as CentralLockChanged event)
  • CloudBoxx events with reasons like boot or bluetooth_connected are published in dedicated TelematicsUnitOperation topic
  • For the can_value_high and can_value_low events there are dedicated events named properly after what is actually happening