Podłączanie Mirakl

Connection to podstawowa jednostka integracji w P2Lab Mirakl. Łączy jeden marketplace Mirakl z jednym kanałem sprzedaży Shopware i przechowuje wszystkie dane specyficzne dla marketplace’u — kategorie, atrybuty, mapowania, stan synchronizacji — potrzebne do utrzymywania obu stron w synchronizacji. Możesz mieć kilka połączeń obok siebie, po jednym na marketplace.

Plugin konfiguruje nowe połączenie przez 13-krokowy kreator, który prowadzi Cię od podania danych logowania aż po pierwszy eksport katalogu. Kroki opcjonalne można pominąć i skonfigurować później, a kreator można też uruchomić ponownie dla istniejącego połączenia, żeby odświeżyć jego dane referencyjne bez ponownego wpisywania danych uwierzytelniających.

Co musisz mieć od marketplace’u

Instance URL — adres internetowy API sprzedawcy w marketplace’ie (na przykład https://marketplace.example.com). Marketplace podaje go po zaakceptowaniu konta sprzedawcy.
API Key — długi nieczytelny ciąg znaków, który marketplace generuje w panelu sprzedawcy (zwykle w My account → API key). Traktuj go jak hasło.
Shop ID — numeryczny identyfikator sklepu, jaki marketplace przypisał Twojemu kontu sprzedawcy. Widać go w profilu w panelu sprzedawcy.

Potrzebujesz też Sales Channel w Shopware, do którego trafią importowane zamówienia.

Gdzie znaleźć plugin w adminie

Plugin dodaje jeden wpis w głównym menu Shopware, w grupie Catalogues, z etykietą Mirakl (niebieska ikona torby zakupowej). Kliknięcie otwiera Dashboard.

Karta Quick Start na Dashboardzie ma kafelek do każdej strony (Offers, Catalog, Orders, Categories, Attribute Mappings, Offer Field Mappings, Invoices, Transaction Logs, Logs, API Logs, Settings, …). Kliknij Settings, żeby otworzyć stronę ustawień z trzema zakładkami: Connections, Sync Settings i Options.

Dopóki nie utworzysz pierwszego połączenia, Dashboard pokazuje też sekcję Setup Status z linkami do kroków (Configure Connection, Map Categories, Add Products to Catalog, …). Gdy konfiguracja jest gotowa, sekcja zostaje zastąpiona krótkim opisem Mirakl Integration, a po stronach pluginu poruszasz się już wyłącznie po kafelkach Quick Start.

Uruchom kreator

Otwórz Mirakl → Settings → Connections i kliknij Add Connection na górze listy. Kreator otwiera się w kroku 1.

Dla istniejącego połączenia kreator możesz uruchomić z menu kontekstowego wiersza (trzy kropki po prawej) — wybierz Run Setup Wizard. Ta opcja pomija krok 1 (dane logowania) i zaczyna od kroku 2, więc możesz odświeżyć dane referencyjne marketplace’u i przerobić mapowania bez ponownego wpisywania niczego.

Krok 1 — Connection

Wpisz dane logowania i wybierz docelowy kanał sprzedaży:

Connection Name — etykieta, którą rozpoznasz, na przykład ManoMano FR. Używaj nazw, w których jest marketplace i kraj — łatwiej będzie je rozpoznać w innych listach pluginu.
Instance URL — wklej adres internetowy marketplace’u.
API Key — wklej klucz API sprzedawcy (pole ukrywa wartość, ale możesz ją skopiować).
Shop ID — wklej numeryczny identyfikator sklepu.
Sales Channel — wybierz kanał sprzedaży Shopware, w którym będą tworzone zamówienia z tego marketplace’u.

Wszystkie pięć pól jest wymaganych. W stopce są dwa przyciski:

Test Connection — wysyła małe żądanie testowe z URL-em i kluczem (bez zapisu) i pokazuje, czy się powiodło, albo wyświetla komunikat błędu z marketplace’u.
Save & Continue — zapisuje połączenie (w stanie Disconnected), uruchamia test w tle i przechodzi do kroku 2. Udany test zmienia status na Connected; nieudany — na Error. Nie musisz czekać — wynik testu pojawi się na liście połączeń, gdy tylko będzie gotowy.

Krok 2 — Categories

Kreator uruchamia zadanie w tle, które pobiera całe drzewo kategorii marketplace’u (na dużych marketplace’ach mogą to być dziesiątki tysięcy pozycji) i wiąże je z tym połączeniem. Pasek postępu pokazuje, ile pozycji zostało przetworzonych z ogólnej liczby. Gdy zadanie się skończy, zobaczysz:

N categories linked to connection — łączna liczba dostępna po odświeżeniu.
N new categories added — pojawia się tylko wtedy, gdy odświeżanie znalazło wcześniej nieznane pozycje.

Kliknij Next, gdy zadanie się zakończy.

Krok 3 — Product Attributes

Ten sam schemat co w poprzednim kroku: zadanie w tle pobiera wszystkie atrybuty produktu, jakie definiuje marketplace (razem z dozwolonymi wartościami i regułami), i wiąże je z połączeniem. Po zakończeniu raportuje N product attributes linked to connection oraz N new attributes added.

Krok 4 — Offer States

Pobiera wartości statusu oferty akceptowane przez marketplace (np. new, used-good). Po zakończeniu odświeżania pojawia się lista Default Offer State — wybierz wartość, której plugin ma użyć domyślnie przy wysyłaniu nowych ofert (możesz później nadpisać ją per produkt). Wybór zapisuje się po kliknięciu Next.

Krok 5 — Reason Codes

Pobiera kody powodów odmowy i zwrotu, jakie definiuje marketplace. Nie są one mapowane z góry — plugin pokaże Ci je w momencie, w którym faktycznie odmawiasz albo obsługujesz zwrot, żebyś mógł wskazać właściwy.

Krok 6 — Offer Fields

Pobiera definicje pól oferty, jakich marketplace oczekuje dla każdej oferty (cena, stan magazynowy, czas wysyłki, EAN itp.). Zmapujesz je z polami Shopware w kolejnym kroku.

Krok 7 — Offer Field Mappings

Wstępne mapowanie między polami Shopware a polami oferty Mirakl. W stopce trzy przyciski:

Skip — zostaw połączenie bez mapowań; ustawisz je później w Settings.
Apply Defaults — wstaw zestaw sensownych mapowań domyślnych. Istniejące mapowania nie są nadpisywane.
Import JSON — wgraj plik mapowań wyeksportowany wcześniej z innego sklepu. Kreator zaraportuje, ile mapowań zostało zaimportowanych, zastąpionych, pominiętych oraz ile pól nie udało się znaleźć w tym połączeniu.

Krok 8 — Auto-Map Attributes

Plugin może spróbować dopasować atrybuty produktu z marketplace’u do pól Shopware, pól niestandardowych, grup właściwości i kategorii, porównując nazwy. W stopce trzy przyciski:

Skip — ustawisz mapowania atrybutów ręcznie później w Settings.
Import JSON — wgraj plik mapowań atrybutów wyeksportowany wcześniej z innego sklepu. Kreator zaraportuje, ile mapowań zaimportowano, zastąpiono, pominięto i ilu atrybutów nie znaleziono.
Run Auto-Map — uruchamia zadanie w tle z paskiem postępu. Po zakończeniu raportuje, ile nowych mapowań powstało, ile istniejących zostało powiązanych z połączeniem oraz ile atrybutów pominięto, bo nie znaleziono dla nich dobrego dopasowania.

Krok 9 — Order Status Mapping

Skonfiguruj, w jaki sposób statusy zamówień marketplace’u odpowiadają statusom zamówień, dostawy i płatności w Shopware (np. status Shipping marketplace’u odpowiada zamówieniu Shopware w trakcie realizacji ze statusem dostawy Shipped). Sensowne wartości są wstawione z góry. Wybierz — w wierszu, w którym chcesz zostawić odpowiedni status Shopware bez zmian. Konfiguracja zapisuje się po kliknięciu Next.

Krok 10 — Reverse Status Mapping

Druga strona medalu: które zmiany statusu w Shopware mają wywoływać akcje po stronie marketplace’u (akceptacja, wysyłka, odmowa). Na przykład oznaczenie zamówienia Shopware jako Completed może wywołać potwierdzenie wysyłki po stronie marketplace’u. Wybierz —, żeby wyłączyć wiersz. Zapis po Next.

Krok 11 — Document Auto-Upload

Zdecyduj, które typy dokumentów Shopware (faktura, dokument dostawy, korekta, …) mają być automatycznie wysyłane do marketplace’u zaraz po wygenerowaniu:

Przełącznik włącza i wyłącza całą funkcję dla tego połączenia.
Gdy przełącznik jest włączony, mały edytor pozwala zestawić każdy typ dokumentu Shopware z typem dokumentu Mirakl. Niezestawione typy nie są wysyłane.

Zapis po Next.

Krok 12 — Import Orders

Zdecyduj, jak daleko wstecz pobierać zamówienia historyczne z marketplace’u:

Import all historical orders — pobiera wszystko, co API marketplace’u zwróci dla tego sklepu.
Import orders from a specific date — wybierz datę; importowane są tylko zamówienia utworzone w tej dacie lub później.

Gdy klikniesz Next, wybrana data zostaje zapisana w połączeniu, a zadanie importu zamówień rusza natychmiast. Wiadomości dla zaimportowanych zamówień są potem pobierane automatycznie w tle.

Krok 13 — Catalog Export

Ostatni krok. Kreator przypomina Ci, że:

Konfiguracja połączenia jest skończona.
Aby marketplace mógł zaciągnąć Twoje produkty, musisz skonfigurować Catalog Mapping w swoim marketplace Mirakl, używając pliku CSV z Twoimi produktami.
Wygenerowany CSV wgrywasz w Mirakl w Settings → Catalog mapping → Use the mapping wizard.

Klik Finish zamyka kreator i przenosi Cię na stronę Catalog Export dla tego połączenia, gdzie wygenerujesz CSV.

Późniejszy retest połączenia

Dane logowania możesz przetestować w każdej chwili:

Z listy Connections — menu kontekstowe wiersza → Test Connection.
Z okna Edit Connection — przycisk Test Connection w stopce okna.

Udany test ustawia status z powrotem na Connected; nieudany — na Error i pokazuje komunikat błędu zwrócony przez marketplace w powiadomieniu.

Późniejsza edycja połączenia

W menu kontekstowym wiersza Edit otwiera okno, w którym możesz zmienić Connection Name, Instance URL, API Key, Shop ID, Sales Channel i Default Offer State. W stopce okna są też skróty Run Setup Wizard (uruchamia kreator od kroku 2) i Test Connection.

Ustawienia per funkcja, których nie ma w podstawowym oknie Edit Connection — Order Status Mapping, Reverse Status Mapping, Document Auto-Upload, Variant Name Format, Catalog Export — mają własne pozycje w tym samym menu kontekstowym i otwierają osobne okna lub strony.

Kilka połączeń naraz

Z jednego sklepu Shopware możesz połączyć się z wieloma marketplace’ami Mirakl — każde dostaje własny Instance URL, API Key, Shop ID i własną kopię danych referencyjnych marketplace’u. Mapowania (kategorii, atrybutów, pól oferty) są zapisywane per Connection, więc ta sama kategoria Shopware może mapować się na zupełnie różne kategorie marketplace’u w różnych połączeniach, bez żadnego konfliktu.

Co dalej: pierwsza synchronizacja

Przejdź do First sync, żeby wysłać pierwszą partię produktów.