Overview¶

Services Overview¶

The services are split into 4 logical components covering the areas:

Entities (e.g. vehicles/cycles)
Products (basic product information)
Applications (linkgae between products and entities)
System (background information)

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

All body and response messages are 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 HMS 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 (OAuth2.0) to be generated and used in the authentication header on all method calls.

Each method includes a base request class.

"baseRequest":{
        "requestReference":123456,
        "requestPostedTime":"2019-05-23T18:12:43.511Z",
        "system":"ecat"
    }

you should use 'ecat' as the system identifier

Each method will return a base response class.

"baseResponse": {
    "baseRequest": {
      "requestReference": 123456,
      "requestPostedTime": "2019-05-23T18:12:43.511Z",
      "system": "ecat"
    },
    "responseTime": "00:00:00.0082905",
    "resultCode": 0,
    "resultText": "success"
  }

It includes the original base request and adds result information including how long it took the method to retrieve the data. This time will not include transferring the resultant json to your consuming system.

Best Practices¶

The HMS API reflects data held in XChecker and our SAP-PIM data store, as such, any questions on data integrity should be addressed to the PST or to the support team in the supplying system. We make every effort to ensure the validity of the data passed through the API but can not guarantee that data issues won't adversly affect the consuming systems.

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 entities relate to each other across the different sources (indexes).

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 entity on that index.

Xchecker Categories¶

For background information only

Categories in Xchecker are the highest level of product grouping. 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.

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.

Various methods may return these fields but they are no longer used as input filter or selection parameters; the functionality has been replaced with 'external nodes' which are product grouping identifiers supplied to Xchecker by PIM.

External Nodes¶

Product grouping for Halfords is controlled by PIM under different hierarchy groups. Each level of the hierarchy is assigned a leaf node identifier - an external node in Xchecker - and is passed to our SAP-PIM database to associate with Xchecker parts. The API is constructed to allow product selection via these external nodes.

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 and links to. Internal to Xchecker, Part numbers are unique at a PartNumber/Brand level. Many parts are held in Xchecker as external links to the data held in the SAP-PIM database, referenced by the SAP Article ID.

Applications¶

Applications refer to the linkage between a product and a vehicle and contain linkage specific details such as fitting position and applicable dates.