How-to Guide - Rest API - Products

Introduction

The purpose of this guide is to provide an understanding of the REST Products APIs provided by Enactor for use with external Web Sites and for Customer integration. It is separated out into functional areas, with each section related to a specific service. Note that the final URL used to access the service will be determined based on how the Enactor REST Products API is deployed.

Following are Enactor REST Products APIs areas covered in this document:

Product Catalogue API
External Product API

Product Catalog API

Get Product Details

This service when given a product ID will return details about that product, including descriptions, sizes, stock levels and prices. This will return a new entity 'IProductDetail' which includes all the details requested.

To support location-based pricing, it is possible to include the location ID in the request, e.g. /products/500100?locationId=0001

Adding the location ID means the service will calculate and return the price effective at that location (based on location and/or group-level price data).

Request

Request Service URL

GET /products/{productId}

Request Tokens

productId: The ID of the product to retrieve details of.

Request Parameters

retrieveSkuProducts: Boolean. If true, the related sku products will be returned - Defaults to false. Eg: retrieveSkuProducts=true
locationId: Boolean. If true, the service will calculate and return the price effective at that location (based on location and/or group-level price data). Eg: locationId=true

Request Body

There is no request body.

Response

Response Headers

There are no response headers.

Response Body

GetProductDetailResponse

Element	Type	Description
productDetails	IProductDetail	The details of the specified product.

Request & Response Examples

Request:

GET: http://[SWARM_LEADER_IP]/WebRestApi/rest/products/500100

Response:

Status: 200 OK

{
  "productDetail": {
    "description": "JVC LT-40CA890 Android TV 40\" ",
    "longDescription": "JVC LT-40CA890 Android TV 40\" Smart 4K Ultra HD HDR LED TV",
    "price": 29900,
    "productId": "500100",
    "productMediaSet": {
      "productId": "500100",
      "productMediaSetItems": [
        {
          "productMediaId": "l_500100_002",
          "mediaType": "LARGE",
          "mediaURL": "image://PRODUCT/l_500100_002.jpg"
        },
        {
          "productMediaId": "l_500100_003",
          "mediaType": "LARGE",
          "mediaURL": "image://PRODUCT/l_500100_003.jpg"
        },
        {
          "productMediaId": "l_500100_005",
          "mediaType": "LARGE",
          "mediaURL": "image://PRODUCT/l_500100_005.jpg"
        },
        {
          "productMediaId": "l_500100",
          "mediaType": "MAIN_LARGE",
          "mediaURL": "image://PRODUCT/u_500100.jpg"
        },
        {
          "productMediaId": "m_500100",
          "mediaType": "MAIN_THUMB",
          "mediaURL": "image://PRODUCT/m_500100.jpg"
        },
        {
          "productMediaId": "m_500100_002",
          "mediaType": "THUMB",
          "mediaURL": "image://PRODUCT/m_500100_002.jpg"
        },
        {
          "productMediaId": "m_500100_003",
          "mediaType": "THUMB",
          "mediaURL": "image://PRODUCT/m_500100_002.jpg"
        },
        {
          "productMediaId": "m_500100_005",
          "mediaType": "THUMB",
          "mediaURL": "image://PRODUCT/m_500100_005.jpg"
        }
      ]
    },
    "productExtendedInformation": {
      "productId": "500100",
      "informationText": "* Picture quality: 50 Hz\n* HDR: HDR10\n* Catch-up TV & 4K streaming\n* Freeview HD with Freeview Play\n* HDMI 2.0b x 4"
    },
    "productImageURL": "image://PRODUCT/u_500100.jpg",
    "mmGroupKey": {
      "groupTypeId": "mmGroup",
      "groupHierarchyId": "RETAIL",
      "variantGroupTypeId": "region",
      "variantGroupId": "All",
      "variantGroupHierarchyId": "All",
      "groupId": "TV",
      "id": "TV"
    },
    "type": "merchandiseProduct",
    "status": "LIVE",
    "mMGroup": {
      "allowPriceEntry": false,
      "concession": false,
      "forceMessageAcknowledgement": false,
      "operatorMessage": {},
      "quantityEntry": false,
      "receiptMessage": {},
      "fasciaId": {
        "groupTypeId": "fascia"
      },
      "groupId": "TV",
      "groupTypeId": "mmGroup",
      "groupHierarchyId": "RETAIL",
      "level": 3,
      "level1GroupId": "RETAIL",
      "level2GroupId": "ELECTRONICS",
      "level3GroupId": "TV",
      "localisedName": {
        "string": [
          {
            "country": "GB",
            "language": "en",
            "string": "Televisions"
          }
        ]
      },
      "variantGroupId": "All",
      "variantGroupTypeId": "region",
      "variantGroupHierarchyId": "All",
      "variantLevel": 1,
      "lastUpdated": 1703180395003,
      "name": "Televisions"
    }
  }
}

Search the Product Catalogue (Solr)

This service provides the ability to list products by passing in a Solr query as a parameter. The service responds with a SearchProductCatalogueResponse which includes and contains a list of ProductDetails, facet field counts and the count of results found.

Request

Request Service URL

GET /products?q={solr_query}

Request Tokens

solr_query: String. The Solr query that is to be run for searching the product catalogue.

Request Parameters

There are no request parameters.

Request Body

There is no request body.

Response

Response Headers

There are no response headers.

Response Body

SearchProductCatalogueResponse

Element	Type	Description
productDetails	List<IProductDetail>	The list of products along with their details.
count	Long	The number of results found.

Request & Response Examples

Request:

GET:
http://[SWARM_LEADER_IP]/WebRestApi/rest/products?q=productLongDescription:tv&rows=5

Response:

Status: 200 OK

{
  "productDetails": [
    {
      "description": "JVC LT-40CA890 Android TV 40\"",
      "longDescription": "JVC LT-40CA890 Android TV 40\" Smart 4K Ultra HD HDR LED TV",
      "productId": "500100",
      "productImageURL": "image://PRODUCT/u_500100.jpg",
      "mmGroupKey": {
        "groupHierarchyId": "RETAIL",
        "groupId": "TV",
        "id": "TV"
      },
      "type": "merchandiseProduct",
      "status": "LIVE"
    },
    {
      "description": "JVC LT-40CA890 Android TV 40\" HJ",
      "longDescription": "JVC LT-40CA890 Android TV 40\" Smart 4K Ultra HD HDR LED TV",
      "productId": "500100HJ",
      "productImageURL": "image://PRODUCT/u_500100.jpg",
      "mmGroupKey": {
        "groupHierarchyId": "RETAIL",
        "groupId": "HADHI",
        "id": "HADHI"
      },
      "type": "merchandiseProduct",
      "status": "LIVE"
    },
    {
      "description": "JVC LT-55CF890 Fire TV Edition with Price Prompt",
      "longDescription": "JVC LT-55CF890 Fire TV Edition 55\" Smart 4K Ultra HD HDR LED TV with Amazon Alexa",
      "productId": "500101HJ",
      "productImageURL": "image://PRODUCT/u_500101.jpg",
      "mmGroupKey": {
        "groupHierarchyId": "RETAIL",
        "groupId": "TV",
        "id": "TV"
      },
      "type": "merchandiseProduct",
      "status": "LIVE"
    },
    {
      "description": "JVC LT-55CF890 Fire TV Edition",
      "longDescription": "JVC LT-55CF890 Fire TV Edition 55\" Smart 4K Ultra HD HDR LED TV with Amazon Alexa",
      "productId": "500101",
      "productImageURL": "image://PRODUCT/u_500101.jpg",
      "mmGroupKey": {
        "groupHierarchyId": "RETAIL",
        "groupId": "TV",
        "id": "TV"
      },
      "type": "merchandiseProduct",
      "status": "LIVE"
    },
    {
      "description": "SAMSUNG UE50TU7020KXXU 50\"",
      "longDescription": "SAMSUNG UE50TU7020KXXU 50\" Smart 4K Ultra HD HDR LED TV",
      "productId": "500102",
      "productImageURL": "image://PRODUCT/u_500102.jpg",
      "mmGroupKey": {
        "groupHierarchyId": "RETAIL",
        "groupId": "TV",
        "id": "TV"
      },
      "type": "merchandiseProduct",
      "status": "LIVE"
    }
  ],
  "count": 7
}

Search the Product Catalogue

This service provides the ability to list products with a variety of selection criteria. The service will return ISearchProductCatalogueResponse, which contains a list of ProductDetails. When brief query parameter is set to true, the service will return ISearchProductCatalogueBriefResponse with a list of the matching product IDs and descriptions.

The pageSize and pageOffset fields can be used to control how many matches are returned. Note that the service will not support a pageSize greater than 100. Unless otherwise stated any request criterion that are not supplied should not restrict the returned results. For example, if minPrice is not supplied but maxPrice is, then all products with a price below or equal to the maxPrice should be returned.

Request

Request Service URL

POST /products

Request Tokens

There are no request tokens.

Request Parameters

brief: Boolean. If truem the service will only return a list of product IDs and descriptions - Defaults to false. Eg: brief=true

Request Body

ISearchProductCatalogueRequest

Element	Required / Optional	Type	Description
searchLocationId	Required	String	Location for which the product search is to be requested.
description	Optional	String	Match on the product description.
descriptionFuzzy	Optional	Boolean	If true the description should be a fuzzy match, otherwise it should be a simple 'contains' match - Defaults to true.
minPrice	Optional	Long	Match on products which have a price greater than or equal to this value.
maxPrice	Optional	Long	Match on products which have a price less than or equal to this value.
colour	Optional	String	Match on products which have this colour.
style	Optional	String	Match on products which have this style.
size	Optional	String	Match on products which have this size.
mmg	Optional	String	Match on products which are part of this MMG, or are in an MMG which is a decendent of this MMG.
inStock	Optional	Boolean	If true, only match products which are in-stock. If false, return products which are in or out-of-stock - Defaults to false.
pageSize	Optional	Integer	The maximum number of matches to return on a single page - Defaults to 20, limited to 100.
pageOffset	Optional	Integer	The offset of the first match to return - Defaults to 0.

Response

Response Headers

There are no response headers.

Response Body

SearchProductCatalogueResponse

Element	Type	Description
productDetails	List<IProductDetail>	The list of products along with their details.
count	Long	The number of results found.

Request & Response Examples

Request:

POST http://[SWARM_LEADER_IP]/WebRestApi/rest/products

{
  "@entity": "retail:searchProductCatalogueRequest",
  "excludePriceRange": false,
  "includedProductTypes": [],
  "orIdAndDescription": false,
  "description": "TV",
  "searchLocationId": "0001"
}

Response:

Status: 200 OK XXX

{
  "productDetails": [
    {
      "description": "JVC LT-40CA890 Android TV 40\"",
      "longDescription": "JVC LT-40CA890 Android TV 40\" Smart 4K Ultra HD HDR LED TV",
      "price": 0,
      "productId": "500100",
      "productImageURL": "image://PRODUCT/u_500100.jpg"
    },
    {
      "description": "JVC LT-40CA890 Android TV 40\" HJ",
      "longDescription": "JVC LT-40CA890 Android TV 40\" Smart 4K Ultra HD HDR LED TV",
      "price": 0,
      "productId": "500100HJ",
      "productImageURL": "image://PRODUCT/u_500100.jpg"
    },
    {
      "description": "JVC LT-55CF890 Fire TV Edition",
      "longDescription": "JVC LT-55CF890 Fire TV Edition 55\" Smart 4K Ultra HD HDR LED TV with Amazon Alexa",
      "price": 0,
      "productId": "500101",
      "productImageURL": "image://PRODUCT/u_500101.jpg"
    },
    {
      "description": "JVC LT-55CF890 Fire TV Edition with Price Prompt",
      "longDescription": "JVC LT-55CF890 Fire TV Edition 55\" Smart 4K Ultra HD HDR LED TV with Amazon Alexa",
      "price": 0,
      "productId": "500101HJ",
      "productImageURL": "image://PRODUCT/u_500101.jpg"
    }
  ]
}

Get Product Attributes

The Product Attributes API provides the ability to retrieve product attributes for a given product. The service also provides the ability to provide pagination details to limit and offset the list of product attributes.

Request

Request Service URL

GET /products/{productId}/attributes

Request Tokens

productId: The ID of the product to retrieve details of.

Request Parameters

limit: Integer. This will limit the number of product attributes to return. Eg: limit=20
offset: Integer. This will specify the number of rows to skip before starting to return the product attributes. Eg: offset=5

Request Body

There is no request body.

Response

Response Headers

There are no response headers.

Response Body

There is no response body.

Request & Response Examples

Request:

GET:
http://[SWARM_LEADER_IP]/WebRestApi/rest/products/500100/attributes

Response:

Status: 200 OK

{
  "productId": "500100",
  "pagination": {
    "@type": "offsetPagination",
    "offset": 0,
    "limit": 100,
    "resultCount": 2
  },
  "values": {
    "brand_option_path": "SAMSUNG",
    "stars_option_path": "5.0"
  }
}

External Product API

The External Product API provides the ability to retrieve specific details about a product that are external to the current system. This data is not considered sensitive; therefore, the access Token is not required. Following is the list of External Product APIs covered in this section:

Get the Product.
Get the Product Price.

Get the Product

This service behaves equivalently to the product lookup done locally by a POS. The service needs to send more than just the product ID, so it can also simulate the transaction held by the client. It is also why the service sends back the full product, since the POS will use that in functions that follow the product lookup.

The product details are equivalent to the details returned by the product catalogue service. They are included for completeness, but this service does not guarantee that it will have all the information that can be provided by the Product Catalogue service.

Request

Request Service URL

POST /products/lookup

Request Tokens

There are no request tokens.

Request Parameters

There are no request parameters.

Request Body

ProductLookupRequest

Element	Type	Description
productCode	String	The code entered for the product.
productCodeScanned	String	A product code scanned.
embeddedProductCode	String	A product code extracted from an embedded product price.
locationId	String	The ID of the location requesting the details
deviceId	String	The ID of the device that is requesting the details.
customerRetailDetails	customerRetailDetails	The transaction details about the customer.
flightDetailsItem	flightDetailsItem	Transaction details about a flight. Only relevant for airport sales.

Response

Response Headers

There are no response headers.

Response Body

ProductLookupResponse

Element	Type	Description
product	IProduct	The product that was requested.
productDetails	IProductDetail	The details of the requested product.

Request & Response Examples

Request:

POST http://[SWARM_LEADER_IP]/WebRestApi/rest/products/lookup

{
  "productCode": "EXTERNAL1",
  "locationId": "Store1",
  "deviceId": "pos1.store1.enactor",
  "terminalId": "pos1.store1.enactor",
  "transactionEntityQName": "{http://www.enactor.com/retail}normalRetailSaleTransaction",
  "customerRetailDetails": {
    "@type": "customerRetailDetails",
    "validatedOnline": false,
    "newCustomer": false,
    "marketingDetailsCaptured": false
  }
}

Response:

Status: 200 OK

{
  "productDetail": {
    "description": "External Product 1",
    "price": 0,
    "productId": "EXTERNAL1",
    "productMediaSet": {
      "productId": "EXTERNAL1"
    },
    "productExtendedInformation": {
      "productId": "EXTERNAL1"
    }
  },
  "product": {
    "productId": "EXTERNAL1",
    "type": "merchandiseProduct",
    "productDescription": {
      "string": [
        {
          "string": "External Product 1"
        }
      ]
    },
    "productLongDescription": {},
    "localisedProductInfo": {},
    "posDetails": {
      "productOptionSetDetails": {
        "isTemplate": false
      },
      "isTemplate": false
    },
    "isTemplate": false,
    "status": "LIVE",
    "lastUpdated": 1624962225551,
    "taxExemptProhibited": false,
    "exportDetails": {
      "isTemplate": false
    },
    "inventoryDetails": {
      "allowCustomerOrder": false,
      "customerOrderOnly": false,
      "isTemplate": false
    },
    "productDimensions": {
      "isTemplate": false
    },
    "warrantyDetails": {
      "localisedWarrantyInformation": {},
      "isTemplate": false
    },
    "standardCostPrice": 0.0,
    "standardMargin": 0.0,
    "fasciaId": {},
    "mmGroupId": {},
    "brandId": {},
    "rangeId": {},
    "seasonId": {}
  }
}

Get the Product Price

This service behaves equivalently to the price lookup done locally by a POS. The service needs to send more than just the product ID, so it can also simulate the transaction held by the client. It is also why the service sends back the full product, since the POS will use that in functions that follow the product lookup.

The product and the price lookups are handled separately by the POS, which is why they are provided as separate services.

Request

Request Service URL

POST /products/price/lookup

Request Tokens

There are no request tokens.

Request Parameters

There are no request parameters.

Request Body

PriceLookupRequest

Element	Type	Description
productId	String	The ID of the product to lookup the price for.
locationId	String	The ID of the location that is requesting the details.
deviceId	String	The ID of the device that is requesting the details.
customerRetailDetails	customerRetailDetails	The transaction details about the customer.
flightDetailsItem	flightDetailsItem	The transaction details about the flight. Only relevant for airport sales.

Response

Response Headers

There are no response headers.

Response Body

PriceLookupResponse

Element	Type	Description
price	Long	The value of the product’s price.
productPrice	IProductPrice	The price details of the specified product.

Request & Response Examples

Request:

POST http://[SWARM_LEADER_IP]/WebRestApi/rest/products/price/lookup

{
  "productId" : "EXTERNAL1",
  "priceType" : "R",
  "locationId" : "Store1",
  "deviceId" : "pos1.store1.enactor",
  "terminalId" : "pos1.store1.enactor",
  "transactionEntityQName" : "{http://www.enactor.com/retail}normalRetailSaleTransaction"
  "customerRetailDetails" : {
    "@type" : "customerRetailDetails",
    "validatedOnline" : false,
    "newCustomer" : false,
    "marketingDetailsCaptured" : false
  }
}

Response:

Status: 200 OK

{
  "price": 1000,
  "productPrice": {
    "productId": "EXTERNAL1",
    "locationId": {},
    "priceGroupId": {
      "groupTypeId": "priceGroup",
      "groupHierarchyId": "ALL",
      "variantGroupTypeId": "region",
      "variantGroupId": "All",
      "variantGroupHierarchyId": "All",
      "id": "UK"
    },
    "currencyId": {
      "id": "GBP"
    },
    "startDate": 1624921200000,
    "priceType": "R",
    "price": 1000,
    "roundingRuleId": {}
  }
}

Introduction​

Product Catalog API​

Get Product Details​

Request​

Response​

Request & Response Examples​

Search the Product Catalogue (Solr)​

Request​

Response​

Request & Response Examples​

Search the Product Catalogue​

Request​

Response​

Request & Response Examples​

Get Product Attributes​

Request​

Response​

Request & Response Examples​

External Product API​

Get the Product​

Request​

Response​

Request & Response Examples​

Get the Product Price​

Request​

Response​

Request & Response Examples​

Introduction

Product Catalog API

Get Product Details

Request

Response

Request & Response Examples

Search the Product Catalogue (Solr)

Request

Response

Request & Response Examples

Search the Product Catalogue

Request

Response

Request & Response Examples

Get Product Attributes

Request

Response

Request & Response Examples

External Product API

Get the Product

Request

Response

Request & Response Examples

Get the Product Price

Request

Response

Request & Response Examples