Co właściwie znaczy „integracja Allegro z PrestaShop” i czego automatem nie zrobisz

Pod pojęciem „integracja Allegro z PrestaShop” kryją się trzy niezależne przepływy. Każdy ma inne wymagania i można go wdrożyć osobno — w dowolnej kolejności.

• Oferta i katalog — wystawianie produktów z PrestaShop na Allegro oraz utrzymanie zgodności tytułu, opisu, zdjęć i parametrów. Można to robić w jedną stronę (PrestaShop → Allegro) albo w obie.
• Stany magazynowe — jedno źródło prawdy o dostępności. Najczęściej PrestaShop albo ERP, a Allegro tylko pobiera stan. Odświeżanie co 5–15 minut wystarcza w większości sklepów; przy sprzedaży limitowanych partii potrzebny jest krótszy interwał.
• Zamówienia i obsługa posprzedażowa — pobranie zamówienia z Allegro, utworzenie go w PrestaShop, rezerwacja stanu, numer przesyłki, statusy, zwroty i reklamacje.

PrestaShop nie ma wbudowanego łącznika z Allegro. W praktyce wybór zawęża się do trzech opcji: gotowy moduł komercyjny, własny moduł oparty na Allegro REST API albo middleware działające poza sklepem.

Typowy rozjazd: handlowiec obniża cenę w PrestaShop, ale przepływ cenowy nie jest włączony. W sklepie produkt kosztuje 249 zł, na Allegro nadal 299 zł. Klient kupuje taniej w sklepie i pyta, dlaczego na Allegro jest drożej. Drugi scenariusz: stan zmieniany tylko w panelu Allegro i sprzedaż towaru, którego fizycznie nie ma na półce.

Kiedy integracja jest zbędna? Jeśli wystawiasz 3–10 ofert raz na kwartał i nie ruszasz stanów częściej niż raz w tygodniu, ręczna obsługa zajmie mniej czasu niż konfiguracja i utrzymanie połączenia. Automatyzacja zaczyna się opłacać przy kilkudziesięciu ofertach i codziennych zmianach ceny lub stanu. Podstawy techniczne — wybór modułu, klucze API, pierwsza synchronizacja — znajdziesz w kompletnym przewodniku po integracji Allegro z PrestaShop.

Trzy drogi integracji: gotowy moduł, własny moduł, middleware

Nie ma jednej właściwej drogi. Decyzję podejmuj na podstawie liczby ofert i tego, co już działa w firmie.

Kryterium	Gotowy moduł	Własny moduł (Allegro REST API)	Middleware
Koszt startowy	300–2500 zł jednorazowo (licencja)	60–120 h pracy, czyli ok. 9 000–30 000 zł przy stawce 150–250 zł/h	0–2000 zł opłaty wdrożeniowej u części dostawców
Koszt miesięczny	20–100 zł (wsparcie, aktualizacje)	Utrzymanie 2–8 h miesięcznie, głównie po zmianach API Allegro	99–499 zł + opłata rosnąca wraz z wolumenem zamówień
Czas wdrożenia	1–3 dni konfiguracji	4–12 tygodni	1–2 tygodnie
Kontrola nad logiką	Tylko to, co przewidział autor modułu	Pełna	Tylko reguły udostępnione w panelu
Ryzyko przy aktualizacji PrestaShop	Średnie — zależy od tempa aktualizacji autora	Wysokie — zmiany w API sklepu wymagają poprawek w kodzie	Niskie — middleware działa poza sklepem

Progi decyzyjne:

• do ~300 ofert — gotowy moduł zwykle wygrywa. Kosztuje mniej niż dwa dni pracy programisty, a konfiguracja zamyka się w tygodniu.
• 300–3000 ofert — granica, na której middleware bywa tańszy niż utrzymanie własnego kodu. Płacisz abonament, ale nie płacisz za każdą zmianę w API Allegro.
• powyżej 3000 ofert, kilka kanałów sprzedaży lub ERP — własny moduł albo dedykowany connector. Tylko wtedy kontrola nad logiką zwraca koszt 60–120 h pracy.

Middleware przestaje wystarczać, gdy potrzebujesz niestandardowych reguł cenowych (inna marża dla kategorii, inna dla klienta B2B), wielokanałowości z priorytetami magazynów albo nietypowego mapowania wariantów — np. gdy jeden produkt w PrestaShop ma trafiać jako trzy osobne oferty Allegro w zależności od koloru.

Jeśli w firmie działa ERP i to on jest źródłem prawdy o towarze, prowadź integrację w kierunku ERP → Allegro i ERP → PrestaShop. Wariant PrestaShop → Allegro z ERP obok oznacza, że dwa systemy nadpisują sobie stany i ceny — najczęstsza przyczyna „magicznych” rozjazdów. Zanim wybierzesz narzędzie, uporządkuj organizację wdrożenia sklepu PrestaShop. Dokumentację techniczną modułów i API znajdziesz w PrestaShop Developer Documentation.

Mapowanie pól: co musi się zgadzać między PrestaShop a Allegro

Z praktyki wdrożeń: większość problemów nie wynika z kodu, tylko z mapowania pól. Zanim podłączysz cokolwiek, przygotuj arkusz z kolumnami: pole PrestaShop, pole Allegro, źródło prawdy, kto może edytować.

Do sprawdzenia przed startem:

• SKU / reference — unikalny klucz produktu po obu stronach. Musi być niezmienny.
• EAN / GTIN — brak numeru blokuje część kategorii i utrudnia dopasowanie.
• Nazwa — na Allegro limit znaków, dłuższe tytuły trzeba skracać szablonem.
• Opis — treść z edytora PrestaShop nie zawsze przechodzi na Allegro, znaczniki bywają czyszczone.
• Cena regularna i promocyjna — promocja bez daty końca zostaje aktywna na stałe po stronie Allegro.
• Stan — uwzględnij rezerwacje i sztuki w nieopłaconych koszykach, inaczej sprzedasz towar dwa razy.
• Waga i wymiary — od nich zależy cennik kuriera i dopłaty; temat rozwija integracja InPost z PrestaShop.
• Zdjęcia — minimalna liczba, format, brak znaków wodnych w części kategorii.
• Kategoria PrestaShop → kategoria Allegro — to nie mapowanie 1:1, drzewa mają inną strukturę.
• Parametry oferty — część jest wymagana w danej kategorii (rozmiar, kolor, materiał).

Jedno źródło prawdy. Jeśli PrestaShop i Allegro mogą edytować ten sam stan, powstaje pętla nadpisywania: przy dwóch zmianach w ciągu minuty wygrywa ostatni zapis i stany się rozjeżdżają. Rozwiązanie jest proste — stan edytujesz tylko w jednym miejscu, drugi system ustawiasz jako tylko do odczytu.

Dopasowanie oferty. Zapisz identyfikator oferty Allegro (external.id) po stronie PrestaShop — w tabeli produktu lub osobnej tabeli mapowania. Nigdy nie dopasowuj po nazwie: zmiana tytułu zerwie połączenie i system wystawi duplikat.

Warianty. Kombinacje w PrestaShop (jeden produkt, np. 12 kombinacji) kontra jedna oferta Allegro z macierzą wariantów. Jeśli warianty różnią się tylko kolorem lub rozmiarem przy tej samej cenie bazowej — jedna oferta z wariantami. Jeśli różnią się ceną, wagą albo dostawcą — jeden produkt = jedna oferta.

Czego nie przeniesiesz 1:1. Opisów z pełnym HTML-em, parametrów wymaganych w konkretnej kategorii i części pól opisowych. Obejście: szablony opisów w PrestaShop plus osobne pola z treścią przeznaczoną wyłącznie na Allegro.

Synchronizacja stanów magazynowych: jak nie sprzedać towaru, którego nie ma

Stan magazynowy to miejsce, w którym integracja dotyka pieniędzy w obie strony: za mało na stanie to anulowane zamówienie i kara od Allegro, za dużo to zamrożona gotówka. Najpierw ustal źródło prawdy. W większości sklepów jest nim PrestaShop, a Allegro tylko konsumuje stany. Kierunek odwrotny — magazyn prowadzony na Allegro — ma sens wyłącznie wtedy, gdy nigdzie indziej nie sprzedajesz.

Zdarzenia z Allegro możesz pobierać na dwa sposoby:

• Webhooki – powiadomienia o zdarzeniach przychodzące do Twojego sklepu. Opóźnienie liczone w sekundach, ale wymagają publicznego endpointu HTTPS, weryfikacji podpisu i kolejki zadań po stronie PrestaShop. Jeśli hosting nie przyjmuje POST-ów z zewnątrz, ten tryb odpada.
• Odpytywanie API (cron co 5–15 minut) – prostsze w utrzymaniu, ale 15 minut zwłoki przy sprzedaży na dwóch kanałach to realne ryzyko dubli. Przy 4000 SKU i interwale 5 minut robią się tysiące zapytań na dobę.

Bufor bezpieczeństwa. Trzymaj rezerwę 1–2 szt. dla najszybciej rotujących pozycji albo 5–10% stanu. Sprzedaż na dwóch kanałach bez bufora kończy się anulowaniem zamówień, a to najdroższy typ błędu: prowizja, kara, spadek pozycji oferty.

Rezerwuj stan w momencie złożenia zamówienia, nie opłacenia. Przy płatnościach odroczonych i Allegro Pay pieniądze wpływają nawet kilkanaście godzin później. Jeśli zdejmujesz towar ze stanu dopiero po zaksięgowaniu wpłaty, przez ten czas ta sama sztuka wisi w ofercie i sprzedaje się drugi raz.

Wiele magazynów i kont. Trzymaj jawną tabelę mapowania: magazyn → konto Allegro. Przeniesienie towaru między magazynami musi generować zdarzenie, inaczej jedno konto widzi stan, którego fizycznie nie ma.

Idempotencja i kolejka. Każdy event zapisuj z identyfikatorem i unikalnym indeksem w bazie — ten sam webhook może przyjść dwa razy. Timeout po faktycznym zapisie rozwiązuj zasadą: najpierw odczytaj stan, potem ponów zapis. Aktualizacje batchuj — jedno zadanie aktualizuje paczkę ofert, a nie osobne zapytanie na każdą. Limity zapytań Allegro REST API się zmieniają, więc sprawdź aktualne wartości w dokumentacji i czytaj nagłówki odpowiedzi z informacją o pozostałym limicie.

Jak wygląda sam łącznik od strony technicznej, opisujemy w przewodniku Jak zintegrować Allegro z PrestaShop: kompletny przewodnik.

Zamówienia z Allegro w PrestaShop: import, statusy, płatności, faktury

Zanim cokolwiek zaimportujesz, ustal, jak zamówienie z Allegro ma wyglądać w PrestaShop. Statusów z ekranu Zamówienia → Statusy nie mapuj 1:1, bo po stronie Allegro dane są dwuwarstwowe: inny jest status formularza zakupu (m.in. BOUGHT, READY_FOR_PROCESSING, FILLED_IN, CANCELLED, RETURNED), a inny status realizacji (m.in. NEW, PROCESSING, READY_FOR_SHIPMENT, SENT, RETURNED). Do tego dochodzi status płatności. Jeden status w PrestaShop powstaje więc z kombinacji tych trzech warstw.

Drugi powód, dla którego mapowanie 1:1 nie działa: każdy status w PrestaShop ma własny szablon maila. Przy domyślnej konfiguracji klient dostanie potwierdzenie od Ciebie i drugie od Allegro. Wyłącz wysyłkę maili dla statusów importowanych z Allegro i zostaw jeden kanał komunikacji.

Duplikaty. Klucz unikalności to identyfikator zamówienia Allegro, nie e-mail ani numer koszyka. Trzymaj go w osobnej kolumnie z indeksem unikalnym i zapisuj już przy pierwszym imporcie — ponowny import po błędzie nic wtedy nie zdubluje. Przy dwóch kontach Allegro dołóż do klucza identyfikator konta.

RODO. Importuj minimum: dane do wysyłki, punkt odbioru, dane do faktury, identyfikator kupującego. Nie kopiuj całej historii dyskusji do bazy sklepu. Po zakończeniu realizacji i upływie okresu przechowywania anonimizuj rekord zamówienia, zachowując kwoty i dokumenty księgowe.

Faktury. Dane do faktury przychodzą z formularza zakupu: nazwa nabywcy, NIP, adres. Wystawiaj dokument przez API systemu księgowego, nie ręcznie, i przygotuj się na KSeF — harmonogram wdrożeń jest etapowy, sprawdź aktualny termin dla swojego obrotu. Struktury faktury nie buduj na sztywno, bo format e-faktury jeszcze się zmieniał.

Zwroty. Dyskusje i zgłoszenia zwrotów importuj jako osobny typ dokumentu. Ruch magazynowy z powrotem na stan rób po fizycznym przyjęciu towaru, nie w chwili zgłoszenia zwrotu — inaczej wystawiasz na sprzedaż rzecz, której nie masz. Mechanikę statusów i webservice opisuje dokumentacja dla deweloperów PrestaShop, a nadawanie przesyłek po imporcie zamówienia — tekst Integracja InPost z PrestaShop: kompletny poradnik.

Koszty i czas wdrożenia: rozbicie na godziny, nie na „od”

Wycena w stylu od X zł nic nie mówi, bo rozrzut między projektami jest trzykrotny. Rozbij ofertę na godziny i porównuj wykonawców na tej samej siatce:

• analiza i audyt danych: 4–8 h (katalog, warianty, stany, konta Allegro, słowniki cech),
• mapowanie pól i ustalenie źródła prawdy: 8–16 h,
• development: 40–80 h,
• testy: 8–16 h (scenariusze: brak stanu, duplikat, timeout, zwrot),
• wdrożenie i monitoring: 4–8 h.

Razem 64–128 godzin. Pomnóż to przez stawkę godzinową wykonawcy i zestaw z ceną z oferty. Jeśli kwota jest niższa niż 64 h × jego własna stawka, w wycenie brakuje całego etapu — najczęściej testów albo audytu danych.

Co najbardziej podnosi koszt: liczba ofert, warianty (każda kombinacja to osobna oferta na Allegro), liczba kont Allegro, integracja z ERP i niestandardowe reguły cenowe. Zmiana reguły cenowej po wdrożeniu kosztuje zwykle tyle samo, co napisanie jej od zera.

Utrzymanie. Wdrożenie jest jednorazowe, ale zmiany w API Allegro są faktem. Wystarczy nowa wersja endpointu ofert albo zmiana formatu zdarzenia i import przestaje działać. Abonament powinien obejmować monitoring z alertem, gdy import stanie, poprawki po zmianach API, aktualizacje modułu i raport rozjazdów stanów. Realnie zarezerwuj 2–5 godzin miesięcznie, czyli 24–60 godzin rocznie.

Dwa scenariusze. Sklep z 200 ofertami bez wariantów, jednym kontem i stanem prowadzonym w PrestaShop: dolne widełki, 64–80 h. Sklep z 4000 SKU, wariantami, dwoma kontami Allegro i ERP po stronie magazynu: górne widełki plus osobne godziny na mapowanie słowników cech i uzgodnienie, który system jest źródłem prawdy o stanie. Wtedy 128 h to punkt startowy, a nie sufit.

Testy przed startem: sandbox, scenariusze i rollback

Testy robisz na dwóch środowiskach: sandboxie Allegro (środowisko testowe REST API) i kopii sklepu na staging. Staging musi mieć tę samą wersję PrestaShop, ten sam motyw i realną bazę produktów, ale wyłączone maile do klientów i płatności na żywo. Na produkcji nie sprawdzasz niczego, co tworzy zamówienie, wysyła maila do kupującego albo zmienia stan oferty na koncie sprzedawcy.

Minimalny zestaw scenariuszy przed startem:

• brak stanu — produkt schodzi do 0; sprawdzasz, czy oferta kończy się na Allegro, czy tylko zmienia dostępność (to decyzja biznesowa, nie techniczna),
• anulowanie przez kupującego — czy zamówienie wraca do PrestaShop ze statusem anulowane i czy stan wraca na magazyn,
• zwrot pełny i częściowy — czy zwrot w Allegro zgadza się ze zwrotem w PrestaShop,
• edycja oferty bezpośrednio w Allegro — zmieniasz ręcznie tytuł i cenę; patrzysz, czy integracja to nadpisze, zignoruje, czy zgłosi konflikt,
• zmiana ceny w PrestaShop w trakcie promocji — cena regularna vs promocyjna to najczęstsze źródło rozjazdów.

Testy graniczne i oczekiwane zachowanie:

Po wdrożeniu włączasz monitoring: logi żądań do API, alert przy błędach 401/403/429 i dzienny raport rozjazdów stanów (produkty, gdzie stan w sklepie różni się od stanu oferty na Allegro). Rollback plan jest prosty: wyłączasz crony odpowiedzialne za synchronizację, przełączasz integrację w tryb tylko do odczytu i obsługujesz zamówienia z Allegro ręcznie. Sprzedaż i magazyn działają dalej — zatrzymujesz synchronizację, nie sklep. Zakres trzech przepływów (oferta, stany, zamówienia) i wybór między modułem a middleware opisujemy w przewodniku jak zintegrować Allegro z PrestaShop.

Najczęstsze błędy i jak je rozpoznać w logach

Logi to najtańsze narzędzie diagnostyczne, jakie masz. Zapisuj każde żądanie do API Allegro z kodem odpowiedzi, znacznikiem czasu i identyfikatorem oferty lub zamówienia. Bez tego przy sytuacji „stany się nie zgadzają” zostaje zgadywanie i ręczne klikanie w panelu.

• 401/403 — wygasły lub odwołany token OAuth albo brak wymaganego zakresu uprawnień (np. dostępu do zamówień). Objaw: cisza w synchronizacji przez kilka godzin, bo nikt nie patrzy na logi.
• 429 — przekroczony limit zapytań. Objaw: stan aktualizuje się „skokowo”, część ofert zostaje z nieaktualnym stanem, a kolejkę trzeba ograniczyć i dodać backoff.
• Pętla aktualizacji — dwa systemy nadpisują ten sam stan. W logach widać serię zmian tego samego produktu co kilka sekund. Rozwiązanie: jedno źródło prawdy dla stanu i wyłączenie zapisu po jednej stronie.
• Duplikaty zamówień — po restarcie kolejki to samo zamówienie wchodzi drugi raz, bo brakuje klucza idempotencji i sprawdzania przed zapisem.
• Oferty bez mapowania — nowe aukcje wystawione ręcznie na Allegro, dla których nie ma produktu w sklepie. Wykrywasz je alarmem przy nieznanym ID oferty i domykasz mapowanie w panelu.

Rozjazd cen wymaga osobnego raportu porównawczego: cena regularna i promocyjna w sklepie (w PrestaShop ceny promocyjne siedzą w tabeli specific_price — model danych opisuje dokumentacja dla deweloperów PrestaShop) kontra cena i cena promocyjna w ofercie Allegro. Uruchamiaj go raz dziennie i wysyłaj wynik mailem — różnice wychodzą wtedy, gdy jest jeszcze czas je poprawić.

Zrobić samemu czy zlecić? Pytania do wykonawcy i czerwone flagi

Samodzielna integracja ma sens w wąskim zakresie: katalog do kilkudziesięciu ofert, gotowy moduł robiący dokładnie to, czego potrzebujesz, i osoba w firmie, która zna PHP oraz utrzyma wdrożenie po zmianach API. Jeśli któryś z tych warunków nie jest spełniony, koszt wewnętrzny zwykle przestaje być niższy niż zlecenie.

Zlecenie rozważ, gdy w tle działa ERP, sprzedajesz na kilku kontach Allegro, masz niestandardową logikę cen (rabaty grupowe, ceny B2B, progi ilościowe) albo nie ma kto utrzymać integracji po miesiącu od startu.

Pytania, które zadajesz wykonawcy na pierwszym spotkaniu:

• Kto jest właścicielem kodu — moduł i skrypty przechodzą na Ciebie po odbiorze? Jeśli nie, zostajesz z systemem, którego nie możesz przenieść do innego wykonawcy.
• Co się dzieje przy zmianie API Allegro — dostosowanie jest w cenie czy płatne osobno i przez jaki okres wykonawca odpowiada za zgodność.
• Jaki jest SLA na zgłoszenia — konkretny czas reakcji przy zatrzymanej synchronizacji, a nie „do 3 dni roboczych” na wszystko.
• Czy dostaję logi i monitoring — w jakiej formie i kto ma do nich dostęp.

Czerwone flagi w ofercie: brak wyszczególnienia godzin (nie da się porównać dwóch ofert), „cena od X” bez zakresu, brak etapu testów na sandboxie, brak wsparcia po wdrożeniu i brak informacji o właścicielu kodu.

W umowie powinny znaleźć się: zakres, harmonogram, kryteria odbioru (np. cała lista scenariuszy testowych przechodzi bez błędów), okres opieki po wdrożeniu oraz stawka za prace dodatkowe. Dobry punkt odniesienia to nasze podejście do wdrożenia modułu płatności w PrestaShop — ten sam schemat: etapy, testy, opieka po starcie.

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

Lista kontrolna do odklikania

• Unikalne SKU (reference) dla każdego produktu — Sprawdź przed startem integracji — duplikaty reference rozwalają dopasowanie ofert i są trudne do naprawienia po fakcie.
• Kompletność EAN/GTIN — Zweryfikuj, ile produktów ma wpisany EAN. Braki zgłoś przed mapowaniem — część kategorii Allegro wymaga tego parametru.
• Waga i wymiary paczki — Sprawdź przy każdym produkcie przed konfiguracją cenników dostawy i przed wystawieniem ofert.
• Ceny regularne i promocyjne — Ustal, czy promocje w PrestaShop mają być przenoszone do Allegro, czy cena na Allegro jest zarządzana osobno. Sprawdź to na 2–3 produktach w promocji.
• Mapowanie kategorii PrestaShop → kategoria Allegro — Zrób to przed pierwszą synchronizacją. Drzewo kategorii w PrestaShop rzadko pokrywa się 1:1 z kategoriami Allegro.
• Parametry wymagane w kategoriach Allegro — Dla każdej kategorii, w której wystawiasz, wypisz parametry obowiązkowe i sprawdź, czy masz dla nich dane w PrestaShop.
• Obsługa wariantów — Ustal, kiedy 1 produkt = 1 oferta, a kiedy 1 produkt = 1 oferta z macierzą wariantów. Sprawdź to na produkcie z realnymi kombinacjami.
• Identyfikator oferty Allegro zapisany w PrestaShop — Upewnij się, że moduł zapisuje ten identyfikator trwale, np. w polu produktu. To warunek bezpiecznych aktualizacji.
• Jedno źródło prawdy dla stanu magazynowego — Zapisz na piśmie, który system jest nadrzędny. Sprawdź, czy integracja nie zapisuje stanu w obie strony.
• Bufor magazynowy i progi blokady ofert — Ustal wartości przed startem i sprawdź je na testowym produkcie o niskim stanie.
• Mapowanie statusów zamówień z Allegro do PrestaShop — Sprawdź, jaki status dostaje zamówienie po pobraniu i co się dzieje po oznaczeniu wysyłki.
• Limity i wydajność API — Przy dużym katalogu przetestuj pełną synchronizację i zmierz czas. Ustal, czy zadania idą przez cron i jak często.
• Logi synchronizacji i kopie zapasowe — Sprawdź przed startem, gdzie trafiają logi i jak cofnąć błędną masową zmianę cen lub stanów.
• Osoba odpowiedzialna za mapowanie po stronie firmy — Wyznacz ją na starcie wdrożenia. Mapowanie to decyzje biznesowe, nie zadanie wyłącznie dla programisty.

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
• Google Ads – dokumentacja API