Upgrading to Web API v2¶
Since the Web API v2 is not backward compatible some actions are required when migrating from v1 to v2. This section is meant as a guide for the migration and it summarizes the major breaking changes introduced in v2.
sessionKey: Must now be a valid UUID v4
customerKey: Must now be a valid UUID v4
market: Must be a configured market to be allowed in notifications
Signed in visitors¶
In v1 the
customerKey was set to a SHA256 calculated via the CustomerKeyAuthentication class. This has been removed and is now always a UUID v4. The UUID should be stored by the retailer for each visitor.
customerKey and the new one should be used together in the same session at least once for eSales to understand that they refer to the same visitor, or they can be migrated explicitly using Customer Keys Migration.
The base URL for the Apptus eSales Web API v2 is now
Two different security mechanisms needed to be implemented when using the Web API v1: security tokens and basic authentication. Different resources needed different security mechanisms.
Web API v2 provides a unified way to handle resources requiring additional security via a new customer header, the
Api-Key header. The value of this header is the customer's
The affected endpoints are the following:
- Secure payment notification
- Dynamic page
- GDPR export customer data
- GDPR customer data job status
- GDPR download customer data
- GDPR remove customer data
A stricter validation of notifications has been introduced. Many validation warnings are now considered as errors instead. For instance, using a non matching product key and variant key in a notification will now fail.
In Web API v2 the namespace
esales. is used for session parameters (i.e. market, session key and customer key) and other parameters do not need to be prepended with
args. anymore. So when migrating panel requests from v1:
esales.marketshould be in the query string instead of
arg.should be removed from all other parameters.
As for notifications, a stricter validation of query parameters has been introduced. The query parameters
esales.market are now mandatory.
A new endpoint for exports is introduced. The export endpoint allows for exporting of a customer's eSales configuration, products, panels, and more.
Two major changes have been introduced when working with dynamic pages.
- All query parameters except
esales.markethave been moved into the body.
- All dynamic page tokens have been removed from v2 in favor of the
Api-Keyheader in the HTTP request.
The second change has a larger impact on the integration. In Web API v1 each panel in a dynamic page needed to have a valid dynamic page token. These security tokens were necessary to limit possible misuse when working with dynamic pages client-side. Token generation needed to be done beforehand on server-side as an extra integration step.
The usage of the customer's private key in the request header makes working with dynamic pages much simpler, but forces the integration to be server-side.
The query result format has been modified in v2. The major changes are:
- Unnecessary and debug information has been removed making the result more compact and avoiding unnecessary data transfer.
- eSales entity attributes such as
ad_keyhave been moved from
attributesto specific properties of the entities.
- Each attribute in eSales entity
attributesis now an array. Attributes defined in eSales as comma-separated or pipe-separated lists of values are now automatically parsed and returned as lists of values.
- Empty panels and panels containing errors are now returned as well making the result more predictable.
Furthermore v2 returns more consistent HTTP status codes for responses where one or more sub-panels contain errors, e.g. if a sub-panel fails because of a wrong argument, the status code will be 400 and not 200 as with Web API v1.
Import and exports for synonyms¶
A new format for import and export of synonyms is introduced.
<?xml version='1.0' encoding='UTF-8'?> <operations> <clear> <synonym/> </clear> <add> <synonym> <locale>en-GB</locale> <search_phrase>Shoes</search_phrase> <synonym_phrase>Boots</synonym_phrase> </synonym> </add> </operations>
If a visitor searches for
Shoes, it will also include searches for
Boots in the result.
- Apptus cookies (
- Dynamic pages can no longer be called client-side. If dynamic pages are used they must be called server-side or be converted into zones.
- The library has a more structured implementation which results in slightly different integration details. For instance the implementation of non-eSales notifications now takes an object as input instead of two strings (i.e. product key and variant key).