Czym jest integracja z PrestaShop i jakie ma warstwy

Integracja z PrestaShop to automatyczna wymiana danych między sklepem a systemem zewnętrznym: przez API, moduł albo kolejkę zadań. Kluczowe słowo to „automatyczna”. Wklejanie numerów przesyłek ręcznie do panelu to nie integracja, a praca administracyjna z dodatkowym krokiem. PrestaShop udostępnia do tego warstwę modułów i API — punkt wyjścia dla dewelopera opisuje dokumentacja dla deweloperów PrestaShop.

W praktyce integrację tworzą cztery niezależne warstwy. Każda ma własne klucze API, własne limity i własny sposób raportowania błędów. Awaria jednej nie wyłącza pozostałych, ale potrafi zatrzymać obsługę zamówień.

• Płatności — operator przekazuje wynik transakcji webhookiem.
• Logistyka i kurierzy — etykieta, numer przesyłki, statusy doręczenia.
• Dane i magazyn (ERP/WMS) — stany, ceny, dokumenty sprzedaży.
• Marketing i analityka — GA4, feedy produktowe, mailing.

Drugie rozróżnienie dotyczy kierunku danych. Wymiana jednokierunkowa to eksport zamówień do księgowości albo wysyłka zdarzeń do GA4: dane płyną w jedną stronę i nikt ich nie porównuje. Wymiana dwukierunkowa to synchronizacja stanów i cen z ERP lub hurtowni — sklep wysyła zamówienie, system zwraca nowy stan magazynowy. Bez ustalonego „źródła prawdy” dla stanu i ceny dwie synchronizacje zaczną się nadpisywać.

Kiedy wystarczy eksport CSV raz dziennie: jeden magazyn, stany poprawiane ręcznie, do 20–30 zamówień na dobę, brak sprzedaży tego samego towaru w drugim kanale. Kiedy integracja jest konieczna: ten sam asortyment w sklepie i na marketplace, kilkaset SKU i więcej, kilka osób pakujących zamówienia, wymóg wystawienia faktury w kilka minut od płatności. Kolejne sekcje rozbierają to na płatności i kurierów. Kontekst ofertowy i zakres usług znajdziesz na stronie DropDigital – strony internetowe.

Integracje płatności w PrestaShop: co wybrać i na co uważać

Płatności generują najwięcej zgłoszeń typu „klient zapłacił, a zamówienie wisi”. Mechanika jest zawsze podobna: moduł tworzy transakcję i przekierowuje klienta do operatora, operator obsługuje płatność, a sklep dostaje webhook (IPN) i dopiero wtedy zmienia status zamówienia. Bez webhooka nie ma zmiany statusu — nawet jeśli pieniądze są na koncie.

Prowizję i czas rozliczenia ustala się indywidualnie w umowie, więc porównywanie operatorów bez aktualnego cennika i deklarowanego obrotu nie ma sensu. Zapytaj o stawkę dla swojego wolumenu i o to, czy prowizja nalicza się także od zwrotów.

• Pułapka 1: brak IPN, gdy firewall blokuje ruch wychodzący na porcie 443 albo URL zwrotny nie odpowiada kodem 200. Operator powtarza próbę kilka razy i odpuszcza.
• Pułapka 2: wielokrotne wywołania tego samego webhooka. Zabezpieczenie to idempotencja: zapisuj identyfikator transakcji do osobnej tabeli i przy drugim wywołaniu tylko dopisuj wpis do logu, bez kolejnej zmiany statusu.
• Pułapka 3: dublowanie statusów — moduł ustawia „opłacone”, a ręczna reguła w sklepie zmienia je na „w realizacji”. Ustal jedną kolejność przejść.

Przed startem sprawdź: tryb sandbox i test kwotą 1 zł, poprawność URL-i powrotu (sukces i błąd), obsługę płatności częściowych oraz zwrotów pełnych i częściowych, a także włączone logi modułu na pierwszy tydzień produkcji. Temat drugiej popularnej bramki rozwijam w tekście o tym, jak wygląda organizacja wdrożenia modułu PayPal w PrestaShop.

Integracje kurierskie: InPost, DPD, DHL, Poczta Polska, GLS

Integracja kurierska daje cztery rzeczy: etykietę generowaną z panelu zamówień, numer przesyłki zapisany przy zamówieniu, statusy doręczenia wracające do sklepu oraz — w InPost — wybór Paczkomatu na checkoutcie. Bez tego pakowanie wygląda tak: przepisanie adresu, ręczne utworzenie przesyłki w panelu kuriera, wklejenie numeru, ręczna zmiana statusu. Przy 30 zamówieniach dziennie to kilkadziesiąt minut pracy i stałe źródło pomyłek.

Interfejsy operatorów różnią się typem, autoryzacją i formatem etykiety. Poniższa tabela to punkt wyjścia do rozmowy z przedstawicielem kuriera — typy interfejsów i pola bywają rozszerzane, więc aktualny zakres potwierdź w dokumentacji technicznej.

• Pułapka z adresem: przy Paczkomacie i punkcie obsługi adres punktu to osobne pole. Jeśli moduł wpisze go w adres dostawy klienta, etykieta pojedzie pod zły adres, a dane do faktury zostaną nadpisane.
• Pułapka B2B: przesyłka paletowa to inna usługa niż paczka. Moduł paczkowy nie wystawi etykiety paletowej — takie zamówienia obsłuż osobno.
• Mapowanie statusów zwrotnych ustal przed startem i zapisz w konfiguracji modułu, nie w kodzie: „nadana” → „wysłane”, „doręczona” → „zrealizowane”, „awizo” → „oczekuje w punkcie”. Nazwy statusów u operatorów się zmieniają.
• Wybór punktu na checkoutcie: widget mapy zmniejsza liczbę błędnych kodów, ale dokłada skrypt do koszyka. Wbudowana lista jest szybsza, lecz klient częściej przepisuje kod ręcznie.

Własny moduł ma sens wtedy, gdy masz umowę z kurierem spoza rynku modułów, cenniki kontraktowe albo gabaryty niestandardowe. W pozostałych przypadkach taniej wychodzi wdrożenie i utrzymanie gotowego modułu.

Integracja PrestaShop z ERP, magazynem i systemem księgowym

To najtrudniejszy typ integracji, bo dotyka stanów magazynowych, czyli danych, na których firmie zależy najbardziej. Najczęstsze kierunki to Subiekt GT/nexo, Comarch ERP Optima, WF-Mag, BaseLinker oraz własne WMS-y pisane pod konkretny magazyn. Każdy z nich ma inny model dostępu: część udostępnia REST API, część tylko pliki wymiany w CSV lub XML, część wymaga connectora pośredniego.

Zakres synchronizacji zwykle obejmuje sześć obszarów: stany magazynowe, ceny, kartoteki produktów (nazwa, SKU, EAN, jednostka miary, stawka VAT), zamówienia, faktury i statusy płatności. Kierunek przepływu trzeba ustalić, zanim ktoś napisze pierwszą linię kodu: ERP jest źródłem prawdy o stanie i cenie, PrestaShop źródłem prawdy o zamówieniu. Odwrócenie tej zależności kończy się tym, że dwie osoby w firmie nadpisują sobie ten sam rekord.

Pułapka pierwsza: rozjazd stanów przy sprzedaży równoległej — sklep online i kasa stacjonarna schodzą z tego samego magazynu. Jeśli synchronizacja chodzi co 30 minut, w piątek po południu sprzedasz dwa razy ostatni egzemplarz. Rozwiązanie jest dwuczęściowe: rezerwacja stanu w momencie złożenia zamówienia oraz krótszy interwał dla produktów o niskim stanie (1–2 minuty zamiast 15).

Pułapka druga: duplikaty zamówień, gdy eksport zostanie wywołany drugi raz — po timeoucie, restarcie crona albo ręcznym kliknięciu. Potrzebny jest klucz idempotencji po numerze zamówienia (np. reference razem z id_shop) i tabela mapująca po stronie modułu, która przed zapisem do ERP sprawdza, czy rekord już istnieje.

Sposoby łączenia: REST API (najwięcej kontroli, najwięcej pracy), pliki wymiany (najprostsze, ale opóźnione), kolejka RabbitMQ lub Redis (odporna na awarie, dobra przy większym wolumenie), harmonogram cron co X minut (wystarcza w większości małych sklepów). Wydajność: odpytywanie API produkt po produkcie przy 5000 SKU to 5000 żądań HTTP na jeden przebieg i realne ryzyko zdławienia serwera. Obejście: pobieranie paczkami po 200–500 rekordów, synchronizacja inkrementalna po dacie modyfikacji, tabela pośrednia jako cache i indeksy na SKU oraz dacie zmiany. Kontekst całego wdrożenia opisaliśmy w materiale o organizacji wdrożenia sklepu PrestaShop.

Gotowy moduł z Addons czy własny moduł na zamówienie

Decyzja sprowadza się do trzech pytań: czy proces jest standardowy, ile kosztuje utrzymanie przez 5 lat i kto go naprawi po kolejnej aktualizacji.

Gotowy moduł wystarczy, gdy masz standardową umowę z kurierem, popularną bramę płatniczą (PayPal, Przelewy24, Stripe), standardowy ERP z oficjalnym konektorem (Subiekt, Comarch Optima) i nie modyfikujesz logiki cenowej. Wtedy zakup w granicach kilkuset złotych jednorazowo plus ewentualna subskrypcja załatwia sprawę, a wdrożenie zajmuje 1–2 dni.

Własny moduł bywa tańszy w 5-letnim cyklu, gdy wchodzą: niestandardowe reguły cenowe (rabaty kaskadowe, ceny zależne od kontrahenta), wielomagazynowość z podziałem na lokalizacje, B2B z indywidualnymi cennikami przypisanymi do klienta. Gotowe wtyczki tu pękają — albo nie mają funkcji, albo wymagają obejść w bazie danych, które przy każdej aktualizacji trzeba przenosić ręcznie.

Płatne wtyczki mają trzy typowe pułapki: subskrypcję roczną (przez 5 lat płacisz pięć razy), limit instalacji (środowisko staging zjada jedną licencję) oraz brak wsparcia po podniesieniu PHP (moduł pisany pod 7.4 sypie błędami na 8.2). Zdarza się też, że autor zniknął z rynku i nikt nie wyda poprawki.

Kryteria oceny przed zakupem: data ostatniej aktualizacji (im starsza, tym większe ryzyko), zadeklarowana kompatybilność z wersją PrestaShop i PHP, opinie opisujące realne problemy, polityka wsparcia — czy jest zgłaszanie ticketów, kontakt e-mail, czas reakcji. Punkt wyjścia do weryfikacji technicznej: dokumentacja deweloperska PrestaShop.

Koszt utrzymania to aspekt najczęściej pomijany przy zakupie. Pytanie brzmi: gdy PrestaShop wyda nową wersję, kto poprawi moduł i w jakim terminie? Przykład z życia: moduł płatności działający bez zarzutu do momentu zmiany API bramki — wtedy liczy się nie cena zakupu, a to, czy ktoś po drugiej stronie odbiera telefon. Zobacz, jak wygląda organizacja wdrożenia modułu płatności PayPal.

Jak wygląda wdrożenie integracji krok po kroku

Proces ma sześć etapów. Jeśli oferta wykonawcy nie zawiera żadnego z nich, to nie jest wdrożenie integracji, a instalacja modułu.

Etap 1 — warsztat zakresu. Lista systemów, kierunki przepływu, wymagana częstotliwość danych, definicja źródła prawdy dla każdego pola. Owoc: dokument na 2–4 strony, nie prezentacja.

Etap 2 — środowisko testowe. Kopia bazy produkcyjnej na subdomenie, osobne klucze API dla stagingu, osobne konto w bramce płatniczej w trybie sandbox. Bez tego testujesz na żywych zamówieniach klientów.

Etap 3 — implementacja i mapa pól. Moduł lub łącznik plus tabela mapowania: statusy zamówień ERP ↔ PrestaShop, kategorie, jednostki miary, stawki VAT, kody kurierów. To tutaj wychodzą różnice typu „ERP ma siedem statusów, sklep trzy”.

Etap 4 — testy scenariuszowe. Minimum pięć przypadków: zamówienie z płatnością online, zwrot, anulowanie po zapłacie, brak stanu przy zamówieniu, zamówienie B2B z indywidualnym cennikiem. Każdy scenariusz z wynikiem: co się stało w sklepie, co w ERP, co w logach.

Etap 5 — produkcja w trybie obserwacji. Uruchomienie z monitoringiem logów integracji i alertem na błędy. Pierwsze 2–4 tygodnie to przegląd odrzuconych rekordów raz dziennie, nie raz na kwartał.

Etap 6 — dokumentacja i SLA. Krótki opis: kto odpowiada za co, gdzie są klucze, jak zrestartować kolejkę, co zrobić przy błędzie 5xx albo 429 z API (kod odpowiedzi i zasady ponawiania opisuje dokumentacja MDN dotycząca HTTP). SLA na wypadek awarii API: czas reakcji, kanał zgłoszenia, kto ma dostęp do serwera.

Przykład organizacji takiego wdrożenia, z podziałem na etapy i odpowiedzialności, znajdziesz w artykule o organizacji wdrożenia sklepu PrestaShop.

Testy odbiorcze i pułapki, które wychodzą po dwóch tygodniach

Testy odbiorcze rób na kopii sklepu z realnymi danymi — produktami, klientami, stanami i historią zamówień. Czysta instalacja z trzema produktami testowymi nie wyłapie niczego. Poniżej pięć objawów, które najczęściej zgłaszają klienci po dwóch tygodniach od wdrożenia.

• Zamówienia bez numeru przesyłki. Sprawdź logi odpowiedzi API kuriera (w PrestaShop: Zaawansowane parametry → Logi, plus logi modułu) i to, co realnie wysyłasz. Najczęstsza przyczyna to nie literówka w nazwisku, a brakujący kod kraju, telefon w formacie lokalnym zamiast E.164 albo linia adresu ucięta przy mapowaniu. Druga w kolejności: odpowiedź HTTP 200 z JSON-em, w którym siedzi błąd. Kod 200 nie znaczy sukces — sprawdź, jak zbudowana jest odpowiedź HTTP i jej kody.
• Stany rozjeżdżają się o kilka sztuk. Zestaw log synchronizacji z inwentaryzacją z ostatnich 30 dni. Różnica rosnąca liniowo to zwykle zwroty i anulacje, które nie wracają na stan. Różnica skacząca to jedno zdarzenie przetworzone dwa razy — udana synchronizacja i nieudany retry tego samego zamówienia.
• Płatność zaksięgowana, zamówienie wisi. Webhook nie doszedł. Testuj z zewnątrz, nie z serwera sklepu: curl -X POST na adres webhooka z innego serwera, sprawdź kod odpowiedzi i czas. Sprawdź też walidację podpisu HMAC — po zmianie klucza w panelu podpis przestaje się zgadzać, a bramka przestaje ponawiać. Kolejność testów płatności opisujemy przy okazji wdrożenia modułu PayPal w PrestaShop.
• Duplikaty faktur w ERP. Eksport bez klucza idempotencji po ID zamówienia. Dwa wywołania crona w tej samej minucie albo retry po timeoucie tworzą dwie faktury. Klucz buduj z id_order i typu dokumentu, nie z daty i kwoty.
• Wydłużony czas odpowiedzi sklepu. Profiluj bazę (slow query log, SHOW PROCESSLIST). Integracja często dokłada zapytanie w pętli na liście produktów albo pobiera cennik u dostawcy przy każdym wejściu na kartę. Cache odpowiedzi API na 5–15 minut zwykle rozwiązuje problem.

Ćwiczenie awaryjne: na stagingu odetnij API kuriera na 15 minut i złóż 20 zamówień. Sprawdź, czy czekają w kolejce z czytelnym statusem, czy znikają bez śladu.

Ile kosztuje integracja z PrestaShop — widełki w godzinach

Wycena w godzinach ma sens tylko wtedy, gdy wiesz, co siedzi w tych godzinach. Realne widełki dla typowych zakresów:

Na liczbę godzin wpływa pięć rzeczy. Pierwsza to liczba kierunków synchronizacji — jednokierunkowy eksport zamówień to zupełnie inna praca niż dwukierunkowa wymiana stanów. Druga: jakość API dostawcy, czyli czy jest sandbox, dokumentacja i limity zapytań. Trzecia: liczba mapowanych statusów, bo 6 kontra 25 to różnica kilkunastu godzin na samych regułach. Czwarta: wielomagazynowość. Piąta: obsługa zwrotów i faktur korygujących. Przykład z życia: sklep z jednym magazynem i sześcioma statusami kontra sklep z trzema magazynami, dropshippingiem i 20 statusami — identyczna integracja z tym samym kurierem to praca trzy razy większa.

Godziny są uczciwsze niż sztywne pakiety, bo płacisz za pracę, a nie za marżę pośrednika: pracujesz bezpośrednio z deweloperem, który tę integrację pisze. Pakiet za 999 zł zwykle kończy się dopłatami przy pierwszym nietypowym przypadku — najczęściej przy zwrotach i korektach. Kolejność prac i podział zadań między sklepem, księgowością i wykonawcą opisujemy w materiale o organizacji wdrożenia sklepu PrestaShop krok po kroku.

Ukryte koszty, o które warto zapytać w ofercie: licencje lub abonament API u dostawcy, serwer albo VPS na crony i webhooki, monitoring, poprawki po aktualizacji PrestaShop i PHP.

Koszt braku integracji też jest liczbą: 200 zamówień miesięcznie razy 3 minuty ręcznego przepisywania to 10 godzin pracy miesięcznie, czyli około 120 godzin rocznie. Do tego błędne stany i sprzedaż towaru, którego nie ma na półce.

Utrzymanie integracji po wdrożeniu — co trzeba mieć na uwadze

Integracja nie kończy się w dniu wdrożenia, bo dostawcy regularnie zmieniają API. Przejście z prostego klucza API na OAuth 2.0, nowa wersja endpointu, wygaszenie starej (deprecation), zmiana formatu etykiety — każde z tych zdarzeń potrafi wyłączyć integrację w tygodniu, w którym nikt nie planował żadnych prac. Już na etapie umowy ustal, jak wykonawca wersjonuje integrację i gdzie trzyma klucze: poza repozytorium, w zmiennych środowiskowych. Zmiany w samym PrestaShop śledź w dokumentacji dla deweloperów PrestaShop, bo tam najszybciej widać porzucane mechanizmy.

Aktualizacje PrestaShop i PHP to druga pułapka. Zmiana PHP z 8.1 na 8.3 albo przejście na nowszą gałąź PrestaShop wymaga regresji: moduły pisane pod starsze wersje sypią się na sygnaturach i ostrzeżeniach. Kolejność jest stała — kopia, staging, lista wszystkich integracji, test scenariuszowy od zamówienia przez płatność i etykietę do faktury w ERP. Bez tego aktualizacja wypada w środku sezonu.

Monitoring to nie panel, a alerty. Minimum: powiadomienie na błędy 4xx i 5xx z API, kolejka nieudanych zadań z ponawianiem i odstępami, log zmian statusów zamówień. Praktyczny test: dzienny raport z trzema liczbami — ile zadań w kolejce, ile nieudanych, jak stary jest najstarszy nieudany wpis. Bez tego o awarii dowiesz się od klienta, zwykle po dwóch dniach.

Integracje analityczne wymagają takiej samej uwagi jak płatności. Po zmianie szablonu zdarzenie zakupu potrafi wysyłać się dwa razy i zawyżać przychód — opisujemy to w tekście o wdrożeniu GA4 w PrestaShop bez dublowania danych.

Ustal SLA i kanał kontaktu: czas reakcji, godziny pracy, limit godzin w pakiecie oraz to, czego opieka nie obejmuje — nowych funkcji, migracji i skutków aktualizacji wymuszanych przez dostawcę. Zapisz to jednym akapitem, nie w umowie na dwanaście stron.

Rekomendacja: przegląd integracji raz na kwartał. Testy scenariuszowe — jedno zamówienie na każdą metodę płatności i każdego kuriera — plus porównanie liczb: zamówienia w sklepie kontra ERP, wartość zamówień kontra faktury, stany magazynowe. Różnica powyżej 0,5 procent to sygnał do sprawdzenia, nie do ignorowania.

Najczęstsze błędy i jak je wykryć

Lista kontrolna do odklikania

• Źródło prawdy dla każdego pola — Sprawdź przed startem prac: dla stanu, ceny, nazwy produktu i statusu płatności musi być wskazany jeden system nadrzędny.
• Mapowanie statusów — Uzgodnij tabelę: status w PrestaShop ↔ status w systemie zewnętrznym. Weryfikuj na testach, czy „nadana” i „doręczona” faktycznie wskakują w dobre miejsca.
• Dostępy i sieć — Sprawdź klucze API, role, whitelistę adresów IP i to, czy hosting nie blokuje portów wychodzących przy webhookach.
• Środowisko testowe — Przed produkcją: kopia bazy, osobne klucze, dane testowe. Jeśli dostawca nie daje sandboxa, zaplanuj testy poza godzinami sprzedaży.
• Kopia bazy i plan wyłączenia — Ustal, jak wyłączyć integrację bez psucia zamówień i jak ręcznie nadrobić dane po wyłączeniu. Sprawdź to raz na stagingu.
• Kolejność wdrożeń — Zaplanuj osobnе okno dla płatności, osobne dla kurierów, osobne dla magazynu i osobne dla analityki. Nie łącz ich w jeden dzień.
• Monitoring i alerty — Sprawdź, czy błędy integracji generują powiadomienie i czy logi są czytelne dla osoby nietechnicznej.
• Obsługa błędów i ponowień — Ustal, ile razy system ponawia próbę, co się dzieje po jej wyczerpaniu i gdzie trafia „martwe” zdarzenie do ręcznej obróbki.
• Osoby i godziny reakcji — Zapisz imiennie, kto reaguje na alert w godzinach pracy, a kto poza nimi. Zweryfikuj to jednym testowym alarmem.
• Analityka bez dublowania — Sprawdź, czy zdarzenia zakupowe nie są wysyłane dwa razy po włączeniu integracji — punkt wyjścia opisuje wdrożenie GA4 w PrestaShop bez dublowania danych.
• Zakres i wyłączenia — Na piśmie: co integracja obejmuje, a czego nie (np. faktury korygujące, zamówienia B2B na palety, produkty na zamówienie).
• Limity i częstotliwość sync — Ustal, ile zapytań na minutę pozwala API dostawcy i jak często synchronizujesz stany. Sprawdź to na wolumenie zbliżonym do rzeczywistego.
• Dokumentacja powdrożeniowa — Sprawdź, czy po zakończeniu prac masz opis: gdzie są klucze, gdzie logi, jak wyłączyć moduł i do kogo zgłosić awarię.

Najczęściej zadawane pytania

Źródła i materiały

• Google Search Central – tworzenie treści dla ludzi
• Google Search Central – dane strukturalne
• Google Search Central – Core Web Vitals
• PrestaShop – dokumentacja dla deweloperów
• MDN Web Docs – HTTP