|
Qixol Promo is designed for quick and complete integration from virtually any platform. Access to the Promo API services is via REST or WCF. If you are integrating from a platform authored in Microsoft .NET, there is also a .NET assembly available to further simplify the integration process (see section below.)
To fully understand the data that needs to be submitted to Promo, it is recommended that an evaluation company be created in Promo and a full review of the product be completed in order to ensure key concepts around basket, product and attribute management are understood.
Attributes
Before integrating with Promo, it is important to understand the role of attributes, in order to ensure that all required Product and Basket level attributes are defined, and Promo has the full range of values for those attributes. The attributes that will be defined for both Products and Baskets will be specific to the implementation.
Basket Attribute example: For an integration with a Point-of-Sale terminal, it may be necessary to provide a flag indicating whether the basket is submitted with a validated Staff identification number. To cope with this, a new Basket Attribute would be created in the Promo Portal, with values assigned to it of Yes and No (or other values as required - these values can also be managed using the Promo API). The attribute can then be utilized when creating promotions, by adding a Basket Level Criteria to the promotion, to indicate that it can only be applied when the value for this attribute received with baskets is set to Yes or No. All baskets submitted from the integrating Point-of-Sale terminal(s) would be expected to provide the attribute with baskets.
Product Attribute example: For an integration with a website, it may be necessary to provide details with each product on the category(s) within the website where the product is displayed. For example for a fashion website, this could include Shoes which are displayed in the Shoes category, but also in the Complete Outfits category. The new product attribute can optionally be created manually within the Promo Portal (or created automatically when importing products), where the values for that attribute are submitted with products when they are created or amended. Where a value is submitted for a product attribute that is not found, that attribute will be automatically created. Product attributes can be used when creating promotions to help with identifying products, by adding one or more Product Attribute Criteria to the promotion. When a product is included as a line in the basket, its attributes are retrieved and compared against the criteria defined for each available promotion to see if it should be applied.
Before integrating with Promo, it is important to ensure that supplied Product data has all required attributes that will be needed to restrict when a promotion should be applied, and that all required Basket Attributes and their values have been created.
Using the services
All interactions with Promo are managed within the context of a company. When you register with Promo, a company is created for you, within which all promotions and other product/attributes data resides. Each company is assigned a unique key (the Services Interaction Key), and this key must be provided with all interactions to the service APIs. When using the REST services, the company key must be included in the Url of the service method. If using WCF services the company key must be supplied in the XML request document.
All information passed to the Promo services must be encapsulated in JSON or XML complying with the defined schema. Where dates are passed these should be in Universal Time Coordinated (UTC). For both JSON and XML documents the date and time format must adhere to XML standards, as described by the w3schools article.
Each response returned from the Promo Services includes a summary section with a result indicating whether the request has failed validation or has encountered any problems during processing, and where available messages to help resolve any validation issues.
Currencies
Currency values within data submitted to Promo should never include a currency symbol, and should use a decimal point for the decimal mark. A maximum of two decimal places should be used for currency values.
For more information on how to manage multi-currency scenarios, see Currencies.
When to use the Services
It is recommended that the following areas of integration be managed using a periodic approach (for example as a nightly scheduled activity, or more frequently if required):
oProduct information - push to Import Services
oBasket attribute values - push to Import Services
oCampaign/Coupon code updates - pull from Export Services
oCampaign/Coupon code updates - push to Import Services
oPromotions available for day (not line-level) - pull from Export Services
oPromotions available for day (line-level) - pull from Export Services
When a basket (or transaction) is being created or completed, the following real-time services can be used:
oBasket Validation - push to Basket Services
oCampaign/Coupon code Validation - pull from Basket Services
Promo Api
.NET Framework and .NET Core 2.0
If the integrating system is authored using Microsoft .NET, it is recommended that you use the Qixol Promo Api Library. This can be added to your project or solution, when using Microsoft Visual Studio, by searching for Qixol Promo in the NuGet Package Manager using nuget.org as the package source, then clicking Install. The assembly provides an object model for all interactions with Qixol Promo.
REST details
When using the REST services, always use the POST verb for all requests.
|
