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.
| Field | Description |
Field status | Description The HTTP status codes. |
Field operationId | Description The id of the specific operation which can be used for fault tracing. |
Field data | Description Data returned by the specific endpoint. |
Example
{
"status": 0,
"operationId": "string",
"data": {}
}Status codes
All the status codes which the API can return are described below.
| Status code | Description |
Status code 200 OK | Description Indicates a successful request. |
Status code 202 Accepted | Description Indicates a successful request, but the processing has not been completed. |
Status code 204 No Content | Description Indicates a successful request, the response will not contain a body. |
Status code 400 Bad Request | Description 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. |
Status code 401 Unauthorized | Description Error code which usually indicates and error with either the VCC-API-key or Bearer token, check the error message for details. |
Status code 404 Not found | Description Error code which indicates that the resource could not be found, the description can contain a reason for the response. |
Status code 406 Not Acceptable | Description Error code which indicates that an invalid mediatype was sent in the Accept header. |
Status code 422 Unprocessable Entity | Description Error code which indicates that the update passes the validation rules defined in the Open API spec but fails against the internal business rules. |
Status code 500 Internal Server Error | Description Error Code which indicate that something went wrong when processing the request, check the error message for details. |
Status code 502 Bad Gateway | Description 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.
| Field | Description |
Field status | Description The HTTP status codes. |
Field operationId | Description The id of the specific operation which can be used for fault tracing. |
Field error.message | Description A message explaining the error. |
Field error.description | Description A more in detail description of the error. |
Field error.detail | Description 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
If the error message from the request body doesn't provide enough information for troubleshooting, you can contact us at developer.portal@volvocars.com.
Before contacting us, please include a UUID in the vcc-api-operationId header of the problematic API request. This will help us locate your requests in our systems. If a vcc-api-operationId is not provided in a request, a UUID will automatically be generated for the request.
The vcc-api-operationId header will also always be returned in the response as a header with the same name.
Example
-H 'vcc-api-operationId: <UUID>'