Jak odróżnić błąd API od problemu po stronie WooCommerce lub Allegro?
Jeśli integracja WooCommerce z Allegro przestała działać, pierwszym krokiem nie jest „naprawianie wszystkiego”, tylko szybkie przypisanie objawu do jednej z warstw: API, mapowania danych albo harmonogramu synchronizacji. Taki podział od razu zawęża obszar poszukiwań i chroni przed błądzeniem po ustawieniach wtyczki.
W praktyce błąd API najczęściej widać w odpowiedziach serwera: 401 lub 403 sugeruje problem z autoryzacją, 429 wskazuje na limity, a kody 5xx zwykle oznaczają kłopot po stronie usługi lub tymczasową niedostępność endpointu. Jeżeli w logach pojawiają się timeouty albo przerwane połączenia, warto sprawdzić też stabilność hostingu i sieci, zanim zaczniesz zmieniać dane produktów.
| Objaw | Najbardziej prawdopodobna warstwa | Co sprawdzić najpierw |
|---|---|---|
| 401 / 403 w logach | API / autoryzacja | Token OAuth, uprawnienia, wygasłe połączenie z Allegro |
| 429, throttling, odrzucenia po serii żądań | API / limity | Częstotliwość wywołań, kolejkę, ewentualne ograniczenia po stronie integracji |
| 5xx, timeout, brak odpowiedzi | API / infrastruktura | Status usługi, połączenie, logi serwera, stabilność hostingu |
| Brak aktualizacji mimo aktywnej integracji | Harmonogram synchronizacji | WP-Cron, cron systemowy, kolejka zadań, ręczny test synchronizacji |
| Oferty publikują się z brakującymi polami lub w złej kategorii | Mapowanie danych | SKU, EAN, atrybuty, kategorie Allegro, wymagane parametry |
Wniosek praktyczny
Jeśli ręczna synchronizacja działa, a automatyczna nie, to zwykle nie jest problem z API, tylko z harmonogramem lub kolejką zadań. Jeśli synchronizacja dochodzi do skutku, ale dane w Allegro są niepełne lub błędne, trop prowadzi raczej do mapowania albo walidacji pól.
Nie wyciągaj wniosków tylko z objawu
„Brak synchronizacji” może oznaczać trzy różne rzeczy: integracja nie uruchamia żądań, żądania są odrzucane przez API albo dane trafiają do Allegro, lecz są blokowane na etapie walidacji. Dopiero logi z kodem odpowiedzi, identyfikatorem żądania i informacją o zadaniu cron pozwalają odróżnić te scenariusze.
Czy problem wynika z mapowania pól, a nie z samej synchronizacji?
Jeśli integracja WooCommerce z Allegro działa technicznie, ale efekt na aukcjach jest niepełny, źródła problemu często trzeba szukać nie w samym przesyle danych, tylko w mapowaniu pól. To właśnie na tym etapie decyduje się, czy SKU, EAN, atrybuty, warianty i kategorie zostaną poprawnie przełożone na wymagania Allegro.
Najpierw sprawdź zgodność danych, nie sam fakt wysyłki
Typowy sygnał błędnego mapowania to sytuacja, w której produkt ma poprawną cenę i stan w WooCommerce, ale w Allegro pojawia się z brakującym opisem, w złej kategorii albo z niepełnymi parametrami. Taki objaw zwykle oznacza, że integracja wysłała ofertę, lecz nie znalazła odpowiedniego odwzorowania pól wejściowych na strukturę wymaganych danych po stronie Allegro.
Na co zwrócić uwagę w pierwszej kolejności
W praktyce warto porównać trzy warstwy: dane produktu w WooCommerce, reguły mapowania wtyczki oraz wymagania konkretnej kategorii Allegro. Jeśli choć jedna z nich nie zgadza się z pozostałymi, oferta może przejść tylko częściowo albo zostać odrzucona na etapie walidacji.
| Objaw w Allegro | Prawdopodobna przyczyna | Co sprawdzić |
|---|---|---|
| Brak ceny, opisu lub części parametrów | Niepełne odwzorowanie pól | Ustawienia mapowania wtyczki, wymagane pola dla kategorii |
| Oferta trafia do niewłaściwej kategorii | Błędne przypisanie kategorii | Reguły kategorii Allegro i przypisania produktu w sklepie |
| Nieprawidłowe warianty lub brak wariantów | Problem z atrybutami i wariantami | SKU, EAN, atrybuty wariantów, powiązania produktów |
| Publikacja przechodzi, ale opis jest uboższy niż w sklepie | Brak dopasowania atrybutów lub ograniczenie pola | Mapowanie parametrów i format treści obsługiwany przez integrację |
Uważaj na pozorne oznaki poprawnej synchronizacji
To, że oferta została utworzona, nie znaczy jeszcze, że mapowanie jest poprawne. Jeżeli dane są obcięte, niekompletne albo niezgodne z wymaganiami kategorii, problem może wyglądać jak awaria synchronizacji, choć w rzeczywistości jest błędem konfiguracji pól.
Jak sprawdzić, czy harmonogram synchronizacji w ogóle działa?
Jeśli WooCommerce i Allegro są połączone, ale zmiany pojawiają się z opóźnieniem albo tylko po ręcznym uruchomieniu zadania, bardzo często problem leży nie w API, lecz w harmonogramie synchronizacji. W praktyce chodzi o to, czy zadania w ogóle są wywoływane, czy trafiają do kolejki i czy przetwarzanie nie utknęło po drodze.
Najpierw sprawdź, czy integracja ma w ogóle czym uruchamiać synchronizację: WP-Cron, cron systemowy na serwerze albo własny mechanizm kolejki wtyczki. Jeżeli ruch w sklepie jest mały, WP-Cron może działać nieregularnie, bo odpala się przy wejściach na stronę, a nie według zegarka. To od razu tłumaczy sytuację, w której oferta aktualizuje się dopiero po kilku godzinach.
Sygnał, że winny jest harmonogram
Jeśli ręczna synchronizacja przechodzi poprawnie, a automatyczna nie uruchamia się lub uruchamia się rzadko, źródła problemu należy szukać w cronach, kolejce zadań albo ustawieniach częstotliwości synchronizacji. To jeden z najprostszych sposobów odróżnienia awarii harmonogramu od błędu API.
- Sprawdź panel integracji i ostatni czas wykonania synchronizacji.
- Porównaj zachowanie synchronizacji ręcznej i automatycznej na jednym produkcie.
- Zweryfikuj, czy WP-Cron jest włączony i czy hosting nie wymaga crona systemowego.
- Sprawdź, czy w kolejce nie zalegają zadania z opóźnieniem lub błędem.
- Oceń, czy harmonogram nie jest ustawiony zbyt rzadko dla częstych zmian cen i stanów.
Na co uważać przy interpretacji objawów
Brak natychmiastowej aktualizacji nie zawsze oznacza, że synchronizacja nie działa. Czasem działa, ale z opóźnieniem wynikającym z harmonogramu, kolejki lub sposobu wywoływania cronów. Dopiero zestawienie czasu modyfikacji produktu, czasu uruchomienia zadania i wpisów w logach pokazuje, czy problem jest techniczny, czy tylko organizacyjny.
Jakie logi i komunikaty błędów dają najwięcej informacji diagnostycznej?
Najbardziej użyteczne są trzy źródła: logi WooCommerce, logi wtyczki integracyjnej oraz zapisy po stronie serwera lub crona. W praktyce szukaj nie tylko samego komunikatu o błędzie, ale też kodu odpowiedzi, identyfikatora żądania, treści odpowiedzi API i momentu, w którym zadanie zostało uruchomione. Te dane pozwalają odróżnić błąd autoryzacji od problemu walidacji albo od opóźnionej kolejki synchronizacji.
Co w logu ma największą wartość diagnostyczną
Jeżeli wpis zawiera kod 401, 403, 429 albo 5xx, od razu masz trop do warstwy API. Jeśli widzisz komunikat o brakującym polu, nieprawidłowym formacie albo odrzuceniu parametrów, problem zwykle leży w mapowaniu lub danych produktu. Z kolei informacja o braku uruchomienia zadania, pustej kolejce albo dużym opóźnieniu wskazuje na harmonogram synchronizacji.
Jak może wyglądać mylący przypadek
Na pierwszy rzut oka wszystko wygląda jak brak synchronizacji, bo oferta nie aktualizuje się w Allegro. Dopiero log pokazuje, że żądanie zostało wysłane, ale odpowiedź zawierała błąd walidacji wymaganego pola. To oznacza, że integracja działa, tylko blokuje ją niekompletne lub źle zmapowane dane.
Gdzie szukać i co porównywać
W praktyce warto zestawić czas modyfikacji produktu, czas uruchomienia zadania i ostatni wpis w logu. Jeśli ręczna synchronizacja przechodzi, a automatyczna nie zostawia śladu wykonania, problem jest po stronie cronów lub kolejki. Jeśli synchronizacja dochodzi do API, ale kończy się odrzuceniem danych, trop prowadzi do mapowania lub wymagań konkretnej kategorii Allegro.
Kiedy problem leży w danych produktu, a nie w integracji?
Zanim zaczniesz podejrzewać API albo harmonogram synchronizacji, sprawdź sam produkt. W integracji WooCommerce z Allegro to właśnie niepełne albo niespójne dane wejściowe najczęściej blokują publikację, psują warianty albo powodują odrzucenie aktualizacji mimo tego, że technicznie połączenie działa.
Najbardziej zdradliwe są sytuacje, w których oferta „idzie”, ale efekt w Allegro jest uboższy niż w sklepie. Produkt ma poprawną cenę i stan magazynowy, a mimo to znika opis, brakuje części parametrów albo oferta trafia do niewłaściwej kategorii. To zwykle oznacza problem z danymi produktu, nie z samym transportem danych.
Które pola warto zweryfikować jako pierwsze
- EAN i SKU, jeśli są wymagane przez kategorię lub reguły integracji.
- Atrybuty produktu i parametry obowiązkowe dla danej kategorii Allegro.
- Warianty, powiązania produktów i zgodność identyfikatorów.
- Stany magazynowe, cena brutto/netto oraz jednostki miary.
- Zdjęcia i opis HTML, jeśli wtyczka ogranicza sposób ich przenoszenia.
Sygnał ostrzegawczy
Jeśli Allegro przyjmuje ofertę, ale dane wyglądają na obcięte, puste albo niepasujące do kategorii, problem częściej leży w mapowaniu pól lub brakujących atrybutach niż w awarii synchronizacji. Sama obecność oferty nie jest dowodem, że wszystkie dane zostały poprawnie odwzorowane.
Typowy przypadek z praktyki
W WooCommerce produkt ma poprawną cenę, lecz w Allegro pojawia się bez pełnego opisu albo bez części parametrów. Po sprawdzeniu okazuje się, że wtyczka nie ma dopasowanego atrybutu wymaganego przez kategorię, więc oferta przechodzi tylko częściowo lub zostaje zwalidowana z ubytkiem danych.
Nie zakładaj, że winna jest integracja
Brak EAN, niezgodny wariant, błędna kategoria lub brak obowiązkowego parametru potrafią wyglądać jak awaria połączenia. W rzeczywistości integracja może działać poprawnie, tylko dane wejściowe nie spełniają wymagań Allegro dla konkretnej kategorii lub typu oferty.
Jak zbudować kolejność testów, żeby nie pomylić przyczyny z objawem?
Najlepsza diagnostyka integracji WooCommerce z Allegro zaczyna się od prostego odcinania zmiennych. Zamiast zgadywać, czy winne jest API, mapowanie danych czy harmonogram, sprawdzaj kolejne warstwy w tej samej kolejności i na możliwie małym zakresie, najlepiej na jednym produkcie.
- Uruchom ręczną synchronizację jednego, dobrze uzupełnionego produktu i sprawdź, czy przechodzi bez błędów.
- Porównaj wynik z synchronizacją automatyczną: jeśli ręczna działa, a automatyczna nie, problem zwykle leży w harmonogramie lub kolejce.
- Sprawdź logi dla tego samego produktu i tego samego przedziału czasu, zwracając uwagę na kod odpowiedzi, walidację pól i moment uruchomienia zadania.
- Przetestuj produkt z pełnym zestawem wymaganych danych, aby odróżnić błąd konfiguracji od braku pola obowiązkowego.
- Jeśli to możliwe, wykonaj próbę na środowisku testowym lub staging, a dopiero potem na produkcji.
Dlaczego jeden produkt mówi więcej niż cały katalog
Izolacja pojedynczego produktu pozwala szybko odciąć szum wynikający z wielu wyjątków naraz. Jeśli ten sam test przechodzi dla jednego towaru, a nie przechodzi dla innego, trop prowadzi do danych produktu albo mapowania. Jeśli nie przechodzi dla żadnego, bardziej prawdopodobny staje się problem po stronie API lub harmonogramu.
| Test | Co jeśli przechodzi | Co jeśli nie przechodzi |
|---|---|---|
| Ręczna synchronizacja jednego produktu | Integracja i API działają co najmniej na poziomie podstawowym | Problem leży w danych, mapowaniu albo kolejce/cronach |
| Automatyczna synchronizacja tego samego produktu | Harmonogram działa poprawnie | Trop prowadzi do WP-Cron, crona systemowego lub ustawień częstotliwości |
| Produkt z kompletem wymaganych danych | Walidacja po stronie Allegro powinna przepuścić ofertę | Brakuje pola, atrybutu, EAN, wariantu lub mapowania |
| Porównanie logów z czasem zmiany produktu | Łatwo związać zdarzenie z zadaniem synchronizacji | Trzeba sprawdzić, czy zadanie w ogóle zostało uruchomione |
Nie myl skutku z przyczyną
Najczęstszy błąd diagnostyczny to skupienie się wyłącznie na objawie, na przykład na braku aktualizacji w Allegro. Taki sam efekt może dawać odrzucone żądanie API, walidacja danych, błędne mapowanie albo opóźniona kolejka zadań. Dopiero porównanie testu ręcznego, automatycznego i logów pozwala wskazać właściwą warstwę awarii.
Co robić po każdym nieudanym teście
Po każdym kroku notuj trzy rzeczy: co zostało zmienione, jaki był wynik i czy w logu pojawił się kod błędu albo informacja o uruchomieniu zadania. Taki zapis oszczędza czas przy eskalacji do dostawcy wtyczki lub supportu Allegro, bo pokazuje, które warstwy zostały już wykluczone.
Jakie działania naprawcze zastosować po zidentyfikowaniu źródła błędu?
Gdy już wiesz, czy problem leży po stronie API, mapowania danych czy harmonogramu synchronizacji, naprawę warto prowadzić dokładnie w tej samej kolejności. Dzięki temu nie rozregulujesz działającej części integracji i szybciej zobaczysz, czy poprawka rzeczywiście usuwa przyczynę, a nie tylko maskuje objaw.
Jeśli źródłem problemu jest API, zacznij od odświeżenia autoryzacji i weryfikacji połączenia z Allegro. W praktyce chodzi o sprawdzenie, czy token nie wygasł, czy konto ma nadal wymagane uprawnienia oraz czy integracja nie trafia na błędy autoryzacji, limitów lub chwilową niedostępność usługi. Dopiero po wykluczeniu tych rzeczy ma sens ponawianie synchronizacji masowo.
Przy błędnym mapowaniu naprawa zwykle polega na dopasowaniu pól produktu do wymagań konkretnej kategorii Allegro. Warto skorygować SKU, EAN, atrybuty, warianty i przypisanie kategorii, a potem uruchomić ponowną synchronizację na jednym, dobrze uzupełnionym produkcie. Jeśli oferta zacznie przechodzić poprawnie, masz potwierdzenie, że problem był konfiguracyjny, a nie infrastrukturalny.
Gdy winny jest harmonogram, najważniejsze jest przywrócenie regularnego uruchamiania zadań i sprawdzenie, czy kolejka nie zalega po wcześniejszych błędach. W zależności od konfiguracji może to oznaczać korektę WP-Cron, crona systemowego, częstotliwości zadań albo ręczne ponowne kolejkowanie synchronizacji. Po zmianach porównaj czas modyfikacji produktu z czasem aktualizacji w Allegro, żeby upewnić się, że opóźnienie faktycznie zniknęło.
Kiedy eskalować problem
Jeśli po korekcie autoryzacji, mapowania i harmonogramu integracja nadal zachowuje się niestabilnie, warto zebrać logi, status ostatnich zadań i przykładowy produkt testowy, a następnie skontaktować się z dostawcą wtyczki lub wsparciem Allegro. Taki pakiet informacji pozwala szybciej odróżnić lokalny błąd konfiguracji od problemu po stronie usługi lub samego konektora.
Co warto zweryfikować po naprawie
Najlepiej sprawdzić jeszcze jedną rzecz: czy poprawka działa tylko dla jednego produktu, czy dla całego zestawu przypadków, które wcześniej sprawiały kłopot. Jeśli po zmianie mapowania lub harmonogramu synchronizacja nadal pomija wybrane oferty, problem może być częściowy i dotyczyć tylko konkretnej kategorii, wariantu albo zestawu wymaganych parametrów.
FAQ
Jak najszybciej sprawdzić, czy winne jest API, mapowanie czy harmonogram?
Najpierw zweryfikuj logi i status ostatnich synchronizacji: błędy autoryzacji lub odpowiedzi HTTP wskazują API, błędy walidacji i brakujące pola sugerują mapowanie, a brak uruchomień zadań albo duże opóźnienia wskazują harmonogram.
Czy ręczna synchronizacja może działać, gdy automatyczna nie działa?
Tak, to częsty sygnał problemu z harmonogramem lub kolejką zadań. Jeśli ręczna synchronizacja przechodzi, a automatyczna nie, warto sprawdzić WP-Cron, cron serwera i częstotliwość zadań.
Jak rozpoznać problem z mapowaniem ofert?
Najczęściej po niepełnych danych w Allegro: braku ceny, złej kategorii, brakujących atrybutów, nieprawidłowych wariantów albo odrzuceniu publikacji mimo poprawnego połączenia API.
Czy brak synchronizacji zawsze oznacza błąd po stronie integracji?
Nie. Czasem przyczyną są nieaktualne dane produktu, limity API, błędy walidacji w konkretnej kategorii albo opóźnienia po stronie harmonogramu.
Jakie logi są najważniejsze przy diagnostyce?
Najbardziej przydatne są logi wtyczki integracyjnej, logi WooCommerce, odpowiedzi API z kodami błędów, identyfikatory żądań oraz informacje o zadaniach cron i kolejkach.
Rafał Jóśko
Lokalizacja: Lublin
Pomagam firmom przejść przez chaos świata online. Z ponad 15-letnim doświadczeniem i ponad 360 zrealizowanymi projektami oferuję kompleksowe prowadzenie działań digital: od strategii, przez hosting, SEO i automatyzacje, aż po skuteczne kampanie marketingowe. Tworzę spójne procesy, koordynuję zespoły i eliminuję niepotrzebne koszty – Ty skupiasz się na biznesie, ja dbam o resztę.
Wspieram zarówno startupy, jak i rozwinięte firmy B2B/B2C. Działam z Lublina, ale efekty mojej pracy sięgają daleko poza granice Polski.