DataFirefly Amazon Connector: integracja PrestaShop z Amazon Seller Central
Instalacja, połączenie SP-API, marketplace'y, mapowanie kategorii, publikacja, ceny, stany, zamówienia, wysyłki, faktury, anulowania, zwroty i rozwiązywanie problemów.
Wprowadzenie
Moduł łączy sklep PrestaShop z kontem sprzedawcy Amazon za pomocą oficjalnego Selling Partner API (SP-API). Publikuje produkty na wybranych marketplace’ach, wysyła stany magazynowe i ceny, importuje zamówienia Amazon do PrestaShop, potwierdza wysyłki, przesyła faktury oraz odczytuje zwroty pieniędzy i stan magazynowy FBA.
Kompatybilność: PrestaShop od 1.7.8 do 9.x, ten sam plik ZIP dla wszystkich wersji. Multistore, wielojęzyczność, regiony Amazon Europa, Ameryka Północna i Daleki Wschód. Interfejs w 8 językach: francuskim, angielskim, hiszpańskim, niemieckim, włoskim, niderlandzkim, polskim i portugalskim.
Nowości w wersji 2.0.0: kreator połączenia, pulpit synchronizacji, wizualny edytor mapowań z wymaganymi atrybutami Amazon, kolejka z wyjaśnieniem i sposobem poprawy każdego błędu, cena minimalna i maksymalna dla produktu i dla marketplace’u, tryb VAT dla każdego marketplace’u, zwrot pieniędzy z poziomu PrestaShop, anonimizacja danych kupującego oraz kompatybilność z PrestaShop 1.7.8.
Wersja 2.0.0 poprawia też błędy wersji 1.2.1: aktualizacje stanów niedodawane do kolejki i niezapisywane ustawienia produktu przy MySQL w trybie strict, odrzucane zamówienia do kraju wyłączonego w sklepie lub do Hiszpanii, brak importu przez cron uruchamiany z wiersza poleceń, wyłączona marka blokująca ofertę. Aktualizacja z wersji 1.2.1 zachowuje wszystkie dane.
Instalacja
- W Moduły > Menedżer modułów kliknij Załaduj moduł i wyślij plik ZIP. Wymagane są rozszerzenia PHP cURL i OpenSSL.
- Moduł tworzy swoje tabele, zakładkę Konektor Amazon w menu Sprzedaż, przewoźnika „Amazon” przeznaczonego tylko dla importowanych zamówień (nigdy niepokazywanego klientom) oraz statusy zamówień Amazon.
- Otwórz zakładkę: pulpit pokazuje kolejne kroki konfiguracji.
Aby przejść z wersji 1.2.1 na 2.0.0, wyślij nowy plik ZIP. Ustawienia, dane uwierzytelniające, marketplace’y, mapowania, oferty, zamówienia i logi są zachowywane, a sekrety są ponownie szyfrowane nowym algorytmem. Po aktualizacji anonimizacja danych kupującego pozostaje wyłączona: nic z już zaimportowanych danych nie jest zmieniane, dopóki jej nie włączysz.
Przygotowanie konta Amazon
Moduł łączy się przez Twoją własną prywatną aplikację SP-API. Potrzebne jest profesjonalne konto Seller Central.
- W Seller Central otwórz Apps and Services > Develop Apps i zarejestruj się jako prywatny deweloper, jeśli jeszcze tego nie zrobiłeś.
- Utwórz aplikację i poproś o role potrzebne do funkcji, z których będziesz korzystać: Product Listing i Pricing dla katalogu, Inventory and Order Tracking dla zamówień, Direct-to-Consumer Shipping (Restricted) dla adresu dostawy, Amazon Fulfillment dla stanu FBA, Finance and Accounting dla zwrotów pieniędzy, Tax Invoicing dla faktur.
- Autoryzuj aplikację na swoim koncie, aby uzyskać refresh token, i zanotuj ID klienta LWA oraz sekret klienta LWA.
- Odczytaj swoje ID sprzedawcy (Merchant Token) w Ustawienia > Informacje o koncie.
API Orders v2026-01-01 używane przez moduł nie wymaga Restricted Data Token: dostęp do adresu dostawy zależy od roli Direct-to-Consumer Shipping Twojej aplikacji. Bez tej roli zamówienia są importowane z adresem zastępczym, co jest oznaczone w zamówieniu.
Połączenie
Zakładka Połączenie prowadzi przez konfigurację w czterech krokach: region, dane uwierzytelniające Login with Amazon, ID sprzedawcy, a następnie test. Test pobiera z Amazon token dostępu i odczytuje marketplace’y Twojego konta; następnie zaznaczasz sklepy Amazon do włączenia.
Sekret klienta i refresh token są zaszyfrowane w bazie danych (AES-256-GCM) i nigdy nie są ponownie wyświetlane: pozostaw pola puste, aby zachować zapisane wartości. Przycisk Rozłącz usuwa dane uwierzytelniające i zatrzymuje synchronizację.

Marketplace’y i reguły cen
Zakładka Marketplace’y pokazuje kartę dla każdego sklepu Amazon. Dla każdego z nich ustaw:
- włączenie i język oferty (tytuł, opis, punkty);
- narzut procentowy, stałą kwotę i zaokrąglenie (brak, x,99, x,90, w górę do pełnej kwoty);
- cenę minimalną marketplace’u: żadna cena poniżej niej nie jest publikowana;
- ceny brutto lub netto oraz synchronizację cen, którą należy wyłączyć, jeśli używasz repricera Amazon;
- tryb VAT: VAT według reguł sklepu albo bez podatku, gdy VAT pobiera Amazon. Ten wybór zależy od Twojej sytuacji podatkowej: skonsultuj go ze swoim księgowym.
Każda karta pokazuje też liczbę aktywnych ofert i ofert z błędem oraz ostatnie zamówienia z danego marketplace’u.

Mapowania: kategorie i typy produktów
Mapowanie jest potrzebne tylko do tworzenia nowych kart produktów na Amazon. Produkt sprzedawany na istniejącym ASIN lub powiązany przez EAN potrzebuje tylko oferty.
W zakładce Mapowanie przypisz kategorię PrestaShop do typu produktu Amazon. Produkt używa mapowania swojej kategorii domyślnej, a jeśli go brak, mapowania najbliższej kategorii nadrzędnej. Przycisk wyszukiwania odpytuje Amazon po słowach kluczowych i proponuje pasujące typy produktów.

Po wybraniu typu przycisk Wczytaj wymagane atrybuty odczytuje schemat typu produktu z Amazon. Edytor pokazuje dla każdego wymaganego atrybutu, czy jest wypełniany automatycznie przez moduł (tytuł, marka, EAN, cena…), przypisany przez Ciebie czy nadal brakujący, wraz z licznikiem „Pokryte”. Dla każdego brakującego atrybutu wybierz źródło:
- cechę PrestaShop;
- atrybut kombinacji (rozmiar, kolor, materiał…);
- stałą wartość.
Motyw wariantów (na przykład SIZE_NAME/COLOR_NAME) grupuje kombinacje w rodzinę nadrzędny-podrzędny; gdy jest pusty, każda kombinacja jest publikowana jako niezależny produkt. Atrybuty zaawansowane (JSON) pozostają dostępne dla szczególnych przypadków, ze zmiennymi {marketplace_id}, {language_tag}, {currency}, {reference}, {ean13}, {mpn} i {brand}.

Publikowanie produktów
Z karty produktu
Zakładka Moduły na karcie produktu zawiera blok Amazon:
- Sprzedawaj na Amazon włącza produkt.
- Tryb publikacji: automatyczny, oferta na istniejącym produkcie (ASIN lub EAN) albo utworzenie pełnej karty produktu.
- Wysyłka: przez Ciebie (FBM) lub przez Amazon (FBA).
- ASIN, typ produktu, stan i stała cena Amazon zastępują wartości domyślne dla tego produktu.
- Cena minimalna i cena maksymalna produktu: ograniczają wyliczoną cenę i są wysyłane do Amazon jako limity cen sprzedawcy.
- Marketplace’y: odznacz kraj, aby wycofać produkt z tego marketplace’u.
Tabela „Co zostanie wysłane do Amazon” pokazuje dla każdej kombinacji i każdego kraju cenę, cenę promocyjną i jej daty, limity cen, cenę Business i ilość. Cena sprowadzona do limitu jest oznaczona. Oferty już aktywne są widoczne wraz ze statusem i ASIN.

Sprawdź w Amazon przekazuje ofertę do weryfikacji przez Amazon bez publikowania czegokolwiek. Każdy błąd jest wyjaśniony prostym językiem wraz z poprawką do wprowadzenia, na przykład EAN niezarejestrowany w GS1 lub brakujący wymagany atrybut. Blok uzupełniają przyciski Wyślij teraz, Dodaj do następnej synchronizacji i Odśwież status. Oferta już aktywna jest aktualizowana częściowo: atrybuty wprowadzone w Seller Central i nieobsługiwane przez moduł nie są usuwane.

Masowo
Zakładka Produkty wyświetla katalog, a przy każdym produkcie tryb FBM lub FBA, status na każdym marketplace, stan magazynowy sklepu i stan FBA. Filtruj po nazwie, indeksie, EAN, SKU, ASIN, kategorii lub statusie, zaznacz produkty lub wszystkie produkty pasujące do filtra, a następnie zastosuj akcję zbiorczą: włącz i opublikuj, opublikuj ponownie, wyślij ceny, wyślij ilości, dezaktywuj (ilość 0) lub usuń z Amazon.

Oferty już istniejące na Amazon
Powiąż istniejące oferty Amazon zamawia w Amazon raport Twoich ofert. Przy kolejnych uruchomieniach crona każdy SKU jest wiązany z produktem PrestaShop, który ma ten sam SKU, ten sam indeks lub ten sam EAN. Nieznalezione SKU są wymienione w logu.
SKU Amazon
SKU jest tworzony przy pierwszej publikacji zgodnie z wybranym ustawieniem: indeks, EAN13 lub szablon (domyślnie PS{id_product}-{id_product_attribute}). Raz utworzony SKU nigdy się nie zmienia, nawet jeśli zmieni się indeks, a dwie kombinacje nie mogą otrzymać tego samego SKU.
Ceny
Cenę wylicza moduł, po stronie serwera, w tej kolejności: cena wybranej grupy cenowej, przeliczenie na walutę marketplace’u, narzut i stała kwota, zaokrąglenie, a na końcu limity. Cena minimalna to najwyższa z wartości: cena minimalna produktu, cena minimalna marketplace’u oraz cena zakupu powiększona o minimalną marżę; cena maksymalna to cena maksymalna produktu. Cena zerowa lub ujemna nigdy nie jest publikowana, a cena minimalna wyższa od maksymalnej jest odrzucana z komunikatem.
Opcje sekcji Ceny w ustawieniach:
- Grupa cenowa: ceny tej grupy klientów są podstawą cen Amazon.
- Stosuj rabaty sklepu: ceny specyficzne i reguły cenowe katalogu są uwzględniane w cenie Amazon.
- Wysyłaj rabaty sklepu jako ceny promocyjne Amazon: cena regularna pozostaje ceną referencyjną, a rabat staje się ceną promocyjną z datami. Rabat utworzony, zmieniony lub usunięty w PrestaShop aktualizuje Amazon; po usunięciu cena promocyjna jest wycofywana z Amazon.
- Minimalna marża od ceny zakupu: żadna cena nie jest publikowana poniżej ceny zakupu powiększonej o tę marżę, a ta cena minimalna jest wysyłana do Amazon na potrzeby automatycznego ustalania cen.
- Ceny Amazon Business: cena grupy klientów staje się ceną Business, a jej rabaty ilościowe stają się progami (maksymalnie 5). Tylko dla sprzedawców zarejestrowanych w Amazon Business.

Stany magazynowe i FBA
Każda zmiana stanu w PrestaShop dodaje produkt do kolejki wysyłki dla każdego marketplace’u, na którym oferta jest aktywna. Ustawienia: zapas bezpieczeństwa (jednostki niewystawiane na Amazon), maksymalna ilość, czas realizacji, ilość 0 dla produktów wyłączonych oraz codzienna pełna resynchronizacja. Ilość ujemna jest wysyłana jako 0.
Produkty w FBA nie otrzymują ilości z PrestaShop. Odczyt stanu FBA co godzinę pobiera ilość dostępną w magazynach Amazon i pokazuje ją na liście produktów i na karcie produktu; Kopiuj stan FBA do PrestaShop przenosi ją do stanu sklepu dla produktów w FBA.
Zadanie cron
Synchronizacja działa przez zadanie cron, najlepiej co 5 do 15 minut. Sekcja Zadanie cron w ustawieniach pokazuje URL chroniony tokenem i polecenie do uruchamiania z wiersza poleceń:
php /sciezka/do/modules/dfamazonconnector/cron.php --shop=1
Dwa uruchomienia nigdy się nie nakładają: blokada nie pozwala rozpocząć drugiego przebiegu, dopóki trwa pierwszy. Przy każdym przebiegu moduł importuje zamówienia, potwierdza wysyłki, wysyła faktury, anulowania i zwroty pieniędzy, odczytuje zwroty i stan FBA, anonimizuje dane kupujących, dla których minął termin, a następnie wysyła oczekujące oferty, stany i ceny w postaci zbiorczych feedów. Gdy Amazon ogranicza liczbę wywołań, moduł czeka i ponawia próbę w ograniczonym czasie na przebieg. Przycisk Nowy token unieważnia poprzedni URL.

Pulpit
Pulpit pokazuje oferty aktywne i z błędem, zamówienia Amazon z ostatnich 14 dni w FBM i FBA, zadania oczekujące, najczęstsze błędy ofert wraz z poprawką, stan każdego marketplace’u oraz historię ostatnich synchronizacji z liczbą wywołań ograniczonych przez Amazon i błędów. Baner sygnalizuje cron zatrzymany od ponad godziny.

Kolejka i błędy
Zakładka Kolejka i błędy zlicza zadania według typu (oferty, ceny, stany, faktury, anulowania, zwroty pieniędzy) i według statusu. Błędy są grupowane według przyczyny: każda grupa podaje wyjaśnienie, poprawkę do wprowadzenia i link do odpowiedniego ekranu. Ponawiaj lub usuwaj zadania zbiorczo i przeglądaj ostatnie feedy i raporty wysłane do Amazon.

Zamówienia
Zamówienia są odczytywane przez API Orders v2026-01-01 od wybranej daty początkowej. Zamówienie oczekujące na płatność jest zapamiętywane, ale nie jest tworzone; zostaje zaimportowane, gdy tylko Amazon zmieni jego status na „do wysyłki”. Import jest idempotentny: blokada dla każdego zamówienia Amazon oraz numer zamówienia zapisany jako identyfikator transakcji zapobiegają powstaniu duplikatów, nawet jeśli działają dwa crony lub przebieg zostanie przerwany w trakcie.
Każde zaimportowane zamówienie tworzy lub wykorzystuje ponownie klienta-gościa (jednego na kupującego albo jednego klienta dla wszystkich zamówień Amazon), bez newslettera i ofert partnerów, adres dostawy oraz zamówienie PrestaShop z przewoźnikiem Amazon, cenami i kosztami wysyłki z Amazon oraz opcjonalnie datą zakupu z Amazon. Zamówienia do kraju wyłączonego w Twoim sklepie są importowane bez ponownego włączania tego kraju. Fakturę numeruje PrestaShop według Twojej zwykłej numeracji i nigdy nie jest ona numerowana ponownie.
Zamówienia FBA są importowane po wysłaniu przez Amazon, z dedykowanym statusem. Przy opcji „Zamówienia FBA nie zmieniają stanu sklepu” ilość jest zwracana do stanu po utworzeniu zamówienia: nigdy nie jest odejmowana dwa razy.

Zakładka Zamówienia wyświetla zamówienia Amazon z filtrami „Do wysyłki”, „Prośby o anulowanie”, „Błędy importu”, „FBA” i „Zwrócone”. Niezaimportowane zamówienie pokazuje przyczynę i poprawkę (nieznany SKU, niezainstalowana waluta, nieskonfigurowany kraj…) oraz przycisk Ponów.

Wysyłki, faktury, anulowania i zwroty pieniędzy
Blok Amazon na stronie zamówienia zbiera wszystkie działania dotyczące zamówienia.
- Wysyłka: gdy zamówienie otrzyma jeden ze statusów wybranych w ustawieniach, moduł wysyła do Amazon kod przewoźnika, numer przesyłki i datę wysyłki. Amazon wymaga numeru przesyłki: bez niego nic nie jest wysyłane, a blok to sygnalizuje. Tabela mapowania przewoźników przypisuje każdemu przewoźnikowi PrestaShop kod Amazon; zmień przewoźnika zamówienia przed wysyłką, aby został wysłany właściwy kod. Przycisk Potwierdź wysyłkę teraz pozwala nie czekać na cron.
- Faktura: jeśli korzystasz z usługi obliczania VAT Amazon z przesyłaniem własnych faktur, faktura PDF z PrestaShop jest wysyłana po potwierdzeniu wysyłki. Jej status (wysłana, oczekująca, odrzucona) jest widoczny w zamówieniu. Amazon odrzuca przesłanie, jeśli w Seller Central włączone jest automatyczne generowanie faktur przez Amazon.
- Zwrot pieniędzy: zwróć całość lub część zamówienia, pozycja po pozycji, z powodem z listy Amazon. Kwota nie może przekroczyć zapłaconej sumy. Amazon zwraca pieniądze kupującemu, a następnie zwrot jest odczytywany i odnotowywany w zamówieniu.

Gdy kupujący prosi o anulowanie niewysłanego zamówienia, na liście i w zamówieniu pojawia się czerwony alert z powodem. Nie wysyłaj zamówienia: anuluj je na Amazon z poziomu bloku albo włącz Anuluj na Amazon, gdy zamówienie zostanie anulowane w PrestaShop. Anulowanie na prośbę kupującego jest wysyłane z powodem BuyerCanceled. I odwrotnie: zamówienie anulowane po stronie Amazon otrzymuje wybrany status anulowania, bez e-maila do klienta.

Przy opcji Odczytuj zwroty Amazon zwroty pieniędzy wykonane w Seller Central są odczytywane przez API Finances i odnotowywane w zamówieniu PrestaShop. Gdy wszystkie jednostki zostaną zwrócone, zamówienie otrzymuje wybrany status.
Dane kupującego
Sekcja Dane kupującego w ustawieniach stosuje zasady Amazon dotyczące danych osobowych:
- Anonimizuj dane kupującego po (dni): imię i nazwisko, ulica, kod pocztowy, telefon i e-mail kupującego są zastępowane po upływie tej liczby dni od wysyłki (domyślnie 30 przy nowej instalacji). Kraj, miasto, firma, kwoty i faktury są zachowywane. Polityka ochrony danych Amazon wymaga, aby nie przechowywać tych danych dłużej niż 30 dni po dostawie, chyba że wymaga tego prawo. Jeśli musisz ponownie generować faktury, pobierz je wcześniej.
- Blokuj e-maile sklepu do kupujących z Amazon: potwierdzenia, faktury, zmiany statusu i e-maile marketingowe PrestaShop nie są wysyłane do kupujących z Amazon. Komunikacją z kupującym zarządza Amazon; Twoje własne powiadomienia o zamówieniach nadal docierają.
- Przechowuj logi (dni): logi nigdy nie zawierają danych osobowych kupujących ani danych uwierzytelniających.

Alerty i logi
Codzienny e-mail z alertami jest wysyłany do wybranych odbiorców tylko wtedy, gdy jest coś do zrobienia: prośby o anulowanie, niepotwierdzone zamówienia, niezaimportowane zamówienia, odrzucone faktury, oferty z błędem, odrzucone feedy, zatrzymany cron. Zakładka Logi przechowuje każdą operację wraz ze szczegółami technicznymi, z możliwością filtrowania według poziomu i kanału.
Uprawnienia pracowników
Moduł respektuje uprawnienia profilu pracownika do zakładki Konektor Amazon. Profil tylko do odczytu widzi wszystko, ale nie może zmieniać ustawień ani danych uwierzytelniających, ani wysyłać anulowania, zwrotu pieniędzy czy publikacji; interfejs to sygnalizuje.
Rozwiązywanie problemów
Test połączenia kończy się niepowodzeniem
Sprawdź region, ID klienta LWA, sekret i refresh token. Refresh token odpowiada jednej aplikacji i jednemu kontu: wygeneruj go ponownie po każdej zmianie ról aplikacji.
Oferta ma błąd
Otwórz Kolejka i błędy lub kartę produktu: każdy błąd Amazon jest tam wyjaśniony wraz z poprawką. Kod 90220 oznacza brakujący wymagany atrybut, który należy uzupełnić w mapowaniu; kod 90188 oznacza nierozpoznany EAN. Użyj Sprawdź w Amazon, aby zweryfikować poprawkę przed wysłaniem.
Zamówienie nie zostało zaimportowane
Przyczyna jest pokazana w zakładce Zamówienia. Najczęściej jest to SKU Amazon, który nie odpowiada żadnemu produktowi: powiąż istniejące oferty lub popraw indeks, a następnie kliknij Ponów. Sprawdź też, czy waluta marketplace’u jest zainstalowana w PrestaShop.
Stany lub ceny się nie aktualizują
Sprawdź ostatnią synchronizację na pulpicie i oczekujące zadania. Aktualizacje są wysyłane przy następnym przebiegu crona, a Amazon przetwarza je w ciągu kilku minut. Aby wymusić pełną wysyłkę, użyj Wyślij ponownie wszystkie ilości.
Ograniczenia
- Moduł został przetestowany na symulatorze wiernie odwzorowującym dokumentację SP-API: zanim opublikujesz cały katalog, zrób pierwszą próbę na kilku produktach. Moduł nie gwarantuje sprzedaży ani zgodności z zasadami Amazon: odpowiadasz za swoje oferty, swój VAT i ochronę danych na swoim hostingu.
- Wymagane atrybuty różnią się w zależności od typu produktu i marketplace’u: wyświetlane pokrycie zależy od ostatniego wczytania schematu.
- Zamówienie wysłane w kilku paczkach nie jest potwierdzane pozycja po pozycji: wszystkie pozycje są potwierdzane razem.
- Cron jest nadal wymagany; moduł nie korzysta z powiadomień Amazon.