Multipart Import

The MultiPart Import API is VARIO ERP's mechanism for importing structured data in bulk. Shop integrations use it primarily for importing orders, but it can also handle products, customers, and other entities.

How It Works

MultiPart Import uses a two-step process:

1. Import Preset — A predefined configuration that tells the ERP how to map incoming data fields to entity fields. You create this during installation.

2. Import Run — An API call that submits data against a preset for processing.

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ Your App     │────►│ MultiPart    │────►│ VARIO ERP    │
│ sends data   │     │ Import API   │     │ creates      │
│ + preset ID  │     │ validates &  │     │ entities     │
│              │     │ maps fields  │     │              │
└──────────────┘     └──────────────┘     └──────────────┘

Creating Import Presets

Create import presets during your app's installation migration:

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

const migrator = new Migrator('install');

await migrator.setMigration('create-import-presets', async (methods) =>
{
  // Order import preset
  await methods.createMultipartImportPreset({
    name: 'My Shop Order Import',
    entity: 'account-order'
    // ... additional configuration
  });
});

Updating Import Presets

If your import format changes (e.g., new fields added in a later version), update the preset:

await migrator.setMigration('update-import-preset-v2', async (methods) =>
{
  await methods.updateMultipartImportPreset(presetId, {
    name: 'My Shop Order Import v2',
    entity: 'account-order'
    // ... updated configuration
  });
});

Running an Import

Submit data to the import API:

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

async function runImport(presetId, importData)
{
  const result = await ErpApi.fetch('/cmn/data-import/runs/multi-part', {
    method: 'POST',
    useInternalApi: true,
    body: JSON.stringify({
      presetId: presetId,
      data: importData
    })
  });

  return result.data;
}

Import Data Format

The data you submit must match the field mapping defined in your import preset. The general structure is an array of objects, where each object represents one entity to import:

const orders = [
  {
    externalId: 'ORD-001',
    customerEmail: '[email protected]',
    orderDate: '2026-01-15T10:30:00Z',
    items: [
      {
        sku: 'ART-001',
        quantity: 2,
        unitPrice: 29.99
      },
      {
        sku: 'ART-002',
        quantity: 1,
        unitPrice: 49.99
      }
    ],
    shippingAddress: {
      name: 'John Doe',
      street: '123 Main Street',
      city: 'Berlin',
      postalCode: '10115',
      country: 'DE'
    },
    paymentMethodId: 'pm-credit-card',
    shippingMethodId: 'sm-standard'
  }
];

await runImport(orderPresetId, orders);

The exact field names and structure depend on your import preset configuration. The example above is illustrative — your actual data format will be defined by the preset you create.

Handling Import Results

The import API returns information about the import run, including success/failure status and any validation errors:

const result = await runImport(presetId, data);

if (result.errors && result.errors.length > 0)
{
  for (const error of result.errors)
  {
    await log(
      `Import error: ${error.message} (row: ${error.row})`,
      'import',
      'ERROR'
    );
  }
}

Batch Processing

For large imports, split your data into batches to avoid timeouts and memory issues:

async function importInBatches(presetId, allData, batchSize = 50)
{
  for (let i = 0; i < allData.length; i += batchSize)
  {
    const batch = allData.slice(i, i + batchSize);

    try
    {
      await runImport(presetId, batch);
      await log(
        `Imported batch ${i / batchSize + 1} (${batch.length} items)`,
        'import',
        'INFO'
      );
    }
    catch (error)
    {
      await log(
        `Batch ${i / batchSize + 1} failed: ${error.message}`,
        'import',
        'ERROR'
      );
      // Decide whether to continue or abort
    }
  }
}

Common Entity Types

Entity	Description
account-order	Customer orders (sales orders)
product	Products/articles