> For the complete documentation index, see [llms.txt](https://docs.solutioo.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.solutioo.de/shopware/stammdatenverwaltung/artikel-matching-and-datenubernahme-aus-shopware.md).

# Artikel-Matching & Datenübernahme aus Shopware

Wenn Sie den Shopware 6 API Connector in einem **bereits befüllten Shop** in Betrieb nehmen, sind dort in der Regel schon Produkte, Bilder, Eigenschaften und Kategorien vorhanden. Diese müssen **nicht neu angelegt** werden. Stattdessen ordnet der Connector die vorhandenen Shopware-Objekte den passenden Artikeln in Business Central zu („Matching") und übernimmt bei Bedarf zusätzliche Daten. Das ist der wichtigste Schritt, um Duplikate zu vermeiden und beide Systeme sauber zu verheiraten.

Diese Seite beschreibt den vollständigen Ablauf ausführlich: vom grundlegenden Prinzip über die einzelnen Übernahme-Bausteine (Bilder, Attribute, Varianten, Kategorien) bis hin zur Fehlerbehebung.

**Warum Matching so wichtig ist**

Jedes Objekt in Shopware besitzt eine eindeutige technische Kennung – die **ID**. In Business Central wird diese Kennung als **Web-ID** am jeweiligen Datensatz gespeichert (z. B. `SOUSHW Web ID` am Artikel). Solange keine Web-ID gesetzt ist, betrachtet der Connector das Objekt als „noch nicht verknüpft" und würde es beim nächsten Upload **neu anlegen**. Genau das führt zu Dubletten. Das Matching sorgt dafür, dass die richtige Web-ID gesetzt wird, **bevor** der erste Upload läuft.

```mermaid
flowchart LR
    S[(Shopware-Shop mit Bestandsdaten)] -->|Matching| BC[(Business Central Artikelstamm)]
    BC -->|Web-IDs gesetzt| U[Sichere Aktualisierung per PATCH]
```

{% hint style="warning" %}
**Reihenfolge beachten:** Führen Sie das Matching immer **vor** dem ersten großen Upload durch. Wird zuerst hochgeladen, können bereits Duplikate entstanden sein, die anschließend aufwändiger zu bereinigen sind (siehe Abschnitt „Doppelte Web-IDs bereinigen").
{% endhint %}

**Schritt 1 – Produkte per SKU zuordnen**

Grundlage ist der Abgleich über die **Artikelnummer**. Der Connector sucht in Shopware nach einem Produkt, dessen **`productNumber` (SKU)** exakt der Artikelnummer in Business Central entspricht, und übernimmt dessen Shopware-ID als Web-ID.

{% stepper %}
{% step %}
**Nummern prüfen**

Stellen Sie sicher, dass die **Artikelnummer in BC** und die **SKU/productNumber in Shopware** übereinstimmen. Nur dann kann der automatische Abgleich greifen.
{% endstep %}

{% step %}
**Abgleich starten**

Starten Sie den Artikelabgleich. Der Connector ruft die Shopware-Suche (`search/product`) mit dem Filter `productNumber = Artikelnummer` auf.
{% endstep %}

{% step %}
**Web-ID wird gesetzt**

Wird genau ein Treffer gefunden, wird die **Shopware-Produkt-ID als Web-ID** gespeichert. Der Artikel gilt danach als verknüpft; künftige Änderungen gehen als **PATCH**.
{% endstep %}
{% endstepper %}

Den technischen Ablauf mit Flussdiagramm beschreibt die Seite Produkt-Matching per SKU & Web-ID.

**Schritt 2 – Varianten und übergeordnete Artikel**

Besitzt ein Produkt in Shopware **Varianten** (z. B. Farbe/Größe), kann der Connector den **übergeordneten Artikel** (Parent) automatisch anlegen und die zugehörigen **Kind-Artikel** verknüpfen. Die Variantenachsen werden dabei als **Option 1, Option 2 und Option 3** abgebildet. Welche Property Group die Farb- bzw. Größenachse darstellt, steuern Sie über die Konfiguration (Label und ID der Farb-/Größen-Eigenschaft). Details unter Varianten abgleichen (Farbe & Größe).

**Schritt 3 – Attribute & Eigenschaften abgleichen**

Damit Filter und Eigenschaften im Shop weiter funktionieren, sollten die **Attribute (Property Groups)** und deren **Optionen** verknüpft werden, statt sie doppelt anzulegen. Die Aktion **Attribute abgleichen** vergleicht vorhandene Shopware-Attribute anhand ihres **Namens** mit den BC-Artikelattributen. Bei einer Übereinstimmung werden **Web-ID**, **Web-Attribut** und **Synchronisiert** gesetzt – es werden **keine neuen Attribute** angelegt. Die zugehörigen Optionswerte werden anhand ihres **Werts** abgeglichen.

Eine ausführliche Anleitung inklusive Namens- und Wert-Matching, Mapping-Feldern und Stolperfallen finden Sie unter Attribute & Eigenschaften (Property Groups) abgleichen.

**Schritt 4 – Was kann sonst noch übernommen werden?**

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Bilder &#x26; Medien</strong></td><td>Coverbild und weitere Artikelbilder werden zugeordnet; das Coverbild wird als Standardbild in BC gesetzt. Bilder-Download</td></tr><tr><td><strong>Attribute &#x26; Optionen</strong></td><td>Property Groups und ihre Optionen werden per Namens-/Wert-Abgleich verknüpft. Attribute abgleichen</td></tr><tr><td><strong>Kategorien &#x26; Kanäle</strong></td><td>Vorhandene Kategorien und Verkaufskanäle werden zugeordnet, damit die Sichtbarkeit erhalten bleibt. Kategorien</td></tr></tbody></table>

**Hilfsfunktionen**

* **Excel-Import:** Unterstützt die Datenübernahme, indem größere Zuordnungslisten strukturiert eingelesen werden.
* **Doppelte Web-IDs bereinigen („Fix Duplicated Web IDs"):** Sind versehentlich mehrere BC-Artikel mit derselben Shopware-ID verknüpft, bereinigt diese Funktion die Dubletten.

**Doppelte Web-IDs bereinigen**

Duplikate entstehen typischerweise, wenn vor dem Matching bereits hochgeladen wurde oder wenn Artikelnummern nicht eindeutig waren. Gehen Sie so vor:

{% stepper %}
{% step %}
**Ursache eingrenzen**

Prüfen Sie im Aktivitätsprotokoll, welche Artikel als Neuanlage statt als Update übertragen wurden.
{% endstep %}

{% step %}
**Bereinigung ausführen**

Nutzen Sie **Fix Duplicated Web IDs**, um doppelte Verknüpfungen aufzulösen.
{% endstep %}

{% step %}
**Nummern korrigieren**

Sorgen Sie für eindeutige, konsistente Artikelnummern und wiederholen Sie den Abgleich für die betroffenen Artikel.
{% endstep %}
{% endstepper %}

**Empfohlenes Vorgehen (Best Practice)**

1. **Erstdaten laden** (Zahlungs-/Versandarten, Steuern, Kanäle, Kundengruppen usw.) – siehe Shopware Erstdaten laden.
2. **Kategorien und Tags** aus Shopware herunterladen, damit die Zuordnung steht.
3. **Attribute abgleichen**, damit Eigenschaften/Filter verknüpft sind – siehe Attribute & Eigenschaften abgleichen.
4. **Produkte per SKU matchen** und Varianten verknüpfen.
5. **Testlauf mit wenigen Artikeln**, Ergebnis prüfen, dann in Wellen ausrollen.

{% hint style="warning" %}
Führen Sie den Abgleich zunächst mit **wenigen Artikeln** durch und prüfen Sie das Ergebnis, bevor Sie große Mengen übernehmen.
{% endhint %}

**Fehlerbehebung**

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Produkt wird doppelt angelegt</strong></td><td>SKU/productNumber stimmen nicht überein – Nummern angleichen und vorhandenes Produkt matchen.</td></tr><tr><td><strong>Attribut nicht verknüpft</strong></td><td>Name weicht ab (Groß-/Kleinschreibung, Leerzeichen). Namen angleichen und erneut abgleichen.</td></tr><tr><td><strong>Variante fehlt</strong></td><td>Farb-/Größen-Eigenschaft nicht korrekt konfiguriert – Label/ID prüfen.</td></tr><tr><td><strong>Bild nicht übernommen</strong></td><td>Medien-Infos abrufen bzw. Standardbild neu setzen.</td></tr></tbody></table>

### Häufige Fragen

#### Wie unterscheidet der Connector zwischen Aktualisieren und Neuanlegen eines Produkts?

Die Entscheidung fällt über die „SOUSHW Web ID“: Ist sie gefüllt, wird das bestehende Shopware-Produkt per PATCH aktualisiert. Ist sie leer, legt der Connector das Produkt neu an (POST) – nach einer vorherigen Duplikatsuche per `search/product` auf die Artikelnummer.

#### Werden nicht mehr zugewiesene Kategorien, Tags oder Attribute in Shopware entfernt?

Ja. Bei einer Aktualisierung ruft der Connector `Product_UnAssign_Categories`, `Product_UnAssign_Tags` und `Product_UnAssign_Properties` auf und entfernt Zuordnungen, die in Business Central nicht mehr gesetzt sind. So entspricht die Zuordnung in Shopware exakt dem aktuellen BC-Stand.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.solutioo.de/shopware/stammdatenverwaltung/artikel-matching-and-datenubernahme-aus-shopware.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.