Mirakl verbinden

Eine Verbindung (Connection) ist die Grundeinheit der Integration in P2Lab Mirakl. Sie verknüpft einen Mirakl-Marktplatz mit einem Shopware-Verkaufskanal und speichert alle marktplatzspezifischen Daten — Kategorien, Attribute, Zuordnungen, Synchronisationszustand —, die nötig sind, um beide Seiten synchron zu halten. Sie können mehrere Verbindungen nebeneinander betreiben, eine pro Marktplatz.

Das Plugin richtet eine neue Verbindung über einen 13-stufigen Assistenten ein, der Sie von den Zugangsdaten bis zum ersten Katalogexport führt. Optionale Schritte können übersprungen und später konfiguriert werden, und Sie können den Assistenten erneut auf einer bestehenden Verbindung ausführen, um deren Referenzdaten aufzufrischen, ohne die Zugangsdaten neu einzugeben.

Was Sie vom Marktplatz brauchen

Instanz-URL — die Internetadresse der Verkäufer-API des Marktplatzes (zum Beispiel https://marketplace.example.com). Der Marktplatz teilt Ihnen diese mit, nachdem Ihr Verkäuferkonto freigegeben wurde.
API Key — eine lange, undurchsichtige Zeichenkette, die der Marktplatz in Ihrem Verkäufer-Dashboard erzeugt (üblicherweise unter Mein Konto → API key). Behandeln Sie ihn wie ein Passwort.
Shop ID — die numerische Shop-Kennung, die der Marktplatz Ihrem Verkäuferkonto zugewiesen hat. Sie ist in Ihrem Verkäufer-Profil sichtbar.

Außerdem brauchen Sie einen Shopware-Verkaufskanal, in dem die importierten Bestellungen angelegt werden.

Wo Sie das Plugin in der Administration finden

Das Plugin fügt einen einzigen Eintrag in die Hauptnavigation der Shopware-Administration ein, in der Gruppe Kataloge, mit dem Namen Mirakl (blaues Einkaufstaschen-Symbol). Ein Klick darauf öffnet das Dashboard.

Die Karte Schnellstart auf dem Dashboard hat eine Kachel für jede Seite (Angebote, Katalog, Bestellungen, Kategorien, Attributzuordnungen, Angebotsfeld-Zuordnungen, Rechnungen, Transaktionsprotokolle, Protokolle, API Logs, Einstellungen, …). Klicken Sie auf Einstellungen, um die Einstellungsseite mit drei Reitern zu öffnen: Verbindungen, Synchronisierungseinstellungen und Optionen.

Solange Sie noch keine Verbindung angelegt haben, zeigt das Dashboard zusätzlich einen Abschnitt Einrichtungsstatus mit verlinkten Schritten (Verbindung konfigurieren, Kategorien zuordnen, Produkte zum Katalog hinzufügen, …). Sobald die Einrichtung abgeschlossen ist, wird dieser Abschnitt durch eine kurze Beschreibung Mirakl-Integration ersetzt, und Sie navigieren ausschließlich über die Schnellstart-Kacheln.

Den Assistenten öffnen

Öffnen Sie Mirakl → Einstellungen → Verbindungen und klicken Sie oben auf der Liste auf Verbindung hinzufügen. Der Assistent öffnet sich bei Schritt 1.

Für eine bestehende Verbindung können Sie den Assistenten aus dem Kontextmenü der Zeile (drei Punkte rechts) erneut öffnen — wählen Sie Setup-Assistent starten. Diese Option überspringt Schritt 1 (Zugangsdaten) und beginnt bei Schritt 2, sodass Sie die Referenzdaten des Marktplatzes auffrischen und Zuordnungen neu vornehmen können, ohne etwas neu einzutippen.

Schritt 1 — Verbindung

Geben Sie die Zugangsdaten ein und wählen Sie den Ziel-Verkaufskanal:

Verbindungsname — eine Bezeichnung, die Sie wiedererkennen, zum Beispiel ManoMano FR. Verwenden Sie eindeutige Namen, die den Marktplatz und das Land enthalten, damit Sie sie in anderen Auswahlfeldern des Plugins leicht unterscheiden können.
Instanz-URL — fügen Sie die Internetadresse des Marktplatzes ein.
API Key — fügen Sie Ihren Verkäufer-API-Schlüssel ein (das Feld blendet den Wert aus, Sie können ihn aber kopieren).
Shop ID — fügen Sie die numerische Shop-Kennung ein.
Verkaufskanal — wählen Sie den Shopware-Verkaufskanal, in dem Bestellungen von diesem Marktplatz angelegt werden.

Alle fünf Felder sind Pflichtfelder. Die Fußleiste hat zwei Schaltflächen:

Verbindung testen — sendet eine kleine Testanfrage mit der URL und dem Schlüssel (ohne zu speichern) und meldet entweder Erfolg oder die Fehlermeldung des Marktplatzes.
Speichern & Weiter — speichert die Verbindung (im Status disconnected), startet einen Test im Hintergrund und geht zu Schritt 2 weiter. Ein erfolgreicher Test ändert den Status auf connected; ein Fehlschlag auf error. Sie müssen nicht auf den Test warten — das Ergebnis erscheint in der Verbindungsliste, sobald es vorliegt.

Schritt 2 — Kategorien

Der Assistent startet eine Hintergrundaufgabe, die den kompletten Kategoriebaum des Marktplatzes abruft (bei großen Marktplätzen können das Zehntausende Einträge sein) und mit dieser Verbindung verknüpft. Eine Fortschrittsanzeige zeigt, wie viele Einträge von der Gesamtzahl bereits verarbeitet sind. Wenn die Aufgabe fertig ist, sehen Sie:

N categories linked to connection — die Gesamtzahl nach der Aktualisierung.
N new categories added — erscheint nur, wenn die Aktualisierung bislang unbekannte Einträge gefunden hat.

Klicken Sie auf Weiter, sobald die Aufgabe abgeschlossen ist.

Schritt 3 — Produktattribute

Gleicher Ablauf wie im vorigen Schritt: Eine Hintergrundaufgabe holt alle Produktattribute ab, die der Marktplatz definiert (inklusive erlaubter Werte und Regeln), und verknüpft sie mit der Verbindung. Am Ende meldet sie N product attributes linked to connection und N new attributes added.

Schritt 4 — Angebotsstatus

Holt die Angebotsstatuswerte ab, die der Marktplatz akzeptiert (z. B. new oder used-good). Nach der Aktualisierung erscheint ein Auswahlfeld Standard-Angebotsstatus — wählen Sie den Wert, der als Vorgabe verwendet werden soll, wenn neue Angebote übertragen werden (Sie können ihn später pro Produkt überschreiben). Ihre Auswahl wird beim Klick auf Weiter gespeichert.

Schritt 5 — Grund-Codes

Holt die Ablehnungs- und Rücksendegründe ab, die der Marktplatz definiert. Sie werden nicht im Voraus zugeordnet — das Plugin zeigt sie Ihnen in dem Moment, in dem Sie eine Bestellung tatsächlich ablehnen oder eine Rücksendung bearbeiten, damit Sie den passenden auswählen können.

Schritt 6 — Angebotsfelder

Holt die Angebotsfeld-Definitionen ab, die der Marktplatz für jedes Angebot erwartet (Preis, Bestand, Lieferzeit, EAN usw.). Im nächsten Schritt ordnen Sie diese den Shopware-Feldern zu.

Schritt 7 — Angebotsfeld-Zuordnungen

Initiale Zuordnung zwischen Shopware-Feldern und Mirakl-Angebotsfeldern. In der Fußleiste gibt es drei Schaltflächen:

Überspringen — lässt die Verbindung ohne Zuordnungen; Sie können sie später unter Einstellungen einrichten.
Standardwerte anwenden — füllt einen Satz sinnvoller Standardzuordnungen aus. Bereits vorhandene Zuordnungen werden nicht überschrieben.
JSON importieren — laden Sie eine Mapping-Datei hoch, die zuvor aus der Verbindung eines anderen Shops exportiert wurde. Der Assistent meldet danach, wie viele Zuordnungen importiert, ersetzt, übersprungen oder nicht gefunden wurden.

Schritt 8 — Attribute automatisch zuordnen

Das Plugin kann versuchen, Mirakl-Produktattribute über Namensähnlichkeit mit passenden Shopware-Feldern, eigenen Feldern, Eigenschaftsgruppen und Kategorien zu verknüpfen. In der Fußleiste gibt es drei Schaltflächen:

Überspringen — Attributzuordnungen später manuell unter Einstellungen einrichten.
JSON importieren — laden Sie eine zuvor aus einem anderen Shop exportierte Attribut-Mapping-Datei hoch. Der Assistent meldet importierte / ersetzte / übersprungene / fehlende Zuordnungen.
Auto-Mapping starten — startet eine Hintergrundaufgabe mit Fortschrittsanzeige. Am Ende meldet sie, wie viele neue Zuordnungen erstellt wurden, wie viele bestehende verknüpft wurden und wie viele Attribute übersprungen wurden, weil keine passende Übereinstimmung gefunden wurde.

Schritt 9 — Bestellstatus-Zuordnung

Konfigurieren Sie, wie Marktplatz-Bestellstatus auf Shopware-Bestell-, Versand- und Zahlungsstatus abgebildet werden (zum Beispiel entspricht der Marktplatz-Status Shipping einer Shopware-Bestellung im Status „In Bearbeitung” mit Versandstatus Versendet). Sinnvolle Werte sind vorausgefüllt. Wählen Sie in einer Zeile —, um den zugehörigen Shopware-Status unverändert zu lassen. Die Konfiguration wird beim Klick auf Weiter gespeichert.

Schritt 10 — Umgekehrte Status-Zuordnung

Die Gegenrichtung: welche Shopware-Statuswechsel Aktionen auf dem Marktplatz auslösen (akzeptieren, versenden, ablehnen). Zum Beispiel kann das Setzen einer Shopware-Bestellung auf Abgeschlossen eine Versandbestätigung auf dem Marktplatz auslösen. Wählen Sie —, um eine Zeile zu deaktivieren. Gespeichert beim Klick auf Weiter.

Schritt 11 — Dokument-Auto-Upload

Legen Sie fest, welche Shopware-Dokumenttypen (Rechnung, Lieferschein, Gutschrift, …) automatisch in den Marktplatz hochgeladen werden, sobald sie generiert wurden:

Ein Schalter aktiviert oder deaktiviert die Funktion für diese Verbindung insgesamt.
Wenn der Schalter aktiv ist, können Sie in einem kleinen Editor jedem Shopware-Dokumenttyp einen Mirakl-Dokumenttyp zuordnen. Nicht zugeordnete Typen werden nicht hochgeladen.

Gespeichert beim Klick auf Weiter.

Schritt 12 — Bestellungen importieren

Legen Sie fest, wie weit zurück historische Bestellungen aus dem Marktplatz geholt werden sollen:

Alle historischen Bestellungen importieren — holt alles, was die API des Marktplatzes zurückgibt.
Bestellungen ab einem bestimmten Datum importieren — eine Datumsauswahl; nur Bestellungen ab diesem Datum werden importiert.

Mit Klick auf Weiter wird das gewählte Datum in der Verbindung gespeichert und ein Bestellimport-Job sofort gestartet. Nachrichten zu den importierten Bestellungen werden anschließend automatisch im Hintergrund nachgeladen.

Schritt 13 — Katalog-Export

Der letzte Schritt. Der Assistent weist Sie darauf hin, dass:

Die Einrichtung der Verbindung abgeschlossen ist.
Damit der Marktplatz Ihre Produkte aufnehmen kann, müssen Sie das Katalogmapping in Ihrem Mirakl-Marktplatz konfigurieren — mithilfe einer CSV-Datei mit Ihren Produkten.
Die erzeugte CSV-Datei laden Sie in Mirakl unter Einstellungen → Katalogmapping → Mapping-Assistenten verwenden hoch.

Mit Klick auf Fertig schließt sich der Assistent und Sie landen auf der Seite Katalog-Export für diese Verbindung, auf der Sie die CSV-Datei erzeugen.

Die Verbindung später testen

Sie können die Zugangsdaten jederzeit erneut testen:

Aus der Verbindungsliste — Kontextmenü der Zeile → Verbindung testen.
Aus dem Dialog Verbindung bearbeiten — Schaltfläche Verbindung testen in der Fußleiste des Dialogs.

Ein erfolgreicher Test setzt den Status wieder auf connected; ein Fehlschlag setzt ihn auf error und zeigt die Fehlermeldung des Marktplatzes in einer Benachrichtigung.

Eine Verbindung später bearbeiten

Im Kontextmenü der Zeile öffnet Bearbeiten einen Dialog, in dem Sie Verbindungsname, Instanz-URL, API Key, Shop ID, Verkaufskanal und Standard-Angebotsstatus ändern können. Die Fußleiste des Dialogs enthält außerdem die Schnellzugriffe Setup-Assistent starten (führt den Assistenten ab Schritt 2 erneut aus) und Verbindung testen.

Die feature-spezifischen Einstellungen, die nicht im einfachen Dialog Verbindung bearbeiten stehen — Bestellstatus-Zuordnung, Umgekehrte Status-Zuordnung, Dokument-Auto-Upload, Variantennamen-Format, Katalog-Export — haben jeweils einen eigenen Eintrag im selben Kontextmenü und öffnen einen eigenen Dialog oder eine eigene Seite.

Mehrere Verbindungen gleichzeitig

Aus einem Shopware-Shop können Sie sich mit mehreren Mirakl-Marktplätzen verbinden — jede Verbindung erhält ihre eigene Instanz-URL, API Key, Shop ID und eine eigene Kopie der Referenzdaten des Marktplatzes. Zuordnungen (Kategorien, Attribute, Angebotsfelder) werden pro Verbindung gespeichert, sodass dieselbe Shopware-Kategorie in unterschiedlichen Verbindungen auf ganz unterschiedliche Marktplatz-Kategorien abgebildet werden kann, ohne dass sich etwas in die Quere kommt.

Weiter: erste Synchronisation

Weiter geht es mit Erste Synchronisation, um die erste Auswahl an Produkten zu übertragen.