Troubleshooting

Ta strona zbiera problemy, które widzimy najczęściej. Do głębszej diagnostyki każde wywołanie do marketplace’u jest zapisane w API Logs (Dashboard → Quick Start → API Logs) z pełnym żądaniem, odpowiedzią, nagłówkami, statusem i czasem trwania.

Sprawdź, czy plugin jest aktywowany w Extensions → My extensions.
Wyczyść cache panelu zgodnie ze standardową procedurą Shopware.
Wykonaj twardy reload panelu (Ctrl+Shift+R), żeby przeglądarka pobrała nowy bundle.
Jeśli sam budujesz administrację, uruchom ponownie odpowiednie polecenie budujące.
Sprawdź, czy Twoja rola użytkownika ma dostęp do uprawnień pluginu w konfiguracji roli.

Wpis pojawia się w grupie Catalogues z niebieską ikoną torby na zakupy. Wszystkie strony pluginu otwierasz z panelu Mirakl Dashboard, albo przez kroki konfiguracyjne, albo przez kafelki Quick Start.

„Invalid API key” / błędy uwierzytelniania przy Test Connection

Skopiuj klucz ponownie z panelu sprzedawcy u operatora. Białe znaki na początku lub końcu to najczęstsza przyczyna.
Niektórzy operatorzy unieważniają klucze po okresie nieaktywności — wygeneruj nowy.
Sprawdź Instance URL — powinien wyglądać jak https://marketplace.example.com, bez dołączonego /api i bez ukośnika na końcu.
Sprawdź Shop ID — wymagane u większości operatorów. Skopiowanie nie tego identyfikatora sklepu z konta sprzedawcy z wieloma sklepami to częsta przyczyna.
Jeśli przepuszczasz API marketplace’u przez wewnętrzny gateway, sprawdź, czy nagłówek Authorization jest przekazywany bez zmian.
Nieudany test zmienia status połączenia na Error i pokazuje komunikat od marketplace’u — najedź na status albo otwórz okno Edit Connection, żeby go zobaczyć.

Błędy eksportu produktów

Częste komunikaty i co z nimi zrobić:

„Category not mapped” — otwórz Mirakl → Quick Start → Categories, kliknij kategorię marketplace’u, przełącz na zakładkę Mapping i dodaj kategorię Shopware. Zobacz Categories.
„Required attribute missing” — otwórz Mirakl → Quick Start → Attribute Mappings, znajdź wymagany atrybut i przyporządkuj go do pola produktu, pola własnego albo grupy właściwości Shopware.
„Invalid attribute value” — skonfiguruj transformację wartości na mapowaniu atrybutu, żeby zamienić wartość Shopware na taką, którą marketplace zaakceptuje (zamiana, wyrażenie regularne, małe litery, maks. długość). Zobacz Value transformations.
„Offer state unknown” — odśwież statusy ofert na stronie Offer States (Refresh Mirakl States), a potem ustaw Default Offer State w Edit Connection albo nadpisz wartość per produkt (zobacz niżej).

Po zakończonym eksporcie posortuj listę Product Catalog po Export Status = error, żeby zobaczyć, które produkty się nie udały i dlaczego.

Zawieszone synchronizacje / brak postępu

Sprawdź, czy proces w tle (messenger:consume async) faktycznie działa.
Sprawdź, czy harmonogram (scheduled-task:run) jest w Twoim cronie albo uruchamia się okresowo.
Blokada throttlingu zwalnia się sama w ciągu minuty — jeśli zadanie nadal stoi po tym czasie, sprawdź listę Tasks (Dashboard → Quick Start → Tasks), żeby zobaczyć status wpisu i ostatni komunikat.
Jeśli wiersz w Sync Logs jest w statusie Started przez godziny bez czasu zakończenia, proces w tle padł w trakcie uruchomienia. Otwórz zakładkę Related Logs na wierszu i zobacz powiązane wpisy w API Logs, żeby sprawdzić, jak daleko zaszło wywołanie marketplace’u.
Przy obsłudze limitu zapytań wiadomość trafia z powrotem do kolejki z opóźnieniem — wznowi się sama, gdy opóźnienie minie. Zobacz API throttling.

Import zamówień nic nie zwraca, mimo że są nowe zamówienia

Sprawdź Initial Order Import Date na połączeniu (krok 12 kreatora) — przy pierwszym uruchomieniu importowane są tylko zamówienia zaktualizowane po tej dacie. Jeśli ustawisz datę w przyszłości, pierwsze uruchomienie nic nie zwróci.
Po pierwszym uruchomieniu plugin pamięta znacznik czasu ostatnio zaimportowanego zamówienia i kontynuuje od tego miejsca. Jeśli zegary marketplace’u się rozjadą, możesz na chwilę przegapić zamówienia — następne odpalenie to nadrobi.
Wiersz Sync Logs dla uruchomienia pokazuje Processed = 0, jeśli marketplace zwrócił pustą stronę. Otwórz powiązany wpis API Logs, żeby zobaczyć faktyczną odpowiedź.
Sprawdź, czy Enable Order Import jest włączone w Mirakl → Settings → Sync Settings.

Komunikaty o limicie zapytań w Sync Logs

Plugin reaguje na limity zapytań, odkładając wiadomość z opóźnieniem, którego zażądał marketplace. Końcowe wykonanie jest gwarantowane, ale przepustowość spada.
Minutowe rozkładanie wywołań w czasie po stronie pluginu dotyczy tylko importów produktów, ofert i stanów. Pozostałe synchronizacje (zamówień, wiadomości, dokumentów, faktur, dziennika transakcji) polegają wyłącznie na odpowiedzi o limicie od marketplace’u.
Przy chronicznych komunikatach o limicie na synchronizacjach nierozkładanych w czasie zwiększ odpowiedni interwał w Mirakl → Settings → Sync Settings.
Nie dziel klucza API między dwiema instancjami Shopware — każda rozkłada swoje własne wywołania, ale marketplace liczy łączne obciążenie. Używaj jednej instancji na konto sprzedawcy.

Pełny obraz znajdziesz w API throttling.

Oferta nie aktualizuje się na marketplace po edycji w Shopware

Otwórz stronę Offer Mappings i sprawdź status synchronizacji oferty. Żeby zmiana została wzięta, powinien być Queued albo Retry.
Jeśli jest Synced, plugin uznaje, że od ostatniej synchronizacji nic się nie zmieniło — niezmienione przesłania są pomijane. Wymuś ponowną synchronizację z Dashboardu → karta połączenia → Sync All Offers.
Jeśli jest Error, ostatni błąd jest pokazany w wierszu — zwykle zmiana kategorii unieważniła ofertę dla aktualnej kategorii marketplace’u albo brakuje wymaganego pola oferty.
Zmiany tylko stanu magazynowego obsługuje zadanie Stock sync w interwale 15-minutowym i natychmiastowe przekazanie zmiany — nie wpływają na status synchronizacji pełnej oferty.

Synchronizacja wiadomości / dokumentów / faktur / dziennika transakcji jest nieaktywna

Te pięć (Enable Message Sync, Enable Order Document Sync, Enable Document Requests Sync, Enable Invoice Sync, Enable Transaction Log Sync) jest domyślnie wyłączone. Włącz je w razie potrzeby w Mirakl → Settings → Sync Settings.
Po włączeniu wstępne pobranie historyczne uruchamia się raz. Obserwuj Sync Logs, żeby zobaczyć postęp — jeśli zostanie przerwane, kursor pamięta, gdzie był, i następne odpalenie wznowi od tego miejsca.

Baza danych rośnie zbyt szybko

API log — każde wywołanie marketplace’u to jeden wiersz z pełnym żądaniem i odpowiedzią. API log cleanup usuwa wiersze starsze niż API Log Retention (days) (domyślnie 30).
Sync log — każde długo działające uruchomienie i każde jednorazowe zdarzenie zapisuje wiersz (chyba że jego poziom jest odznaczony). Sync log cleanup usuwa wiersze starsze niż Sync Log Retention (days) (domyślnie 30).
Task progress — Task progress cleanup usuwa zakończone wpisy raz dziennie.
Wpisy eksportu — Export cleanup usuwa zakończone wiersze eksportu produktów i wygenerowane pliki CSV raz na godzinę.
Dziennik transakcji — dane finansowe, bez automatycznego przechowywania. Archiwizuj do osobnej bazy, jeśli przekraczasz budżet rozmiaru.

Jeśli widzisz niekontrolowany wzrost, upewnij się, że harmonogram działa — bez niego żadne zadanie sprzątające się nie uruchamia.

Gdzie szukać najpierw

Sync Logs (Dashboard → Quick Start → Logs) — wysokopoziomowe „co zostało spróbowane, przetworzone, nie powiodło się”.
API Logs (Quick Start → API Logs) — surowe wywołanie HTTP z pełnym żądaniem i odpowiedzią, filtrowalne po dacie, połączeniu i typie.
Tasks (Quick Start → Tasks) — dla zadań uruchamianych z panelu: procent, ostatni komunikat.
Imports (Quick Start → Imports) i Product Exports (Quick Start → Product Exports) — zadania importu po stronie marketplace’u z ich statusami i błędami poszczególnych linii.

Jeśli nadal nie możesz znaleźć przyczyny, wpis API Logs dla nieudanego wywołania jest tym, co przekazujesz do wsparcia technicznego.