| API Version | 1.2.0 |
| Date | 2026-05-26 |
This document describes how to integrate a product catalog or configurator into pCon.basket. External catalogs are embedded using an HTML IFrame. Thus a public HTTPS URL for the catalog has to be provided.
The communication between pCon.basket and the catalog is done using postMessage. More information can be found here: Window.postMessage()
The basic sequence for the catalog integration looks like this:
For an external catalog to be visible in pCon.basket, it must be registered. This can be done as part of the OFML data registration. Please follow the DSR specification for further information. If you are integrating pCon.basket it is also possible to register catalogs using the integration API.
Catalogs which are specified in DSR have to provide a logo image. This image has to be a JPEG with the name catalog-logo.jpg that is hosted in the root folder of the catalog website.
For example the image URL for the catalogs https://www.example.com and https://www.example.com/my-catalog.html
will be https://www.example.com/catalog-logo.jpg.
If you are using the integration API to register the catalog you may specify a custom logo URL. Please check the Integration Example for an example.
pCon.basket will send messages to the catalog by calling postMessage on the iframe's contentWindow. To send a message to the basket, postMessage has to be called on the parent window of the catalog.
The actual message and its parameters are stored in the data of the message event. Every message data has the following structure:
interface MessageData
{
/** message identifier */
type: string;
/** optional parameter of the message */
parameter?: string | object;
}
To initialize the product catalog/configurator with the correct language, currency and other settings the catalog has to request the catalog parameters upon startup. This is done using the wbk.externalCatalog.getCatalogParameters message. The basket will respond with a wbk.externalCatalog.catalogParameters message. The parameter of the received message has the following structure:
interface CatalogParameters
{
/** preferred locale for the external catalog UI */
locale: string;
/** preferred currency for article prices */
currency: string;
/** preferred language for article data in order of priority */
language: Array<string>;
/** currently active tax scheme */
taxScheme: TaxScheme;
/** active color scheme of the basket */
theme: Theme;
}
///// subtypes /////
interface TaxScheme
{
id: string;
country: string;
region: string;
taxTypes: Array<TaxType>;
}
interface TaxType
{
id: string;
rateUnit: string;
taxCategories: Array<TaxCategory>;
}
interface TaxCategory
{
id: string;
rate?: number;
}
interface Theme
{
primaryColor: string;
textColor: string;
fontFamily: string;
}
The following JavaScript code snippet demonstrates how the catalog parameters can be requested:
//register event handler for incoming messages
window.addEventListener("message", onMessage);
//request catalog parameters
window.parent.postMessage({ type: "wbk.externalCatalog.getCatalogParameters" }, "*");
//function which handles all incoming messages
function onMessage(pEvent) {
if (pEvent.data.type === "wbk.externalCatalog.catalogParameters") {
//... process the catalog parameters here
console.dir(pEvent.data.parameter);
}
}
When the user is finished selecting or configuring the articles in the catalog the selected articles have to be sent to the basket. This is done using the wbk.externalCatalog.insertArticles message. The message expects an array of articles as parameter. pCon.basket supports 3 kinds of articles, Custom, Ofml and File.
Custom articles are user defined articles and usually do not exist in any OFML catalog. The data structure of a custom article looks like this:
interface CustomArticle
{
type: "Custom";
manufacturerId?: string;
seriesId?: string;
baseArticleNumber?: string;
finalArticleNumber?: string;
variantCode?: string;
/**
* Quantity of the article
* @defaultValue 1
*/
quantity?: number;
/** short text as simple string or as multi language map (language code -> text) */
shortText?: string | { [language: string]: string };
/** long text as simple string or as multi language map (language code -> text) */
longText?: string | { [language: string]: string };
/** feature text as simple string or as multi language map (language code -> text) */
featureText?: string | { [language: string]: string };
/** Additional comments/notes for this article. */
comments?: string;
purchasePrice?: Money;
salesPrice?: Money;
packagingInfo?: PackagingInfo;
/** Map from tax type to tax category for the active tax scheme. */
taxes?: { [type: string]: string };
/**
* Url or data-URI for the article image.
* Currently only jpg and png images are supported.
*/
imageUrl?: string;
}
///// subtypes /////
interface Money
{
value: number;
currency: string;
}
interface Value
{
value: number;
unit: string;
}
interface PackagingInfo
{
width?: Value;
height?: Value;
depth?: Value;
volume?: Value;
tareWeight?: Value;
netWeight?: Value;
itemsPerPackUnit?: number;
packUnitsPerArticle?: number;
}
OFML articles are predefined articles which can only be inserted if the user has access to the corresponding OFML catalog. The data structure of an OFML article looks like this:
interface OfmlArticle
{
type: "Ofml";
manufacturerId: string;
seriesId: string;
baseArticleNumber: string;
variantCode?: string;
ofmlVariantCode?: string;
/**
* Quantity of the article
* @defaultValue 1
*/
quantity?: number;
}
By using the type File it is possible to insert articles using an external file. Currently the file types OBX, OBK and PEC are supported. For each file a publicly available url (CORS has to be allowed) has to be provided. The data structure of a file looks like this:
interface File
{
type: "File";
fileType: "OBX" | "OBK" | "PEC";
fileUrl: string;
}
The following JavaScript code snippet demonstrates how to send 3 different articles to the basket:
window.parent.postMessage({
type: "wbk.externalCatalog.insertArticles",
parameter: [
{
type: "Custom",
manufacturerId: "TEST",
seriesId: "OFFICE",
baseArticleNumber: "office-chair",
shortText: "Office Chair",
salesPrice: { value: 100, currency: "EUR" }
},
{
type: "Ofml",
manufacturerId: "EGROFFICE",
seriesId: "OFFICE2",
baseArticleNumber: "4500"
},
{
type: "File",
fileType: "OBK",
fileUrl: "https://www.example.com/example.obk"
}
]
}, "*");
Version 1.2.0
OBX, OBK and PEC filesVersion 1.1.0
quantity field to OFML articlesVersion 1.0.0
© EasternGraphics GmbH | Albert-Einstein-Straße 1 | 98693 Ilmenau | GERMANY
This work (whether as text, file, book or in other form) is copyright. All rights are reserved by
EasternGraphics GmbH. Translation, reproduction or distribution of the whole or parts thereof is permitted only with the prior agreement in writing of EasternGraphics GmbH.
EasternGraphics GmbH accepts no liability for the completeness, freedom from errors, topicality or continuity of this work or for its suitability to the intended purposes of the user. All liability except in the case of malicious intent, gross negligence or harm to life and limb is excluded.
All names or descriptions contained in this work may be the trademarks of the relevant copyright owner and as such legally protected. The fact that such trademarks appear in this work entitles no-one to assume that they are for the free use of all and sundry.