Your First Shop App

This tutorial walks you through building a minimal shop integration that creates a sales channel, registers a webhook for article updates, and logs incoming product changes. By the end, you will have a working foundation to build upon.

Step 1: Set Up the Project

Start by cloning the demo app and installing dependencies:

git clone https://github.com/vario-software/vario-app-demo.git my-shop-app
cd my-shop-app
npm install

Add your app credentials to app-client.json:

{
  "appIdentifier": "your-app-identifier",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "appJWK": { "...your JWK..." }
}

Step 2: Update the App Manifest

Edit app-manifest.json to declare the permissions your shop app needs:

{
  "appVersion": "1.0.0",
  "label": "My Shop Integration",
  "description": "Connects My Shop Platform with VARIO ERP",
  "shortName": "my-shop",
  "rootUrl": "https://your-app-domain.com/",
  "pcInstallationUrl": "https://your-app-domain.com/ui/install.html",
  "pcInstallationDeletionUrl": "https://your-app-domain.com/ui/uninstall.html",
  "pcManifestUrl": "https://your-app-domain.com/manifest",
  "requirements": {
    "permissions": [
      { "resource": "article", "verb": "read" },
      { "resource": "sales-channel", "verb": "create" },
      { "resource": "sales-channel", "verb": "read" },
      { "resource": "eav", "verb": "create" },
      { "resource": "eav", "verb": "read" },
      { "resource": "eav", "verb": "update" }
    ]
  },
  "uiIntegrations": {
    "integrations": [
      {
        "id": "navigation",
        "pointOfIntegration": "navigation.root",
        "url": "/ui/index.html",
        "iconClass": "fas fa-store",
        "msgKey": "My Shop"
      }
    ]
  }
}

Step 3: Set Up the Installation Migration

Create a migration that sets up a sales channel backend and registers a webhook for article updates.

Create the file backend/services/maintenance/migrations/1/index.js:

const { Migrator } = require('@vario-software/vario-app-framework-backend/utils/migrator');

const handle = async function()
{
  const migrator = new Migrator('migration1');

  // Create a sales channel backend (once)
  await migrator.setMigration('create-sales-channel-backend', async (methods) =>
  {
    const backend = await methods.createSalesChannelBackend(
      'My Shop Platform',
      ['ECOMMERCE']
    );

    // Create an initial sales channel
    await methods.createSalesChannel(
      backend,
      'My Shop',
      'Primary shop connection',
      'ECOMMERCE'
    );

    // Activate the backend
    await methods.activateSalesChannelBackend(backend);
  });

  // Register a webhook for article updates (once)
  await migrator.setMigration('register-article-webhook', async (methods) =>
  {
    await methods.registerWebhook(
      'article.update',
      '/api/webhooks/article-update'
    );
  });

  // Create an EAV group to store platform-specific data (once)
  await migrator.setMigration('create-eav-group', async (methods) =>
  {
    await methods.createEavGroup('my-shop', {
      key: 'my-shop',
      label: 'My Shop',
      attributes: [
        {
          key: 'externalProductId',
          label: 'External Product ID',
          type: 'TEXT',
          viewMode: 'READ_ONLY',
          active: true
        },
        {
          key: 'lastSyncDate',
          label: 'Last Sync Date',
          type: 'TEXT',
          viewMode: 'READ_ONLY',
          active: true
        }
      ],
      linkedEntities: ['article']
    });
  });
};

module.exports = handle;

Step 4: Update the Installation Orchestrator

Edit backend/services/maintenance/install/install.js to call your migration:

const { runAsAppUser } = require('@vario-software/vario-app-framework-backend/setup/runAsAppUser');
const { getRequest, getApp, getTenant } = require('@vario-software/vario-app-framework-backend/utils/context');
const migration1 = require('./migrations/1');

const install = async function()
{
  await runAsAppUser();
  await saveOfflineToken();
  await migration1();
};

const saveOfflineToken = async function()
{
  const request = getRequest();
  const app = getApp();
  const tenant = getTenant();
  const { offlineToken } = request.body;

  if (offlineToken)
  {
    await app.offlineToken.set(tenant, offlineToken);
  }

  const token = await app.offlineToken.get(tenant);
  if (!token)
  {
    throw new Error('MISSING_OFFLINE_TOKEN');
  }
};

module.exports = install;

Step 5: Add the Webhook Handler

Create backend/routes/webhooks.js to handle incoming article updates:

const { log } = require('@vario-software/vario-app-framework-backend/utils/logger');
const ErpApi = require('@vario-software/vario-app-framework-backend/api/ErpApi');

const setupWebhookRoutes = function(app)
{
  app.apiServer.post('/webhooks/article-update', async (req, res) =>
  {
    // Always respond immediately to prevent timeouts
    res.status(200).send({ success: true });

    const { entityId } = req.body;

    await log(`Received article update for: ${entityId}`, 'webhooks', 'INFO');

    try
    {
      // Fetch the updated article data from ERP
      const article = await ErpApi.fetch(`/erp/articles/${entityId}`, {
        useInternalApi: true
      });

      await log(
        `Article "${article.data.articleNumber}" updated. Ready to sync to platform.`,
        'webhooks',
        'INFO'
      );

      // TODO: Add your platform sync logic here
      // For example: await syncArticleToPlatform(article.data);
    }
    catch (error)
    {
      await log(
        `Error processing article update: ${error.message}`,
        'webhooks',
        'ERROR'
      );
    }
  });
};

module.exports = setupWebhookRoutes;

Step 6: Wire Everything Together

Update backend/index.js to register all routes:

const path = require('path');
const VarioCloudApp = require('@vario-software/vario-app-framework-backend');
const clientConfig = require('../app-client.json');
const setupMaintenanceRoutes = require('./routes/maintenance');
const setupWebhookRoutes = require('./routes/webhooks');

const app = new VarioCloudApp(clientConfig, {
  port: '443',
  uiPath: path.join(__dirname, '../frontend'),
  onUnhandledError: async (error) =>
  {
    console.error('Unhandled error:', error);
  }
});

// Register routes
setupMaintenanceRoutes(app);
setupWebhookRoutes(app);

// Start the server
app.start();

Step 7: Test It

1. Start your app locally (see Local Development for tunneling setup)

2. Register your app in the VARIO Cloud Admin Center

3. Install the app — this triggers the installation flow and runs your migrations

4. Edit an article in VARIO ERP — the webhook fires and your handler logs the update

Check your console output. You should see log messages like:

[INFO] Received article update for: 12345-abcde
[INFO] Article "ART-001" updated. Ready to sync to platform.