
Product API details
This page describes the Product API in more detail in addition to the technical API documentation.
Prerequisites
OAuth client
In order to use the Product API, consumers will need an OAuth client for the Catalog Management system, additionally to the subscription key. The OAuth client consists of a client id and a client secret, which is needed for the Token.Get endpoint which returns the access key for all subsequent requests.
Attribute list
Prior to using the API, a list of all necessary attributes must be compiled. This ensures that only those attributes which are needed for the consumer are exported. On the one hand this reduces the payload returned which has a significant impact on performance. On the other hand it is guarantees that sensitive data is not exposed.
Product structure
Wienerberger organizes its products in two different ways:
Commercial products (CPs)
Stock keeping units (SKUs)
Elements and Systems (E&S)
Commercial Products (CPs)
Commercial products are "virtual" products which represent an aggregation hierarchy, i.e. products which share the same property value like model name, color, etc. Such products can be grouped within commercial products. Depending on business needs those hierarchies are defined and exposed in a catalog as a product. A commercial product can hold one or more SKUs.
Commercial products reside on sales organization level.
Stock keeping unit (SKU)
SKUs are the material representation in the ERP system and can be attached to Commercial products. SKUs which are linked to CPs, can be added optionally to the payload from the endpoint CommercialProducts.Get without being explicitly added to the catalog. However, if SKUs are added to the catalog explicitly, the will also be part of the API response even if not reference by a CP.
SKUs reside on product plant level but have a sales organization dimension, which allows adding sales organization dependent data to an SKU (e.g. legal regulations).
Elements and Systems (E&S)
Elements and Systems provide data for combined entities, this could be SKUs or CPs.
E&S reside on sales organization level.
How to implement the API
In order to get started, it must be clarified which category (catalog) containing the CPs, SKUs or E&S should be used by the consumer. The endpoint CommercialProducts.Get returns all entities (CPs, SKUs, E&S) of this catalog independent of the product group. The endpoint is not designed for real-time requests, but to export data which must be persisted by the consumer application. The API endpoint CommercialProducts.Get offers a timestamp parameter, which allows to perform a "delta import" to only return newly created or updated entities since the provided timestamp.
A daily import routine has been proven to be the best approach to keep entity data up-to-date.
Furthermore a so-called "full import" from time to time keeps up with deleted products.
How to handle assets
Assets , in the sense of images, downloads, etc. are stored in the attribute "assetLinks". The "assetLinks" attribute is an array containing single asset objects.
[
{
"AEMguid": "b1428a19-xxxx-xxxx-xxxx-2d6c9bbc64a6",
"mainpic": false,
"optionalsecondpic": true,
"assettype": null
},
{
"AEMguid": "a9832313-xxxx-xxxx-xxxx-060a8b6c08f3",
"mainpic": false,
"optionalsecondpic": false,
"assettype": null
}
]
With the help of the assetprovider servlet, assets can be retrieved. For images and their renditions use the following path:
/services/assetprovider?rendition=web&size=#size#&uuid=#guid#
Replace #guid# with the value from the asset object "AEMguid"
Replace #size# if you want to retreive an image. For other assets you can omit this parameter
Following list shows the available values for the "size" parameter for images:
xl: width="1400" height="1050"
xl2: width="2800" height="2100"
xl3: width="4200" height="3150"
lg: width="1200" height="900"
lg2: width="2400" height="1800"
lg3ed: width="3600" height="2700"
md: width="992" height="1319"
md2: width="1984" height="2638"
md3: width="2976" height="3957"
sm: width="768" height="1024"
sm2: width="1536" height="2048"
sm3: width="2304" height="3072"
xs: width="576" height="854"
xs2: width="1152" height="1708"
xs3: width="1728" height="2562"
To retrieve the original file of any asset, use the following path:
/services/assetprovider?rendition=original&uuid=#guid#
How to retrieve Product Detail Page URL
The "Product Detail" - Service provides the Product Detail Page URL for a given Product ID and an optional locale parameter. The parameter "locale" only needs to be present for multi-language websites. For single-language website the parameter "locale" can be omitted.
/services/productdetail?productID=%PRODUCT_ID%&locale=%locale%
A full URL would look like the following one
https://www.wienerberger.be/services/productdetail?productID=676384&locale=fr-BE
Known Issues
Incorrect values for "totalPageCount" and "totalProductCount" when using parameter "timestamp" in "Get.CommercialProducts"
When getting product data via endpoint "Get.CommercialProducts" the values for "totalPageCount" and "totalProductCount" returned in the payload are incorrect when using the timestamp parameter. The "totalPageCount" value is always set to 1 and the "totalProductCount" is always set to the "pageSize" parameter.
As a workaround, please increment the "currentPage" parameter until the value "totalProductCount" > "pageSize", where "totalProductCount" is the value in the payload and "pageSize" is the parameter in the request