APIs/Energy API
APIs/Energy API

Details

Application

To use this API, you must first create an application. When your application is created, you will receive a VCC API key. This key must be included in the header of each request sent to the API.

Visit your account page to create or view applications.

Example

-H 'vcc-api-key: <your-vcc-api-key>'

Authorisation

This API implements the OAuth2 framework. An access token must be included in the header of each request sent to the API.

Visit the authorisation page for more information.

Example

-H 'authorization: Bearer <your-access-token>'

Common response model

Most of the responses from the API will have a common response body regardless of which endpoint is called, for successful (except 204) responses the response body will contain a data field which contains the information exposed by the endpoint. Each endpoint contains different datasets hence the format of the data field will change.

FieldDescription
status
The HTTP status codes.
operationId
The id of the specific operation which can be used for fault tracing.
data
The data contains the dataset which the specific endpoint serves.

Example

{
  "status": 0,
  "operationId": "string",
  "data": {}
}

Status codes

All the status codes which the API can return are described below.

Status codeDescription
200 OK
Indicates a successful request.
202 Accepted
Indicates a successful request, but the processing has not been completed.
204 No Content
Indicates a successful request, the response will not contain a body.
400 Bad Request
Error code which indicates that the update did not pass the validation rules defined in the Open API spec or an invalid json payload was sent.
401 Unauthorized
Error code which usually indicates and error with either the VCC-API-key or Bearer token, check the error message for details.
406 Not Acceptable
Error code which indicates that an invalid mediatype was sent in the Accept header.
422 Unprocessable Entity
Error code which indicates that the update passes the validation rules defined in the Open API spec but fails against the internal business rules.
500 Internal Server Error
Error Code which indicate that something went wrong when processing the request, check the error message for details.
502 Bad Gateway
Error Code which indicate that something went wrong when calling the API.

Error handling

Sometimes things go wrong, in such cases the API will in addition to the error code return a message body containing information about the error. The message body has a base structure which will be the same regardless of the error. It can also contain a dynamic detail field with specific data for the particular HTTP status code and endpoint.

FieldDescription
status
The HTTP status codes.
operationId
The id of the specific operation which can be used for fault tracing.
error.message
A message explaining the error.
error.description
A more in detail description of the error.
error.detail
An object describing in detail what exactly went wrong, the format of the details object can differ between the endpoint and error codes.

Example

{
  "status": 0,
  "operationId": "string",
  "error": {
    "message": "string",
    "description": "string",
    "detail": "object"
  }
}

Debugging errors

In case the request error message does not help you resolve the issue, you can report it to developer.portal@volvocars.com. You can include a GUID in the vcc-api-operationId header of each request towards the API. This will make it easier for us to find your requests in our logs in cases where deeper analysis is needed.

Example

-H 'vcc-api-operationId: <GUID>'

Details/Application