# Integrations

## Outbound (ERP → Platform)

Outbound integrations push data from the ERP to the external platform. Each type is triggered by an ERP webhook, queued, and processed during the `PROCESS_QUEUES` cron. All outbound services follow the same pattern: **Fetch via VQL → Transform → Push to platform API**.

| Topic                  | Webhook                     | What syncs                                           | Transfer Toggle             |
| ---------------------- | --------------------------- | ---------------------------------------------------- | --------------------------- |
| `upsert.article`       | `article.update`            | Article master data (name, description, EAN, weight) | `UPLOAD_ARTICLE_MASTERDATA` |
| `update.article-price` | `article-price.update`      | Net and gross sales prices                           | `UPLOAD_ARTICLE_PRICE`      |
| `update.article-stock` | `sales_channel.stockChange` | Available stock quantity                             | `UPLOAD_ARTICLE_STOCK`      |
| `upsert.article-media` | `article-shelf.update`      | Product images                                       | `UPLOAD_ARTICLE_IMAGE`      |
| `update.orderStatus`   | Delivery document created   | Shipping confirmation + tracking                     | `UPLOAD_ORDER_STATUS`       |

### Fetching Data

Use VQL with `article.shopListing` as the FROM clause to fetch article data including custom fields. Filter by `listings.salesChannel.id` to scope to your channel. Access custom EAV fields via `listings.custom.<eavGroupKey>.<attributeKey>`.

### Storing the External ID

After creating a product on the platform, store the returned ID on the article listing using a PATCH request with `x-vario-suppress-own-webhooks: true` to prevent triggering another webhook.

### Tax Mapping

For price sync, platforms often require a tax rate or tax class. Store a mapping between ERP tax types and platform tax IDs in your app, scoped by sales channel.

## Inbound (Platform → ERP)

Inbound integrations import data from the external platform into the ERP using the **MultiPart Import** system. The pattern is: **Fetch from platform → Transform → Upload via MultiPart Import**.

### Order Import

The most common inbound integration. Triggered by the `ORDER_IMPORT` cron webhook.

1. Read the `LAST_ORDER_IMPORT_TIMESTAMP` parameter
2. Fetch orders from the platform since that timestamp (supports paginated fetching)
3. Transform to the VARIO import format
4. Upload via `MultiPartImporter` with the `account-order` preset
5. Update the timestamp parameter

The `AUTO_ORDER_IMPORT` parameter controls whether orders are automatically executed or only validated for manual review.

### Product Import

Used for marketplace apps where products originate on the platform, not in the ERP. Same pattern as order import with a `product` preset. After import, store the platform ID on the article listing to enable outbound syncs.

### Customer Import

Most apps do **not** need standalone customer import — customer data is embedded in the order import. Only use standalone import if the platform has a customer registration flow independent of orders. Uses an `account` preset.

### MultiPart Import

The `MultiPartImporter` wraps the ERP's multi-part import API:

1. Copies an import preset (defines field mappings)
2. Uploads data via `pushChunk(fileName, data)` — supports pagination
3. Creates import runs and waits for data extraction
4. Validates or executes the import

Import presets are created during the app migration using `methods.createMultipartImportPreset(body)`.