Vehicle Commands API⚓︎

Vehicle Commands API

The Vehicle Commands API allows you to actively communicate with vehicles by sending commands. The supported commands range from requesting a new vehicle state to controlling vehicle functions, for example unlocking the central lock.

Preconditions⚓︎

Before you can send commands to your vehicles, you have to add the vehicles to your fleet. For detailed information on how to add vehicles to your fleet, see Vehicle Lifecycle API.

Sending commands⚓︎

The Vehicle Commands API is centered around vehicles, not the telematics units built into those vehicles. Consequently, when sending commands to a vehicle, the vehicle is being addressed and identified by its own unique identifier (vehicle_id).

Not every vehicle supports all commands. For example, a car will not be able to unlock its top case as it does not have a top case. Also, not all telematics units support the “request vehicle state” command to actively request a new vehicle state from the vehicle. A vehicle’s command capabilities tell you which commands are supported by the vehicle in combination with the built-in telematics unit. If a vehicle does not have the command capability to execute a specific command, an error (409 Conflict) will be returned each time you send such a command.

If the command has been successful, a JSON object containing the updated vehicle state is returned along with HTTP status code 200. The properties contained in the resulting vehicle state depend on the vehicle model, the installed telematics unit, and sometimes the command that was executed. In any case, the vehicle’s vehicle state capabilities tell you which properties are available for that particular vehicle, and as such can be part of the command response.

Example⚓︎

The following example shows how to send the unlock-central-lock command to a vehicle.

curl -X POST \
  'https://api.invers.com/vehicles/❰vehicle_id❱/commands/unlock-central-lock' \ # (1)!
  -H 'Authorization: Bearer ❰access_token❱' \ # (2)!
  -H 'Content-Type: application/json' -d ''

Just replace ❰vehicle_id❱ with the ID of the vehicle.
Don’t forget to add your valid access token.

If the request has been successful, a JSON object is returned along with HTTP status code 200. The response contains information about the current vehicle state.¹

Here is an example of what the response might look like:

response (json)

{
  "mileage_in_kilometers": {
    "timestamp": "2020-01-30T13:22:05.000Z",
    "value": 10000
  },
  "state_of_charge_or_fuel_level_in_percent": {
    "timestamp": "2020-01-30T13:22:05.000Z",
    "value": 85
  },
  "remaining_range_in_kilometers": {
    "timestamp": "2020-01-30T13:22:05.000Z",
    "value": 35
  },
  "position": {
    "timestamp": "2020-01-30T13:22:05.000Z",
    "value": {
      "lat": 50.834,
      "lon": 8.0219
    }
  },
  "cellular_signal_quality": {
    "timestamp": "2020-01-30T13:22:05.000Z",
    "value": 4
  },
  "driving_enabled": {
    "timestamp": "2020-01-30T13:22:05.000Z",
    "value": true
  },
  "central_lock": {
    "timestamp": "2020-01-30T13:22:05.000Z",
    "value": "UNLOCKED"
  }
}

Combined Commands⚓︎

Combined commands can be used to simultaneously send multiple commands to a vehicle. The following combined commands are currently available:

unlock-and-enable-driving can be used to simultaneously unlock a vehicle and enable driving (disable the immobilizer). If supported, the vehicle has the command capability UNLOCK_AND_ENABLE_DRIVING
lock-and-disable-driving can be used to simultaneously lock a vehicle and disable driving (enable the immobilizer). If supported, the vehicle has the command capability LOCK_AND_DISABLE_DRIVING

Not all telematics brands offer support for combined commands. However, all combined commands mentioned here are supported by the INVERS CloudBoxx.

Error handling and problem types⚓︎

Sending commands to a vehicle might not always work as expected, e.g., due to cellular connectivity issues or because the vehicle is in a conflicting state that does not allow the execution of a particular command. In such cases, the response contains information that helps you identify the cause of the problem and react accordingly. All error responses contain an error response body with problem type.

In addition to that, the following classification helps you to quickly understand whether the error is caused by:

your client’s request
a connectivity issue
an internal problem of the Vehicle Commands API
a third-party (OEM / third-party telematics provider) problem

Client errors⚓︎

Sometimes your application or implementation does something wrong. Mostly, these are programming mistakes.

These kind of errors will have an HTTP status code in the 4xx range.

Example

Command not supportedResource not found

{
  "type": "/problems/vehicle/command-not-supported",
  "type_documentation": "https://developers.invers.com/problems/vehicle/command-not-supported",
  "title": "The command is not supported by the vehicle.",
  "status": 409,
  "detail": "The command 'unlock central lock' is not supported by the vehicle 'P49FJK'.",
  "flow_id": "5e77e3e3-48ab-4955-8ab3-1c62339096ab"
}

{
  "type": "/problems/resource-not-found",
  "type_documentation": "https://developers.invers.com/problems/resource-not-found",
  "title": "The resource cannot be found.",
  "status": 404,
  "detail": "The vehicle with ID 'P49FJK' cannot be found.",
  "flow_id": "5e77e3e3-48ab-4955-8ab3-1c62339096ab"
}

Third-party error⚓︎

Problem types

Learn more about problem types in API Basics.

If the vehicle or the API of the telematics unit manufacturer returns an error, this results in problem type /problems/third-party/error and HTTP status code 502. This case applies to OEM and third-party telematics only, not the INVERS CloudBoxx.

If this occurs over a longer period of time, we recommend checking the status page or alert newsletter of the telematics manufacturer.

{
  "type": "/problems/third-party/error",
  "type_documentation": "https://developers.invers.com/problems/third-party/error",
  "title": "An error occurred at a third party API or protocol.",
  "status": 502,
  "detail": "An error occurred at the NIU API.",
  "flow_id": "5e77e3e3-48ab-4955-8ab3-1c62339096ab"
}

Connection error⚓︎

If the communication between the INVERS API and the telematics unit or the vehicle manufacturer’s API could not be established or a timeout occurred, problem type /problems/vehicle/no-connection will be returned along with HTTP status code 504.

{
  "type": "/problems/vehicle/no-connection",
  "type_documentation": "https://developers.invers.com/problems/vehicle/no-connection",
  "title": "No connection to vehicle",
  "status": 504,
  "detail": "The vehicle 'JQ7RP' did not establish a connection.",
  "flow_id": "5e77e3e3-48ab-4955-8ab3-1c62339096ab"
}

Internal error⚓︎

If an internal error happened within the INVERS API while processing the command, problem type /problems/internal-server-error will be returned along with HTTP status code 500.

In this case INVERS will automatically be notified about the problem and our development team will start investigating the issue. If such an error persists, you can of course contact support. Make sure to provide the flow_id of your request.

{
  "type": "/problems/internal-server-error",
  "type_documentation": "https://developers.invers.com/problems/internal-server-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "Internal Server Error",
  "flow_id": "5e77e3e3-48ab-4955-8ab3-1c62339096ab"
}

Depending on the vehicle and the installed telematics unit, the range of information returned in the response may vary. ↩