Jak naprawić synchronizację zamówień w PrestaShop? 

Zamówienie pojawia się w panelu PrestaShop, ale nie trafia do ERP? System magazynowy nie widzi nowej sprzedaży? Integracja z kurierem, fakturowaniem, marketplace albo Baselinkerem przestała odbierać dane? W sklepie internetowym to nie jest drobna niedogodność. To ryzyko opóźnionych wysyłek, pomyłek magazynowych, ręcznego przepisywania danych i rosnącej liczby pytań od klientów.

Dobra wiadomość jest taka, że problem z synchronizacją zamówień da się zwykle naprawić. Nie zaczynaj od losowego wyłączania modułów. Najpierw ustal, gdzie dokładnie znika zamówienie: w PrestaShop, w module integracyjnym, w zadaniu cron, w Webservice API, w statusach zamówień, w cache, w logach PHP czy po stronie zewnętrznego systemu.

W tym poradniku znajdziesz diagnostykę krok po kroku. Skupiamy się na praktyce: co sprawdzić, w jakiej kolejności, jakie błędy są najczęstsze i kiedy problem może wynikać z konfiguracji hostingu.

Czego dowiesz się z tego wpisu?

Co oznacza, że zamówienia się nie synchronizują?

Brak synchronizacji zamówień nie zawsze oznacza awarię PrestaShop. Czasem sklep działa poprawnie, a problem dotyczy tylko jednego kierunku przepływu danych. Zamówienie może być widoczne w panelu sklepu, ale nie przechodzi do programu magazynowego. Może przejść do ERP, ale bez pozycji produktowych. Może być eksportowane dopiero po zmianie statusu na opłacone. Może też utknąć w kolejce, bo zadanie cron nie uruchamia się od kilku godzin.

Najpierw nazwij dokładnie problem. To oszczędza czas, bo każda integracja działa trochę inaczej. Jedne moduły wysyłają zamówienie od razu po jego utworzeniu, inne dopiero po płatności, jeszcze inne cyklicznie pobierają dane przez API. W PrestaShop możesz mieć integracje z ERP, WMS, systemem księgowym, marketplace, kurierem, bramką płatności, narzędziem do obsługi zamówień lub własnym skryptem korzystającym z Webservice API.

Na tym etapie zanotuj trzy informacje: od kiedy problem występuje, czego dokładnie brakuje oraz czy dotyczy wszystkich zamówień, czy tylko części. Jeżeli błąd pojawił się po aktualizacji modułu, zmianie wersji PHP, migracji serwera, włączeniu cache lub zmianie statusów zamówień, masz już mocny trop.

Najpierw określ kierunek i zakres awarii

Nie diagnozuj synchronizacji od środka. Zacznij od mapy przepływu danych. Zamówienie może iść ze sklepu do zewnętrznego systemu, z marketplace do PrestaShop albo w obie strony. Każdy kierunek ma inne punkty kontroli.

• PrestaShop → ERP lub WMS. Sprawdź, czy zamówienie ma właściwy status, kompletne dane klienta, pozycje produktów, płatność, przewoźnika i adres dostawy.
• PrestaShop → system fakturowy. Zweryfikuj, czy integracja wymaga wygenerowanej faktury, statusu opłaconego albo numeru NIP.
• PrestaShop → kurier. Sprawdź mapowanie przewoźników, metod dostawy, gabarytów, punktów odbioru i numerów telefonu.
• Marketplace → PrestaShop. Upewnij się, że zewnętrzny system nadal ma dostęp do API, a produkty i warianty mają zgodne identyfikatory.
• PrestaShop → narzędzie typu integrator. Sprawdź kolejkę zadań, logi modułu i ostatni poprawny eksport.

Jeżeli problem dotyczy tylko zamówień z jednego kanału, np. tylko z Allegro, tylko z płatnością online albo tylko z dostawą do paczkomatu, przyczyną rzadko jest cały sklep. Szukaj w mapowaniu statusów, module płatności, module dostawy lub danych wymaganych przez dany system.

Dobrym ruchem jest porównanie dwóch zamówień: jednego, które zsynchronizowało się poprawnie, i drugiego, które utknęło. Sprawdź różnice w statusie, przewoźniku, metodzie płatności, kraju dostawy, walucie, wariantach produktów i rabatach. W praktyce bardzo często problem powoduje jedna wartość, której zewnętrzny system nie akceptuje.

Sprawdź cron i harmonogram zadań

Wiele integracji nie synchronizuje zamówień natychmiast. Zamiast tego działa cyklicznie: co minutę, co pięć minut, co godzinę albo w kilku niezależnych kolejkach. Za takie zadania odpowiada zwykle cron, czyli mechanizm uruchamiania zaplanowanych komend lub adresów URL na serwerze.

Jeżeli zamówienia przestały się synchronizować nagle, cron jest jednym z pierwszych miejsc do sprawdzenia. Wejdź w panel hostingu lub połącz się przez SSH i zweryfikuj, czy zadanie nadal istnieje, czy ma poprawną ścieżkę, czy uruchamia właściwą wersję PHP, czy nie zawiera starej domeny, nieaktualnego tokenu albo adresu środowiska testowego.

# Przykładowe tropy do sprawdzenia w zadaniu cron:
# - czy ścieżka do PHP jest aktualna
# - czy ścieżka do sklepu jest aktualna
# - czy URL integracji zwraca 200 OK, a nie 403, 404 lub 500
# - czy zadanie nie uruchamia się równolegle kilka razy
# - czy poprzednie wykonanie nie zostawiło pliku blokady

Uruchom zadanie ręcznie i sprawdź odpowiedź. Jeśli skrypt zwraca błąd 500, problem może być w PHP, module albo bazie danych. Jeśli zwraca 403, przyczyną bywa blokada po stronie WAF, reguł bezpieczeństwa, tokenu lub adresu IP. Jeśli zwraca 404, zwykle zmieniła się ścieżka, domena, katalog instalacji albo reguły przepisywania adresów.

Warto też pamiętać o zmianach w ekosystemie PrestaShop. Historyczna zewnętrzna usługa PrestaShop cron została wygaszona, dlatego integracje oparte na starym mechanizmie warto przenieść na natywne zadania cron na hostingu. Szczegóły techniczne dotyczące zadań cyklicznych opisuje oficjalna dokumentacja PrestaShop o zarządzaniu cronjobami, a kontekst wygaszenia starej usługi znajdziesz w komunikacie Sunsetting the PrestaShop cron service.

Zweryfikuj Webservice API i uprawnienia

Jeżeli zewnętrzny system pobiera zamówienia przez API, sprawdź Webservice API w PrestaShop. Oficjalna dokumentacja opisuje, że Webservice daje zewnętrznym narzędziom dostęp do danych sklepu przez API typu CRUD. W praktyce oznacza to, że integrator może odczytywać, tworzyć, aktualizować lub usuwać zasoby, o ile klucz API ma odpowiednie uprawnienia.

W panelu PrestaShop przejdź do ustawień Webservice i upewnij się, że API jest włączone. Następnie sprawdź klucz wykorzystywany przez integrację. Klucz powinien mieć tylko te uprawnienia, których naprawdę potrzebuje, ale przy synchronizacji zamówień zwykle sam zasób orders nie wystarcza. Często potrzebne są także order_details, order_states, customers, addresses, carts, carriers, order_payments lub order_invoices.

• Jeśli integracja zwraca 401, sprawdź klucz API i sposób autoryzacji.
• Jeśli zwraca 403, sprawdź uprawnienia klucza, blokady IP, WAF i reguły bezpieczeństwa.
• Jeśli zwraca 404, sprawdź adres API, katalog instalacji i reguły przepisywania.
• Jeśli zwraca 500, sprawdź logi PHP, logi PrestaShop i zgodność modułu z wersją sklepu.

Najprostszy test to wejście na endpoint API zgodnie z dokumentacją PrestaShop: Testing access to the Webservice. W produkcyjnym sklepie nie przekazuj klucza API w adresie URL. Bezpieczniej używać nagłówka autoryzacji, bo klucz w URL może trafić do historii przeglądarki, logów lub narzędzi analitycznych.

# Przykładowy bezpieczniejszy kierunek testu:
# 1. sprawdź /api/
# 2. sprawdź /api/orders
# 3. sprawdź jedno konkretne zamówienie
# 4. sprawdź, czy integracja pobiera też order_details
# 5. porównaj odpowiedź API z tym, co widzisz w panelu PrestaShop

Jeżeli masz włączony Multistore, sprawdź również kontekst sklepu. PrestaShop obsługuje scenariusze, w których dane są przypisane do konkretnego sklepu lub grupy sklepów. Integracja może widzieć zamówienia z jednego sklepu, a pomijać zamówienia z drugiego, jeśli nie obsługuje poprawnie identyfikatora sklepu.

Przy większych sklepach unikaj pobierania wszystkiego naraz. Zamiast pełnego eksportu wszystkich zamówień stosuj filtry po dacie, limity, paginację i pobieranie zmian od ostatniego poprawnego przebiegu. To zmniejsza ryzyko timeoutów, zduplikowanych zamówień i obciążenia bazy danych.

Statusy zamówień, płatności i przewoźnicy

Bardzo częstą przyczyną problemów jest mapowanie statusów. Właściciel sklepu widzi zamówienie i zakłada, że powinno już pójść dalej. Integracja działa jednak według własnych reguł. Może eksportować wyłącznie zamówienia opłacone, wyłącznie zamówienia z fakturą, wyłącznie zamówienia z konkretnym przewoźnikiem albo tylko te, które mają status oznaczony jako płatny.

Sprawdź, czy w ostatnim czasie nie zmieniły się nazwy lub identyfikatory statusów. Dla człowieka status Płatność zaakceptowana i Opłacone może brzmieć podobnie, ale dla modułu to często dwa różne ID. Jeśli integracja ma zapisane stare ID statusu, nowo utworzone statusy mogą zostać całkowicie pominięte.

W dokumentacji PrestaShop znajdziesz osobny zasób order_states. To ważne, bo statusy nie są wyłącznie etykietami w panelu. Mogą mieć znaczenie dla faktur, wysyłek, maili, płatności, logiki modułów i eksportu danych.

Po aktualizacji PrestaShop lub modułów szczególnie uważnie sprawdzaj integracje dotykające zamówień, rabatów i wysyłek. PrestaShop 9.1 wprowadza m.in. nowe podejście do wysyłek wielopaczkowych i systemu rabatów jako funkcje eksperymentalne. Jeśli testujesz je na sklepie produkcyjnym lub środowisku stagingowym, upewnij się, że moduły ERP, kurierskie i marketplace rozumieją nową strukturę danych. Więcej o zmianach w tej wersji przeczytasz w artykule o PrestaShop 9.1.

Logi, debug i test na kopii sklepu

Jeśli nie widzisz przyczyny w statusach, cronie ani API, czas na logi. Sprawdź logi modułu integracyjnego, logi PrestaShop, logi PHP oraz logi serwera. Szukaj błędów typu fatal error, timeout, permission denied, memory exhausted, invalid token, SQL error, SSL error, 401, 403, 404 i 500.

Tryb debugowania pomaga zobaczyć błędy, które normalnie są ukryte. PrestaShop pozwala sprawdzać i przełączać debug z poziomu konsoli komendą prestashop:debug. W starszych lub typowych wdrożeniach spotkasz też konfigurację w pliku config/defines.inc.php.

// Przykładowy trop w config/defines.inc.php
define('_PS_MODE_DEV_', true);

Nie zostawiaj debugowania włączonego publicznie na produkcji. Komunikaty błędów mogą ujawniać ścieżki plików, nazwy modułów lub fragmenty konfiguracji. Najbezpieczniej odtworzyć problem na kopii sklepu, zwłaszcza jeśli będziesz wyłączać moduły, zmieniać wersję PHP albo testować aktualizacje.

Jeśli problem objawia się białą stroną, błędem 500 albo brakiem odpowiedzi panelu, pomocny będzie poradnik Biała strona w PrestaShop? Poznaj skuteczne rozwiązania. Choć dotyczy widocznej awarii sklepu, opisane tam podejście do debugowania przydaje się także przy integracjach, bo synchronizacja zamówień często psuje się przez ten sam typ błędu PHP, konflikt modułu albo problem z cache.

Na kopii sklepu wykonaj prosty test: utwórz zamówienie testowe, przeprowadź je przez statusy, uruchom ręcznie cron, sprawdź odpowiedź API i porównaj logi. Jeżeli na kopii działa, a na produkcji nie, różnicy szukaj w konfiguracji środowiska, adresach URL, certyfikacie SSL, zaporze, limicie czasu wykonania lub dostępie z zewnętrznego IP.

Cache, wydajność i limity serwera

Synchronizacja zamówień kojarzy się głównie z API, ale wydajność serwera ma bardzo praktyczne znaczenie. Jeśli sklep ma dużą bazę zamówień, dużo wariantów, rozbudowane moduły i wiele integracji, eksport danych może przekraczać limit czasu wykonania, pamięci PHP albo dopuszczalną liczbę równoległych procesów.

Sprawdź, czy problem pojawia się przy wszystkich zamówieniach, czy tylko przy większych koszykach. Zamówienie z wieloma pozycjami, rabatami, kilkoma paczkami i dodatkowymi polami może być trudniejsze do przetworzenia niż proste zamówienie na jeden produkt.

Wyczyść cache PrestaShop i cache modułu integracyjnego. Jeżeli korzystasz z kilku mechanizmów cache naraz, sprawdź, czy nie dublują się ich zadania. Przy API upewnij się, że endpointy integracyjne nie są przypadkowo cache’owane przez dodatkowy moduł, reguły serwera lub zewnętrzną warstwę optymalizacji.

Na hostingu PrestaShop w cyber_Folks sklep korzysta ze środowiska projektowanego pod wydajność e-commerce, m.in. z LiteSpeed, Redis, dysków NVMe, HTTP/3, dostępem SSH oraz rozwiązaniami cyber_Boost. Dla synchronizacji ma to znaczenie, bo zadania integracyjne często działają w tle, wykonują zapytania do bazy i przetwarzają dane w momentach, gdy sklep jednocześnie obsługuje klientów.

Jeśli chcesz lepiej zrozumieć, jak działa autorski moduł optymalizacyjny, przeczytaj PrestaShop z cyber_Boost – co to jest i dlaczego warto włączyć?. Przy problemach z synchronizacją nie traktuj optymalizacji jako magicznego przycisku naprawy, ale jako element stabilnego środowiska: uporządkowana baza, sensowny cache i automatyczne zadania zmniejszają liczbę miejsc, w których integracja może się potknąć.

Aktualizacje modułów i bezpieczne wdrożenia

Problemy z synchronizacją bardzo często pojawiają się po aktualizacji. Powód jest prosty: integracje są wrażliwe na strukturę danych, wersję PHP, hooki PrestaShop, statusy zamówień i zależności między modułami. Aktualizacja samego sklepu może być poprawna, ale jeden moduł integracyjny może jeszcze nie obsługiwać nowej wersji.

Przed aktualizacją zrób kopię plików i bazy danych, sprawdź changelog modułów i wykonaj test na stagingu. Szczególnie ostrożnie podchodź do modułów płatności, wysyłek, fakturowania, ERP, marketplace i importu/eksportu produktów. To one najczęściej uczestniczą w przepływie zamówienia od kliknięcia Kupuję do wysłania paczki.

Po aktualizacji wykonaj test kontrolny, a nie tylko sprawdzenie frontu sklepu. Utwórz zamówienie, opłać je metodą testową, zmień status, wygeneruj dokument sprzedaży, wyślij do kuriera i sprawdź, czy zewnętrzny system otrzymał komplet danych. Warto mieć stałą procedurę po każdej zmianie, nawet jeśli aktualizujesz tylko jeden moduł.

Jeżeli dopiero konfigurujesz sklep albo porządkujesz jego ustawienia po wdrożeniu, pomocny będzie artykuł dotyczący konfiguracji PrestaShop. Dobrze ustawione podstawy sklepu zmniejszają ryzyko, że integracja będzie dostawać niepełne dane o klientach, płatnościach, dostawach lub walutach.

Lista kontrolna po naprawie synchronizacji

Gdy znajdziesz przyczynę i wprowadzisz poprawkę, nie kończ pracy po jednym udanym eksporcie. Synchronizacja zamówień to proces, który musi działać powtarzalnie. Sprawdź kilka scenariuszy, bo integracja może poprawnie obsłużyć proste zamówienie, ale zatrzymać się na zamówieniu z rabatem, odbiorem w punkcie albo płatnością odroczoną.

• Utwórz zamówienie testowe z jedną pozycją i sprawdź pełny przepływ.
• Utwórz zamówienie z kilkoma produktami, wariantami i rabatem.
• Sprawdź zamówienie z każdą popularną metodą płatności.
• Sprawdź co najmniej dwóch przewoźników lub dwie metody dostawy.
• Uruchom cron ręcznie i poczekaj na kolejne automatyczne wykonanie.
• Porównaj dane w PrestaShop i w systemie zewnętrznym: produkty, ilości, ceny, VAT, adresy, statusy, płatność.
• Sprawdź, czy integracja nie zdublowała zamówień po ponownym uruchomieniu.
• Przejrzyj logi po 24 godzinach od naprawy.

Po naprawie warto też uporządkować bezpieczeństwo. Jeśli klucz API był testowany w wielu miejscach, wygeneruj nowy. Nadaj mu minimalne potrzebne uprawnienia, opisz do czego służy i nie używaj jednego klucza do wszystkich integracji. Jeśli zewnętrzny system pozwala ograniczyć dostęp po IP, rozważ taką konfigurację.

Przy większych sklepach opłaca się prowadzić prosty rejestr integracji: nazwa modułu, cel, kierunek synchronizacji, metoda techniczna, częstotliwość crona, osoba odpowiedzialna, ostatnia aktualizacja i miejsce logów. Kiedy pojawi się kolejny problem, nie zaczynasz od zera.

Kiedy problem może wynikać z hostingu?

Nie każdy błąd synchronizacji jest winą hostingu, ale środowisko serwerowe może zdecydować, czy integracja działa stabilnie. Hosting ma znaczenie, gdy zadania cron nie uruchamiają się poprawnie, skrypty przekraczają limity czasu, API odpowiada zbyt wolno, baza danych jest przeciążona, a większe paczki danych kończą się błędami.

Dla PrestaShop ważne są zwłaszcza: dostęp do odpowiedniej wersji PHP, możliwość pracy przez SSH, stabilne zadania cron, wydajna baza danych, szybki dysk, dobre kopie zapasowe i sensowne mechanizmy bezpieczeństwa. Przy sklepie internetowym kopia bazy nie jest dodatkiem. To zabezpieczenie przed utratą zamówień, zwłaszcza gdy naprawa wymaga cofnięcia zmian w module lub bazie.

W ofercie hostingu PrestaShop cyber_Folks znajdziesz m.in. technologie przyspieszające sklep, kopie zapasowe baz zamówień wykonywane co 6 godzin i dostępne do 28 dni wstecz, WAF, Redis, LiteSpeed Cache, NVMe oraz możliwość pracy przez SSH. To elementy, które pomagają nie tylko w szybkości frontu, ale też w utrzymaniu stabilnego zaplecza integracji.

Jeśli problem wraca przy większym ruchu, w godzinach szczytu albo podczas masowego importu produktów, potraktuj to jako sygnał do przeglądu zasobów. Synchronizacja zamówień konkuruje wtedy o zasoby z klientami przeglądającymi sklep, botami, płatnościami, wyszukiwarką, panelem administracyjnym i innymi cronami.

Jak uniknąć kolejnych problemów z synchronizacją?

Gdy zamówienia w PrestaShop się nie synchronizują, najgorszą strategią jest chaotyczne klikanie po panelu. Najlepszą jest prosta kolejność: ustal kierunek synchronizacji, sprawdź zakres awarii, zweryfikuj cron, API, statusy, logi, cache, aktualizacje i środowisko serwerowe. Dopiero wtedy wiesz, czy problem leży w module, konfiguracji sklepu, zewnętrznym systemie czy hostingu.

W sklepie internetowym synchronizacja zamówień jest częścią procesu sprzedaży, a nie dodatkiem technicznym. Jeśli działa stabilnie, zespół obsługuje zamówienia szybciej, klienci dostają paczki na czas, a Ty masz mniej ręcznej pracy. Jeśli działa niestabilnie, nawet świetny sklep zaczyna generować koszty operacyjne.

Dlatego oprócz naprawy pojedynczego błędu zadbaj o fundamenty: aktualne moduły, testy na stagingu, czytelne logi, bezpieczne klucze API, poprawnie działające crony i hosting dopasowany do PrestaShop. Chcesz prowadzić sklep na środowisku przygotowanym pod wydajność, bezpieczeństwo i codzienną pracę e-commerce?