Overview¶

Please note that this API is intended for real-time access and not to batch build an eCat. If you need to batch build an eCat, please contact your Elcome representative for alternative options.

Services Overview¶

The services are split into 4 logical components covering the areas of entities (e.g. vehicles), parts, applications and system. Each of the components will be configured with a different base URL to allow maximum flexibility of current and future deployment. They are .NET Core 2 micro services that can run independently, can be containerised in Docker (and/or clustered using Docker Swarm mode or Kubernetes) or can be fronted (reverse proxied) by IIS. Currently we will be hosting them using IIS for convenience of administration.

Product assets (images) are dealt with in a separate API document which will be released when available.

All body and response messages will be in JSON format allowing for easy handling, test (Postman / Curl) and monitoring of requests. JSON is an industry standard and is well supported in C#, Java and JavaScript and has many free open source clients.

To help identify and track issues with the EMS API methods, each request must include a unique numeric identifier and a datetime. This information will be passed back as part of the response allowing you to easily identify any issues with the lifetime of the call. Security is handled by requiring a token to be generated in and used in the authentication header on all subsequent method calls.

Each method includes a base request class.

"baseRequest":{
        "requestReference":123456,
        "requestPostedTime":"2012-04-23T18:25:43.511Z",
        "system":"ecat"
    }

currently you should always use 'ecat' as the system identifier

To keep entity selection simpler the IDL vehicle identifier (internalReference) should be used in preference to any externalReference as it is a better unique identifier that Elcome generates.

Best Practices¶

The EMS API reflects data held in XChecker, as such any questions on data should be addressed in the XChecker tool. This will be most obviously apparent in areas such as Make or Model dropdowns where standardisation mat be required. XChecker also controls the availability of part numbers to the API, this is XChecker user maintainable functionality.

XChecker Terminology¶

Indexes and Entities¶

XChecker can be configured to hold many different lists of vehicle data (or generic entity data – an object that parts can be applicated to). Each list that comes from a separate source is called an index (sometimes referred to as vehicle index or entity index). The items in the lists are referred to as entities (or traditionally as vehicles, even though they may be engines, cycles etc).

Examples of different sources are TecDoc, MAM and CarWeb. Each of these companies supplies their vehicle data in a different format and often at different levels of detail. XChecker holds each of these separate sources in a configurable but standardised internal Elcome type format. Elcome also holds some information on how these vehicles relate to each other across the different sources.

When obtaining any data related to a vehicle (or entity) you must supply a reference to that index so that we can correctly select applications that are held against that vehicle on that index.

Categories¶

Categories are the highest level of product grouping in XChecker. Categories sit above ProductTypes (also referred to as Shortcodes). Categories can have one or many ProductTypes. Categories are referenced by text and by a unique numeric identifier. Most methods will return both and using the unique numeric identifier in requests is normally quicker as it saves a lookup.

ProductTypes or Shortcodes ProductTypes is the second and final level of product grouping in XChecker. Every ProductType must belong to a Category. ProductTypes are referenced by text and by a unique numeric identifier. Most methods will return both and using the unique numeric identifier in requests is normally quicker as it saves a lookup.

Brands¶

All products in XChecker (and therefore the IDL) must have a brand associated to them. Branding does not imply a product hierarchy (or product relationship such as parent-child). Brand can be used as a filter condition on many of the product request methods.

Products¶

Products are all the parts that XChecker holds. Parts must belong to a ProductType and must have a Brand. Part numbers are unique at a PartNumber/Brand/ProductType level.

Applications¶

Applications refer to the linkage between a product and a vehicle.

Constructing an eCat¶

Vehicle Selection¶

Operation: Populate a set of cascading drop down boxes to allow the user to select their vehicle.

The following methods can be used for this operation:

getEntityIndexes

Get information on what indexes are available and what fields they contain.
getPrimaryEntityValuesByCascadingPrimaries

Call this in the sequence of defined primary ordinals as detailed in the response from getEntityIndexes to get the cascading values for the users vehicle.
getPrimaryEntityValuesBySparsePrimaries (optional if the sequnce of selections is not the same as the primary ordinals)

Only use this method if you do not wish to get vehicle details in an sequential ordered manner.
getEntitiesByCascadingPrimaries

Once all the values have been selected via the cascading options, call this method to retrieve the full vehicle details of the selected vehicle(s). Note that it may return more than one vehicle so you should be prepared to show the user another more detailed screen to allow them to select their actual vehicle.

Available Product Types¶

Operation: Show available part types for this vehicle:

The following methods can be used for this operation:

getProductTypesByInternalEntityReference

Using the indexReference and internalReference returned by the call to getEntitiesByCascadingPrimaries call this method to return a list of productTypes and their categoryName.

Available Products¶

Operation: Show available products for a given Product Type.

Once you know the vehicle and the Product Type the user is interested in you can retrieve the product details using the following methods:

getAbbreviatedProductsByProductTypeReference

This method will return basic product details allowing for the user to select one to see full details using getProductsByProductReferences