Volvo ⛟ OEM API

Volvo OEM API v1.0.3

Overview and purpose of the API

• The Volvo OEM API is a REST facade consumed by a new DMS platform.
• It is backed by Mule GraphQL (notably GeneralInformationByProductInfoId) and related services.
• This version exposes retrieval of a single vehicle record from master data by lookup keys.
• The response is wrapped in an envelope that may gain additional top-level objects as more OEM services are integrated.

Authentication and security requirements

• Security scheme: MuleSoft Client ID Enforcement (Pass Through).
• Clients must provide the following headers on every request:
  • client_id: string
  • client_secret: string
• Possible security-related responses:
  • 401 Unauthorized: Unauthorized or invalid client application credentials.
  • 403 Forbidden: Bad response from authorization server or policy denial.

Base URL and supported environments

• Base URI: https://{apiHost}/v1/oem
• Base URI parameter:
  • apiHost
    • default: flex-9sqczt.ff5vu7.deu-c1.cloudhub.io
• Example base URL (default environment): https://flex-9sqczt.ff5vu7.deu-c1.cloudhub.io/v1/oem

Endpoint documentation

Get one vehicle

• Operation: getVehicle
• HTTP method and path: GET /vehicle
• Summary: Get one vehicle
• Description:
  • Returns exactly one master-data vehicle matching provided lookup keys.
  • The three query parameters map to the GraphQL input search: ProductInfoSearchInput.
  • The implementation selects the single matching record from GeneralInformationByProductInfoId (e.g., the first match if the graph layer returns a list).
• Security: Secured by Client ID Enforcement (client_id and client_secret headers).

Query parameters

• chassisSeries (optional, string)
  • Description: Vehicle chassis series (maps to search.chassisSeries).
• chassisNumber (optional, number, int32)
  • Description: Chassis number lookup (maps to search.chassisNumber).
• registrationNumber (optional, string)
  • Description: Registration / license identifier (maps to search.registrationNumber).

Notes:
- The specification states a 400 may be returned for invalid combinations of lookup parameters. It does not mandate which combinations are valid; clients should provide parameters consistent with their lookup use case.

Request headers

• Required:
  • client_id: string
  • client_secret: string
• Recommended:
  • Accept: application/json

Responses

• 200 OK
  • Description: The matching vehicle; envelope may gain additional typed properties later.
  • Content-Type: application/json
  • Schema: OemPlatformVehicleEnvelope
    • vehicle: Vehicle
      • registrationNumber?: string
      • chassisSeries?: string
      • chassisNumber?: string (note: returned as string; differs from the query parameter type)
      • vin?: string
      • productCode?: string
      • customerNumber?: string
      • model?: string
      • engine?: string
      • gearbox?: string
      • rearAxle?: string
      • axle?: string
      • impoVVerNumber?: string
      • retailDate?: string
      • usedLastSalesDate?: string | null
      • electric?: string | null
      • modelYear?: string
      • fleetNumber?: string
      • dateOfLastVisit?: string
      • mileageAtLastVisit?: string
      • branchNumber?: string
      • scheduleBranch?: string
      • fromMasterData?: string | null
      • createdInDmsNotSyncWithMd?: string | null
• 400 Bad Request
  • Description: Bad request — invalid combination of lookup parameters.
• 401 Unauthorized
  • Description: Unauthorized or invalid client application credentials (Client ID enforcement).
  • Content-Type: application/json
  • Schema: UnauthorizedErrorBody
    • error?: string (example: "Invalid Client")
• 403 Forbidden
  • Description: Forbidden — bad response from authorization server or policy denial.
• 404 Not Found
  • Description: Instance not found — no vehicle exists for the given lookup keys.
  • Content-Type: application/json
  • Schema: InstanceNotFoundErrorBody
    • error?: string (example: "Instance not found")
• 500 Internal Server Error
  • Description: Internal server error or bad response from authorization server.

Example request (cURL)

• Example using default host and all query parameters:

curl -X GET "https://flex-9sqczt.ff5vu7.deu-c1.cloudhub.io/v1/oem/vehicle?chassisSeries=R&chassisNumber=859720&registrationNumber=PTB-076" \
  -H "Accept: application/json" \
  -H "client_id: {client_id}" \
  -H "client_secret: {client_secret}"

• Example using only registrationNumber:

curl -X GET "https://flex-9sqczt.ff5vu7.deu-c1.cloudhub.io/v1/oem/vehicle?registrationNumber=PTB-076" \
  -H "Accept: application/json" \
  -H "client_id: {client_id}" \
  -H "client_secret: {client_secret}"

Example 200 response (application/json)

{
  "vehicle": {
    "registrationNumber": "PTB-076",
    "chassisSeries": "R",
    "chassisNumber": "859720",
    "vin": "CC2VVY0A3JB859715",
    "productCode": "VOLVO",
    "customerNumber": "20740",
    "model": "FH (4)",
    "engine": "D13K460",
    "gearbox": "AT2612F",
    "rearAxle": "RSS1144A",
    "axle": "4X2",
    "impoVVerNumber": "2555",
    "retailDate": "2018-05-11 00:00:00",
    "usedLastSalesDate": null,
    "electric": null,
    "modelYear": "2018",
    "fleetNumber": "1976",
    "dateOfLastVisit": "2018-11-13 00:00:00",
    "mileageAtLastVisit": "30315",
    "branchNumber": "1",
    "scheduleBranch": "1",
    "fromMasterData": null,
    "createdInDmsNotSyncWithMd": null
  }
}

Example 404 response (application/json)

{
  "error": "Instance not found"
}

Example 401 response (application/json)

{
  "error": "Invalid Client"
}

Error handling and status codes

• 200 OK: Successful lookup. Body conforms to OemPlatformVehicleEnvelope.
• 400 Bad Request: The provided query parameters are invalid in combination.
• 401 Unauthorized: Missing or invalid client_id/client_secret.
• 403 Forbidden: Authorization server issues or policy denial.
• 404 Not Found: No vehicle matched the lookup keys.
• 500 Internal Server Error: Unexpected error or downstream authorization server error.

Notes:
- Error bodies are defined for 401 and 404. Other error responses may not include a body per the spec.

Best practices for implementation

• Always include client_id and client_secret headers.
• Provide at least one lookup parameter. While the spec does not mandate specific combinations, supplying more precise keys (e.g., both chassisSeries and chassisNumber) can reduce ambiguity.
• Observe data type nuances:
  • Query parameter chassisNumber is an int32 number; the returned vehicle.chassisNumber is a string.
• Handle nullable fields gracefully (e.g., usedLastSalesDate, electric, fromMasterData, createdInDmsNotSyncWithMd may be null).
• Use the Accept: application/json header.
• Implement robust handling for 400/401/403/404/500 responses.
• Do not rely on additional envelope properties; the response may expand in the future, but only vehicle is defined in this version.

Sample code snippets

Bash (cURL) — successful lookup

curl -X GET "https://flex-9sqczt.ff5vu7.deu-c1.cloudhub.io/v1/oem/vehicle?chassisSeries=R&chassisNumber=859720" \
  -H "Accept: application/json" \
  -H "client_id: {client_id}" \
  -H "client_secret: {client_secret}"

Bash (cURL) — handle not found

set -e
resp=$(curl -s -o /tmp/body.json -w "%{http_code}" \
  -X GET "https://flex-9sqczt.ff5vu7.deu-c1.cloudhub.io/v1/oem/vehicle?registrationNumber=UNKNOWN-999" \
  -H "Accept: application/json" \
  -H "client_id: {client_id}" \
  -H "client_secret: {client_secret}")

if [ "$resp" -eq 200 ]; then
  cat /tmp/body.json
elif [ "$resp" -eq 404 ]; then
  echo "Vehicle not found:"
  cat /tmp/body.json
else
  echo "Request failed with HTTP $resp"
  cat /tmp/body.json
fi

JavaScript (fetch) — basic call

async function getVehicleByReg(registrationNumber) {
  const baseUrl = "https://flex-9sqczt.ff5vu7.deu-c1.cloudhub.io/v1/oem";
  const url = `${baseUrl}/vehicle?registrationNumber=${encodeURIComponent(registrationNumber)}`;
  const res = await fetch(url, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "client_id": "{client_id}",
      "client_secret": "{client_secret}"
    }
  });

  if (res.status === 200) {
    return res.json();
  }
  if (res.status === 404) {
    const body = await res.json();
    throw new Error(body.error || "Instance not found");
  }
  throw new Error(`Request failed: ${res.status}`);
}

Python (requests) — chassis lookup

import requests

base = "https://flex-9sqczt.ff5vu7.deu-c1.cloudhub.io/v1/oem"
params = {"chassisSeries": "R", "chassisNumber": 859720}
headers = {"Accept": "application/json", "client_id": "{client_id}", "client_secret": "{client_secret}"}

r = requests.get(f"{base}/vehicle", params=params, headers=headers, timeout=20)

if r.status_code == 200:
    print(r.json())
elif r.status_code == 404:
    print(r.json())
else:
    r.raise_for_status()