Product Sync

Product sync pushes article master data from VARIO ERP to the external platform. This includes product names, descriptions, attributes, images, and category assignments.

Trigger

Product sync is triggered by the article.update webhook. When an article's master data changes in the ERP, your app receives a notification and queues the article for sync.

app.apiServer.post('/webhooks/article-update', async (req, res) =>
{
  res.status(200).send({ success: true });

  const { entityId } = req.body;
  await addToQueue('article.sync', entityId);
});

Fetching Article Data

Use VQL to retrieve the article data you need. A typical product sync query fetches the article along with its descriptions, custom fields, and sales channel assignment:

const ErpApi = require('@vario-software/vario-app-framework-backend/api/ErpApi');

async function fetchArticle(articleId, salesChannelId)
{
  const { data } = await ErpApi.vql(
    `SELECT
       id,
       articleNumber,
       sku,
       active,
       descriptions.description,
       descriptions.longDescription,
       descriptions.languageCode.isoAlpha2,
       weight,
       ean
     FROM article.queryArticles
     WHERE id = '${articleId}'`,
    {},
    1
  );

  return data[0] || null;
}

Including Custom Fields

If you stored platform-specific data in EAV custom fields, include them in the query:

const { data } = await ErpApi.vql(
  `SELECT
     id,
     articleNumber,
     custom.myShop.externalProductId,
     custom.myShop.lastSyncDate
   FROM article.queryArticles
   WHERE id = '${articleId}'`,
  {},
  1
);

Fetching Variants

For articles with variants, fetch the variant data:

const { data } = await ErpApi.vql(
  `SELECT
     id,
     articleNumber,
     parentArticle.id,
     parentArticle.articleNumber,
     variantValues.label,
     variantValues.variantDimension.label
   FROM article.queryArticles
   WHERE parentArticle.id = '${parentArticleId}'`,
  {},
  100
);

Transforming Data

Map the ERP article data to the format your platform expects. This is platform-specific and varies widely.

Key fields to transform:

ERP Field	Common Platform Field	Notes
articleNumber	SKU	Primary identifier
descriptions.description	Product title	Map by language
descriptions.longDescription	Product description	May contain HTML
weight	Weight	Check unit (kg, g, lb)
ean	Barcode / GTIN	EAN-13 or UPC
active	Published status	Map boolean to platform status

Handling Multiple Languages

VARIO ERP stores descriptions per language. Map language codes to platform locales:

function transformDescriptions(descriptions, languageMapping)
{
  return descriptions.map(desc => ({
    locale: languageMapping[desc['descriptions.languageCode.isoAlpha2']],
    title: desc['descriptions.description'],
    body: desc['descriptions.longDescription']
  }));
}

Handling Categories

Map ERP categories to platform categories using your mapping configuration. Categories rarely map 1:1 between systems, so a mapping table is essential.

Pushing to the Platform

After transformation, send the data to the platform's API:

async function syncArticleToPlatform(articleId, salesChannelId)
{
  // 1. Fetch from ERP
  const erpArticle = await fetchArticle(articleId, salesChannelId);

  if (!erpArticle)
  {
    return; // Article not found or not assigned to this channel
  }

  // 2. Transform
  const platformProduct = transformArticle(erpArticle);

  // 3. Check if product exists on platform
  const externalId = erpArticle['custom.myShop.externalProductId'];

  if (externalId)
  {
    // Update existing product
    await platformApi.updateProduct(externalId, platformProduct);
  }
  else
  {
    // Create new product
    const created = await platformApi.createProduct(platformProduct);

    // Store the external ID for future updates
    await storeExternalId(articleId, created.id);
  }
}

Image Sync

Product images are often synced separately from master data because they involve file transfers and can be slow:

1. Fetch image URLs or binaries from the ERP

2. Upload to the platform's media/image API

3. Associate images with the product on the platform

Consider using a separate queue topic (e.g., media.sync) for image sync to avoid blocking product sync on slow image uploads.

Create vs. Update

Your sync logic needs to handle both scenarios:

• Create — The product doesn't exist on the platform yet. Create it and store the external ID.

• Update — The product already exists. Update it using the stored external ID.

Use EAV custom fields to track whether a product has been synced and what its external platform ID is.

Error Handling

Common product sync errors:

Error	Cause	Resolution
Product not found in ERP	Article was deleted after webhook fired	Skip and remove from queue
Platform rate limit	Too many API calls	Retry with backoff (framework handles 429 automatically)
Validation error	Platform rejects the data	Log the error, check transform logic
Network timeout	Platform API is slow or down	Retry later

For comprehensive strategies, see Error Handling.