Najczęstsze problemy integracji w PrestaShop - ilustracja połączeń między sklepem a systemami zewnętrznymi

Integracja PrestaShop – najczęstsze problemy: jak je rozpoznać i skutecznie rozwiązać

Klient klika „Zapłać”, przechodzi przez Przelewy24, wraca do sklepu z komunikatem o udanej płatności, a status zamówienia w panelu PrestaShop nadal pokazuje „Oczekuje na płatność”. Albo inny scenariusz: paczka od trzech dni jest już odebrana z paczkomatu, a stan magazynowy w sklepie wciąż pokazuje ten sam produkt jako dostępny na Allegro i w dwóch kolejnych kanałach sprzedaży.  Z perspektywy klienta jest to po prostu awaria sklepu. Technicznie jednak problem nie musi dotyczyć samego PrestaShop, lecz jednej z integracji odpowiedzialnych za wymianę danych między sklepem a systemem płatności, magazynem lub zewnętrznymi kanałami sprzedaży. Najczęściej nikt nie zauważa błędu, dopóki nie zgłosi go zaniepokojony klient albo nie dojdzie do sprzedaży produktu, którego faktycznie nie ma już na stanie.

PrestaShop rzadko działa w pojedynkę. Rozwijający się sklep łączy się zwykle z bramką płatności, kurierem lub siecią paczkomatów, kontem sprzedażowym na Allegro, systemem do zarządzania sprzedażą wielokanałową, a czasem także z hurtownią dostarczającą towar w modelu dropshipping. Wymiana danych może odbywać się przez API, ale również za pomocą plików XML lub CSV, ponieważ nie każdy dostawca udostępnia jeszcze bezpośrednią integrację API. Każde z tych połączeń działa według własnych zasad, limitów, harmonogramów aktualizacji i formatów danych, niezależnie od tego, kiedy aktualizowany jest sam silnik sklepu. Pisaliśmy już o tym, jak aktualizacja PrestaShop potrafi zerwać działającą integrację z dnia na dzień. Tym razem patrzymy na temat szerzej: nie tylko na to, co dzieje się z integracjami po aktualizacji silnika. Patrzymy na cały ich cykl życia, od pierwszego wdrożenia, przez codzienną pracę, po sytuacje, w których to dostawca zewnętrznej usługi zmienia zasady gry bez pytania kogokolwiek o zdanie.

Dlaczego integracje w PrestaShop bywają zawodne

PrestaShop udostępnia wbudowane Webservice API oparte na protokole HTTP, które pozwala zewnętrznym systemom odczytywać i modyfikować wybrane dane sklepu, między innymi informacje o produktach, zamówieniach, klientach czy stanach magazynowych. Jest to jednak tylko jeden z możliwych sposobów integracji.

Moduły płatności, systemy kurierskie, platformy sprzedażowe i inne zewnętrzne narzędzia mogą komunikować się ze sklepem także za pomocą własnych API, webhooków, dedykowanych modułów, plików XML lub CSV oraz innych mechanizmów wymiany danych. Każde z tych rozwiązań działa według odrębnych zasad, ma własne ograniczenia i może być rozwijane niezależnie od samego PrestaShop. Dlatego nawet poprawnie działający sklep może napotkać problemy, gdy zmiana pojawi się po stronie jednego z połączonych systemów.

W praktyce większość problemów integracyjnych sprowadza się do kilku powtarzających się przyczyn. Klucz API lub token dostępowy może zostać unieważniony, błędnie skonfigurowany albo stracić wymagane uprawnienia, a integracja nie zawsze zgłasza wtedy czytelny komunikat o błędzie. Zewnętrzny system nakłada limit liczby zapytań na minutę i po jego przekroczeniu tymczasowo blokuje komunikację. Dane przesyłane między systemami mają inny format czy inną strukturę pól. Coś, co po jednej stronie wygląda poprawnie, po drugiej zostaje odrzucone albo błędnie zinterpretowane.

Systemy komunikują się asynchronicznie, więc między zmianą statusu a jej odzwierciedleniem w sklepie mija czas, w którym mogą powstać rozbieżności. Do tego dochodzi naturalny fakt, że dostawcy zewnętrznych usług rozwijają swoje API według własnego harmonogramu. Mogą wprowadzać zmiany psujące dotychczasową integrację, nawet jeśli sam PrestaShop pozostaje bez zmian. Część integracji korzysta też z hooków PrestaShop, czyli punktów w kodzie, do których podpinają się poszczególne moduły. Zmiana działania hooka po aktualizacji silnika potrafi zerwać integrację bez żadnej zmiany po stronie zewnętrznego dostawcy.

Skala problemu rośnie razem z liczbą kanałów sprzedaży. Sklep, który oprócz własnej platformy prowadzi sprzedaż na Allegro, korzysta z panelu do zarządzania zamówieniami i wysyła paczki przez kilku kurierów, ma po prostu więcej ruchomych elementów niż sklep obsługujący wyłącznie własną domenę. To samo dotyczy sklepów działających w trybie multistore, gdzie każdy z prowadzonych sklepów może wymagać osobnej konfiguracji tych samych integracji płatniczych i logistycznych. Nic dziwnego, że polscy konsumenci coraz częściej kupują w wielu kanałach jednocześnie, łącząc zakupy na marketplace’ach, we własnych sklepach internetowych i w aplikacjach mobilnych. Rosnąca wielokanałowość oznacza więcej integracji do utrzymania.

Najczęstsze problemy integracji w PrestaShop według obszaru

Integracje płatności: Przelewy24, PayNow i Tpay

Największym zagrożeniem przy integracjach płatniczych nie jest sama płatność, tylko moment, w którym informacja o niej wraca do sklepu. Przelewy24, PayNow i Tpay działają w podobnym modelu. Klient płaci na stronie operatora, a operator wysyła do sklepu asynchroniczne powiadomienie na wcześniej skonfigurowany adres, informujące o zmianie statusu transakcji. Jeśli to powiadomienie z jakiegokolwiek powodu nie dotrze albo nie zostanie poprawnie przetworzone, zamówienie w PrestaShop może pozostać nieopłacone, mimo że pieniądze faktycznie trafiły do operatora płatności.

W przypadku Przelewy24 mechanizm jest wprost opisany w dokumentacji: po zaksięgowaniu wpłaty system wysyła powiadomienie na skonfigurowany adres, a sklep powinien następnie przesłać żądanie weryfikacji transakcji. Dopiero pozytywna odpowiedź na to żądanie potwierdza, że płatność została prawidłowo zrealizowana i może zostać przypisana do zamówienia. Jeżeli weryfikacja nie dojdzie do skutku, klient może widzieć informację o udanej płatności, podczas gdy status zamówienia w PrestaShop nadal pozostaje niezmieniony. Najczęstsze przyczyny takiej sytuacji to nieaktualny lub błędnie skonfigurowany adres powiadomień po migracji sklepu, nieprawidłowe dane konfiguracyjne, pomieszanie środowiska produkcyjnego z testowym albo błąd po stronie modułu odpowiedzialnego za odbiór i weryfikację płatności. Problem może pojawić się również wtedy, gdy serwer sklepu nie odpowie prawidłowo na powiadomienie operatora lub proces weryfikacji transakcji zostanie przerwany.

PayNow działa podobnie, z jedną istotną różnicą. Jeśli sklep jest chwilowo niedostępny w momencie wysyłki powiadomienia, system automatycznie ponawia próbę jego dostarczenia według określonego harmonogramu. Kolejne próby są wykonywane najpierw w krótkich odstępach, a następnie coraz rzadziej. Dokumentacja przewiduje między innymi ponowienie powiadomienia po 48 godzinach. To daje sklepowi spory margines bezpieczeństwa, ale też oznacza, że problem z odbieraniem powiadomień może pozostać niezauważony przez dłuższy czas. Dzieje się tak jeśli nikt nie sprawdza logów komunikacji w panelu sprzedawcy.

Tpay obsługuje rozbieżności w kwotach w zależności od rodzaju płatności i ustawień konta sprzedawcy. W przypadku nadpłaty system wysyła do sklepu powiadomienie z odpowiednim statusem, dzięki czemu integracja może prawidłowo rozpoznać taką transakcję. Podobnie dzieje się przy niedopłacie mieszczącej się w ustawionym progu akceptacji.

Inaczej wygląda sytuacja, gdy klient wpłaci zbyt małą kwotę, która przekracza dopuszczalny próg niedopłaty. Wtedy Tpay nie wysyła powiadomienia do sklepu, lecz przekazuje klientowi link umożliwiający dopłatę brakujących środków. Zamówienie może więc pozostać w statusie oczekującym do momentu uzupełnienia kwoty albo ręcznego zaakceptowania lub zwrócenia transakcji przez sprzedawcę.

Osobną kwestią jest weryfikacja autentyczności samego powiadomienia, czy to przez sumę kontrolną w Przelewy24, czy podpis JWS w Tpay. Pominięcie tego kroku otwiera furtkę do sfałszowanych zgłoszeń o rzekomo zaksięgowanej płatności, których integracja nie ma jak odróżnić od prawdziwych.

Integracje logistyczne: InPost i kurierzy

Problemy z integracjami logistycznymi nie ograniczają się do wyboru punktu odbioru czy generowania etykiety. Często wynikają z nieprawidłowych lub niepełnych danych przekazywanych z produktu i zamówienia, na przykład błędnego formatu adresu, kodu pocztowego albo numeru telefonu. Źródłem problemu mogą być również źle zarządzane feedy produktowe, konflikty z innymi modułami modyfikującymi dane oraz nowe statusy płatności, których integracja logistyczna nie uwzględnia jeszcze w swojej logice. W efekcie zamówienie może nie zostać prawidłowo przekazane do przewoźnika, mimo że w samym sklepie wygląda na kompletne. InPost obsługuje usługi kurierskie, paczkomatowe oraz przesyłki realizowane w ramach Allegro za pośrednictwem zintegrowanej platformy ShipX API, której mechanizm autoryzacji opiera się na standardzie OAuth 2.0. Starsze integracje, napisane jeszcze pod poprzednie, oddzielne API do obsługi paczkomatów, tracą wsparcie. Sklepy, które nie aktualizowały modułu kurierskiego od dłuższego czasu, mogą się o tym przekonać dopiero wtedy, gdy nadawanie przesyłek nagle przestanie działać.

Dostęp do API ShipX trzeba uzyskać osobno. Samo posiadanie konta na paczkomaty.pl nie wystarczy, więc pierwszym częstym problemem bywa zwyczajnie brak właściwych danych dostępowych, identyfikatora organizacji i tokenu, poprawnie skonfigurowanych w module sklepu. Drugim elementem integracji jest widget do wyboru paczkomatu w koszyku, czyli tak zwany geowidget. To frontendowa część całego rozwiązania integracyjnego, odpowiedzialna za wyświetlenie mapy i przekazanie wybranego punktu odbioru do zamówienia. Ponieważ działa bezpośrednio na stronie sklepu, na jego poprawne funkcjonowanie mogą wpływać również zmiany w motywie, konflikty z innymi skryptami lub błędy JavaScript. Są to między innymi: konflikt z inną biblioteką JS, blokada w polityce bezpieczeństwa treści albo agresywny cache strony serwowanej z pamięci podręcznej sprzed aktualizacji frontendu. Klient widzi wtedy checkout bez możliwości wyboru paczkomatu, mimo że backendowa integracja z InPost formalnie działa poprawnie.

Integracje z firmami kurierskimi, takimi jak DPD, działają na zbliżonej zasadzie. Do wygenerowania etykiety potrzebny jest token dostępowy, dane adresowe muszą zostać przekazane w określonym formacie, a informacje o statusie przesyłki są zwracane do sklepu za pośrednictwem API. W zależności od wykorzystywanego API i sposobu działania integracji limity wagowe oraz gabarytowe mogą być weryfikowane na różnych etapach obsługi zamówienia. Jeśli dane nie zostaną sprawdzone wcześniej, problem może ujawnić się dopiero podczas generowania etykiety lub nadawania przesyłki, a nie w momencie składania zamówienia przez klienta.

Integracja PrestaShop z Allegro

Allegro to najbardziej rozbudowana integracja spośród opisywanych tutaj, bo w grę wchodzi jednocześnie synchronizacja ofert, cen, stanów magazynowych i zamówień, a całość opiera się na REST API zabezpieczonym protokołem OAuth 2.0. Zgodnie z dokumentacją Allegro Developer Portal token dostępu może stracić ważność z kilku powodów niezwiązanych bezpośrednio z samą integracją: wylogowania się sprzedawcy ze wszystkich urządzeń, zmiany hasła, zmiany adresu e-mail, zablokowania sprzedaży albo przekroczenia limitu dwudziestu jednocześnie aktywnych sesji. Integracja, która nie obsługuje poprawnie odświeżania tokenu w takich sytuacjach, po prostu przestaje synchronizować dane, często bez czytelnego komunikatu o przyczynie.

Do tego dochodzą limity zapytań. Dla jednego Client ID Allegro dopuszcza maksymalnie 9000 zapytań na minutę, a dodatkowo stosuje mechanizm ograniczający liczbę wywołań wykonywanych w imieniu pojedynczego użytkownika. Po przekroczeniu limitu API odpowiada błędem 429 Too Many Requests, a integracja wysyłająca zbyt wiele zapytań naraz, na przykład podczas hurtowej aktualizacji cen całego katalogu, może zostać czasowo zablokowana.

Osobną pułapką jest sposób działania operacji na ofertach. Zmiana ceny czy aktywacja wielu ofert jednocześnie odbywa się asynchronicznie: żądanie od razu zwraca odpowiedź, ale bez informacji o faktycznym rezultacie, który trzeba sprawdzić osobnym zapytaniem o status zadania. Integracja napisana z założeniem, że taka operacja kończy się natychmiast, może błędnie uznać, że cena została zaktualizowana, podczas gdy zadanie w tle jeszcze się nie zakończyło albo zakończyło się błędem.

Dobrze też wiedzieć, że automatyczna, częsta zmiana ceny oferty przez zewnętrzny system integrujący może wykluczyć ją z udziału w kampanii promocyjnej albo w programie Allegro Ceny, jeśli te mechanizmy również zarządzają ceną tej samej oferty. To rzadko widać na pierwszy rzut oka: oferta wygląda na aktywną i poprawnie skonfigurowaną, ale przestaje brać udział w promocji, z której sprzedawca liczył na dodatkowy ruch. Zdarzenia dotyczące zamówień mogą z kolei docierać w nieoczekiwanej kolejności albo się duplikować, dlatego dobra integracja powinna opierać się na numerze wersji zamówienia, a nie zakładać, że każde zdarzenie przyjdzie dokładnie raz i we właściwej kolejności.

Integracja PrestaShop z Base i innymi systemami ERP

Base i podobne systemy do zarządzania sprzedażą wielokanałową pełnią rolę centrum, które odbiera zamówienia z PrestaShop i innych kanałów, synchronizuje stany magazynowe i ceny, a następnie odsyła do sklepu numery przesyłek i statusy realizacji. Komunikacja odbywa się przez REST API zabezpieczone tokenem przypisanym do konta użytkownika, a oficjalna dokumentacja Base’a jasno określa limit: sto zapytań na minutę dla jednego tokenu. W praktyce oznacza to, że wszystkie integracje korzystające z tego samego klucza, sklep, dodatek księgowy czy aplikacja do rozpoznawania dzwoniących klientów, dzielą jeden wspólny limit. Przy większym sklepie albo przy kilku równolegle działających integracjach limit bywa przekraczany, co skutkuje czasową blokadą dostępu do API i wstrzymaniem pobierania zamówień oraz aktualizacji stanów.

Drugim źródłem problemów może być sposób zaprojektowania synchronizacji stanów magazynowych. W zależności od konfiguracji integracji dane mogą być aktualizowane jedno- lub dwukierunkowo, w czasie rzeczywistym albo w określonych odstępach. Jeśli kilka systemów może jednocześnie zmieniać stan produktu, a aktualizacja nie następuje natychmiast, może dojść do chwilowej rozbieżności. Przy produktach o dużej rotacji, sprzedawanych w kilku kanałach, taka różnica może doprowadzić do sprzedaży towaru, którego fizycznie nie ma już w magazynie.

Do tego dochodzą różnice w mapowaniu statusów zamówień oraz sposobów dostawy i płatności między systemami. Status, który w Base oznacza spakowane zamówienie, musi zostać poprawnie przetłumaczony na odpowiedni status w PrestaShop, a jeśli mapowanie zostało skonfigurowane niedokładnie albo ktoś dodał nowy status po jednej stronie bez aktualizacji integracji po drugiej, zamówienia zaczynają utykać w niewłaściwym miejscu procesu.

Integracja PrestaShop z hurtowniami i dropshipping

Integracje z hurtowniami różnią się od pozostałych tym, że rzadko istnieje jeden, ujednolicony standard. Zamiast tego sklep otrzymuje plik XML, CSV albo dostęp do API hurtowni, z własną, indywidualną strukturą pól, którą trzeba zmapować na strukturę produktów w PrestaShop: kategorie, cechy, atrybuty, producentów i jednostki miary. Sam import uruchamia się zwykle cyklicznie w tle, poprzez zadanie harmonogramu typu cron, a nie ręcznie po każdej zmianie oferty hurtowni.

Najczęstszy problem pojawia się już na etapie mapowania kategorii. Struktura kategorii w pliku hurtowni prawie nigdy nie pokrywa się jeden do jednego ze strukturą kategorii sklepu, a produkt bez przypisanej kategorii docelowej zostaje albo pominięty przy imporcie, albo trafia do kategorii zbiorczej, z której nikt go później nie wyciąga. Drugim problemem jest sposób naliczania marży. Import z hurtowni powinien przeliczać cenę zakupu na cenę sprzedaży według ustalonych reguł, jednolitego narzutu, marży zależnej od kategorii czy producenta, a błąd w tej konfiguracji potrafi przez dłuższy czas sprzedawać produkty poniżej kosztu, zanim ktokolwiek to zauważy przy okazji analizy marżowości.

Trzeci obszar to synchronizacja stanów magazynowych w czasie, gdy hurtownia aktualizuje swój plik raz czy dwa razy dziennie, a nie w czasie rzeczywistym. Produkt, który wyprzedał się u dostawcy tuż po ostatniej synchronizacji, przez wiele godzin nadal widnieje jako dostępny w sklepie, co prowadzi do zamówień niemożliwych do zrealizowania w deklarowanym terminie. Dochodzi do tego ryzyko czysto techniczne: pliki od polskich hurtowni bywają zapisane w kodowaniu Windows-1250 zamiast UTF-8, co przy niepoprawnej konfiguracji importu psuje polskie znaki diakrytyczne w nazwach i opisach produktów. Automatyczny import bez odpowiednich zabezpieczeń potrafi też nadpisać ręcznie zoptymalizowane pod SEO opisy produktów standardowymi danymi od dostawcy.

Jak zapobiegać problemom integracji w PrestaShop

Większości opisanych wyżej sytuacji można zapobiec, traktując integracje jako stały element utrzymania sklepu, a nie jednorazowe zadanie zamknięte w dniu wdrożenia.

Na etapie wdrożenia nowej integracji warto:

W codziennej pracy z już działającymi integracjami warto:

Jeśli sklep korzysta jednocześnie z kilku integracji, dobrym nawykiem jest prowadzenie prostego rejestru: jakie systemy są podłączone, kto po stronie dostawcy odpowiada za wsparcie techniczne i kiedy integracja była ostatnio testowana. Taki rejestr wymaga niewiele pracy, a znacząco skraca czas diagnozy w momencie, gdy coś faktycznie się zepsuje.

Najczęściej zadawane pytania o integracje PrestaShop

Dlaczego integracja przestaje działać, mimo że nikt nic nie zmieniał w sklepie? Najczęściej dlatego, że zmiana nastąpiła po drugiej stronie integracji, u zewnętrznego dostawcy. Allegro, InPost, bramka płatności czy Base aktualizują swoje API według własnego harmonogramu, niezależnego od PrestaShop. Token dostępowy mógł też stracić ważność z przyczyn niezwiązanych z samą integracją, na przykład po zmianie hasła do konta u dostawcy usługi.

Czy integracje płatności trzeba sprawdzać osobno po każdej aktualizacji PrestaShop? Tak. Moduły płatności często korzystają z hooków, które mogą zmienić działanie po aktualizacji silnika, dlatego pełne przejście przez proces zakupowy z użyciem każdej dostępnej metody płatności powinno być standardowym krokiem po każdej aktualizacji, nie tylko przy dużych migracjach.

Jak rozpoznać, że problem leży po stronie integracji, a nie samego PrestaShop? Warto sprawdzić logi komunikacji zarówno w PrestaShop, w sekcji Parametry zaawansowane, jak i w panelu zewnętrznego dostawcy, na przykład w panelu akceptanta bramki płatności czy w panelu Base. Jeśli sklep wysyła żądanie, ale nie otrzymuje odpowiedzi albo otrzymuje błąd po stronie zewnętrznego systemu, problem najczęściej leży w komunikacji między systemami, a nie w kodzie samego sklepu.

Czy warto zlecić obsługę integracji zewnętrznej agencji? Przy pojedynczej, prostej integracji niekoniecznie. Przy kilku równoległych integracjach, zwłaszcza łączących płatności, logistykę i sprzedaż wielokanałową, stały nadzór kogoś, kto zna specyfikę wszystkich podłączonych systemów, zwykle skraca czas reakcji na awarię z dni do godzin. O różnicach między obydwoma modelami pisaliśmy przy okazji porównania agencji e-commerce i własnego programisty.

Czy autorski moduł integracyjny jest bezpieczniejszy niż gotowy moduł z Marketplace? Niekoniecznie bezpieczniejszy, ale bardziej przewidywalny, jeśli jest odpowiednio udokumentowany i utrzymywany. Gotowe moduły bywają porzucane przez twórców, co jest szczególnie ryzykowne przy integracjach obsługujących płatności czy dane klientów. Kluczowe jest to, czy ktokolwiek aktywnie odpowiada za aktualizację modułu w razie zmian po stronie zewnętrznego API.

Podsumowanie

Integracje w PrestaShop rzadko psują się głośno. Zdecydowanie częściej przestają działać po cichu: zamówienie nie trafia do systemu magazynowego, powiadomienie o płatności ginie gdzieś między serwerami, oferta na Allegro przestaje brać udział w promocji, a nikt nie dostaje o tym żadnego komunikatu. Właśnie dlatego integracje warto traktować nie jako jednorazowe zadanie wdrożeniowe, tylko jako stały element utrzymania sklepu, wymagający monitoringu, testów po każdej aktualizacji i jasno ustalonych zasad na wypadek awarii.

Jeśli wolisz nie sprawdzać tego na własnym sklepie, wsparcie programistyczne Woohoo obejmuje rozwój i utrzymanie integracji z systemami płatności, logistyki i ERP jako stały element opieki nad sklepem, a nie dodatkowy projekt na boku.

Umów bezpłatną konsultację i sprawdźmy razem, które integracje w Twoim sklepie wymagają uwagi już teraz.

Zobacz też

Źródła

Zobacz więcej