DataFirefly Shopify Migrator: kompletny przewodnik

Prezentacja

DataFirefly Shopify Migrator to moduł dla PrestaShop 8 i 9, który eksportuje cały katalog do Shopify, w dwóch trybach do wyboru: CSV (generowanie plików gotowych do ręcznego importu przez panel Shopify, bez klucza API) lub API (bezpośredni push do połączonego sklepu Shopify przez Admin REST API 2026-04).

Moduł obsługuje osiem encji, w kolejności, w jakiej powinny być typowo migrowane:

• Produkty: kompletne karty, warianty do 3 grup atrybutów, zdjęcia, stany magazynowe, ceny netto lub brutto, tagi SEO zachowane przez metafields global title_tag/description_tag
• Kolekcje: kategorie PrestaShop konwertowane na custom collections ze zdjęciem i opisem
• Strony CMS: strony PrestaShop konwertowane na strony Shopify ze slugiem i meta SEO
• Klienci: karty klientów, adres domyślny i statystyki zamówień, otagowane jako imported-prestashop
• Zamówienia: wyłącznie poglądowy eksport CSV (Shopify nie oferuje natywnego importu zamówień przez standardowy CSV)
• Przekierowania 301: tabela odpowiedników starych adresów PrestaShop i nowych adresów Shopify dla zachowania pozycjonowania
• Repair images i Variant images: dwa zadania naprawcze do odzyskania zdjęć, które Shopify po cichu zgubił podczas asynchronicznego pobierania, oraz do powiązania każdego wariantu Shopify z jego zdjęciem
• Features do Metafields: push cech produktów PrestaShop jako metafields Shopify z automatycznym tworzeniem Metafield Definitions przez GraphQL

Architektura jest asynchroniczna, oparta na zadaniach: każda migracja tworzy zadanie w bazie, następnie przetwarzane w konfigurowalnych partiach przez workera cron chronionego tokenem. Limit zapytań Shopify jest respektowany automatycznie (1,8 req/s, ponawianie przy 429), a trwałe mapowanie w bazie łączy identyfikatory PrestaShop z identyfikatorami Shopify, aby umożliwić przekierowania i uniknąć duplikatów przy ponownym uruchomieniu.

Wymagania

• PrestaShop 8.0 do 9.x
• PHP 7.4 do 8.3
• Dla trybu API: docelowy sklep Shopify (plan Basic wystarczy), konto Shopify Partners lub dostęp do Shopify Dev Dashboard
• Dla trybu cron: możliwość zaplanowania wywołania adresu URL po stronie hostingu (crontab, cron-as-a-service albo Plesk/cPanel)
• Po stronie serwera: włączone rozszerzenia PHP curl i iconv

Instalacja

1. Pobierz ZIP ze swojego konta klienta DataFirefly (strefa Pobierania na karcie produktu).
2. W back-office PrestaShop przejdź do Moduły / Menedżer modułów / Wgraj moduł i umieść ZIP.
3. Kliknij Zainstaluj. Moduł tworzy trzy tabele (jobs, mapping, log) i dedykowaną zakładkę w Parametrach zaawansowanych, Shopify Migrator.
4. Kliknij Konfiguruj, aby wejść do głównego interfejsu.

Wybór między trybem CSV a trybem API

Tryb CSV

Moduł generuje pliki CSV w natywnym formacie oczekiwanym przez Shopify Admin (Products Import, Customers Import, URL Redirects Import). Każdy plik pobierasz z zakładki Jobs, a następnie importujesz ręcznie w Shopify.

Zalety: brak klucza API do skonfigurowania, możliwość sprawdzenia i skorygowania plików przed importem, bardzo szybkie przetwarzanie po stronie PrestaShop.

Ograniczenia: kolekcje Shopify nie mają natywnego importu CSV (wygenerowany plik służy jako referencja), a zamówienia nigdy nie są importowalne przez standardowy CSV po stronie Shopify.

Tryb API

Moduł wysyła każdą encję bezpośrednio do Twojego sklepu Shopify przez Admin REST API 2026-04, z obsługą limitu zapytań, automatycznym ponawianiem przy błędzie 429 i trwałym mapowaniem ID, aby umożliwić automatyczne przekierowania i idempotencję ponownych uruchomień.

Zalety: migracja od początku do końca jedną komendą, przekierowania wysyłane bezpośrednio, kolekcje tworzone automatycznie z przypisaniem produktów, doskonałe dla dużych katalogów.

Ograniczenia: wymaga aplikacji Shopify z właściwymi zakresami, a niektóre organizacje Shopify utworzone po kwietniu 2025 są GraphQL-only (moduł pozostaje zgodny z REST dla organizacji standardowych).

Tryb API: tworzenie aplikacji Shopify

Tworzenie aplikacji w Dev Dashboard

1. Zaloguj się do Shopify Dev Dashboard (dev.shopify.com/dashboard) swoim kontem Partners.
2. Kliknij Create app, nadaj nazwę (na przykład „Migrator”) i zatwierdź.
3. W ekranie konfiguracji App URL może mieć dowolną prawidłową wartość HTTPS. Jest używany wyłącznie do OAuth, co nie dotyczy naszego przypadku.

Konfiguracja zakresów

W Configuration / Admin API integration / Configure access scopes aktywuj następujące zakresy:

• read_products, write_products
• read_customers, write_customers
• read_content, write_content
• read_inventory, write_inventory
• read_online_store_pages, write_online_store_pages
• read_online_store_navigation, write_online_store_navigation
• write_metaobject_definitions (wyłącznie jeśli używasz encji Features do Metafields)

Kliknij Save.

Instalacja na docelowym sklepie

1. W Distribution wybierz Custom distribution i dodaj swój docelowy sklep Shopify.
2. Kliknij wygenerowany link instalacyjny, który otwiera ekran zgody sprzedawcy po stronie Shopify Admin.
3. Zatwierdź instalację: otrzymasz finalny ekran aplikacji.

Pobranie Client ID i Client Secret

W Settings / Credentials aplikacji skopiuj Client ID, następnie kliknij ikonę oka obok Secret, aby go odsłonić i skopiować.

Tryb API: konfiguracja poświadczeń

W zakładce Settings modułu wybierz tryb Shopify Admin REST API, a następnie wprowadź:

• Shopify store domain: albo krótką nazwę (my-store), albo pełną domenę (my-store.myshopify.com).
• API version: domyślnie 2026-04, bieżąca stabilna wersja.
• Authentication method: możliwe są dwa warianty:

Metoda 1: Admin access token

Dla rzadkich przypadków, gdy dysponujesz już ważnym tokenem Admin API (aplikacja custom legacy lub token uzyskany ręcznie przez OAuth). Wklej token w dedykowane pole i zapisz.

Metoda 2: Client Credentials Grant (zalecana)

Moduł wymienia Twój Client ID i Client Secret na token dostępu Admin API przez przepływ OAuth Client Credentials Grant. Token jest buforowany (24 h) i automatycznie odnawiany na mniej niż 5 minut przed wygaśnięciem. Żadna ręczna interwencja podczas migracji nie jest potrzebna.

Wprowadź oba pola i zapisz. Kliknij Test connection: moduł wyświetli nazwę Twojego sklepu Shopify i czas pozostały do wygaśnięcia tokenu.

Migracja produktów

Eksport produktów jest najbardziej złożony. Obsługuje produkty, warianty (do 3 grup atrybutów, zgodnie z limitem Shopify), zdjęcia (absolutny adres URL z Twojego PrestaShop), stany magazynowe, ceny, producentów użytych jako vendor, kategorie konwertowane na tagi i typ oraz tagi SEO zachowane przez metafields global.title_tag i global.description_tag.

Uruchomienie zadania

1. W Run a migration wybierz kartę Products.
2. Kliknij Create export job. Zadanie pojawi się na liście w zakładce Jobs ze statusem pending.
3. Jeśli skonfigurowałeś cron, worker przejmie je w ciągu minuty. W przeciwnym razie kliknij przycisk Run now, aby popchnąć je synchronicznie (ograniczone timeoutem PHP, około 30 sekund).

Śledzenie postępu

Zakładka Jobs odświeża się automatycznie co 10 sekund. Każdy wiersz pokazuje status (pending/running/done/failed/cancelled), procent postępu, liczbę sukcesów i błędów oraz rozwijany przycisk dzienników wyświetlający 30 ostatnich linii dziennika.

Przypadek trybu CSV

Plik job_X_products.csv jest generowany w formacie Shopify Products Import. Pobierz go z listy zadań, a następnie w Shopify Admin przejdź do Products / Import i umieść plik. Shopify zajmie się dalszym przetwarzaniem po swojej stronie, z powiadomieniem e-mail na koniec.

Migracja kolekcji

Kategorie PrestaShop (poza korzeniem i poza kategorią ID 1) stają się custom collections Shopify, z tytułem, opisem, zdjęciem, tagami SEO i oczyszczonym slugiem. W trybie API już zmigrowane produkty są automatycznie przypisywane do każdej kolekcji przez endpoint /collects.json.

Migracja stron CMS

Aktywne strony PrestaShop są eksportowane jako strony Shopify z tytułem, treścią HTML (względne adresy zdjęć są automatycznie rozwiązywane na absolutne adresy do Twojej domeny PrestaShop), slugiem i tagami SEO.

Migracja klientów

Dla każdego aktywnego i nieusuniętego klienta moduł eksportuje imię i nazwisko, e-mail, adres domyślny, łączną kwotę wydatków, liczbę ważnych zamówień i zgodę na newsletter. Każdy klient otrzymuje tag imported-prestashop, aby ułatwić późniejsze filtrowanie.

Migracja zamówień (wyłącznie CSV)

Eksport zamówień jest poglądowy: Shopify nie oferuje natywnego importu zamówień przez standardowy CSV. Wygenerowany plik zawiera wszystkie użyteczne informacje do archiwum lub analizy: referencję, datę, status, klienta, adresy rozliczeniowe i dostawy, walutę, sumy netto i brutto, przewoźnika, śledzenie oraz jedną linię na zakupiony produkt.

W formularzu tworzenia zadania możesz filtrować po zakresie dat (pola Orders from i Orders to).

Dla użytkowników Shopify Plus narzędzia zewnętrzne, takie jak Matrixify, przyjmują ten format na wejściu i pozwalają wykonać prawdziwy reimport.

Migracja przekierowań 301

To kluczowy punkt dla zachowania pozycjonowania w dniu przełączenia domeny. Moduł czyta tabelę mapowania zbudowaną przez wcześniejsze eksporty (produkty, kolekcje, strony) i generuje dwukolumnowy plik CSV w natywnym formacie Shopify URL Redirects, ze starymi adresami PrestaShop w pierwszej kolumnie i nowymi adresami Shopify w drugiej.

W trybie API moduł wysyła każde przekierowanie bezpośrednio przez POST /redirects.json. W trybie CSV zaimportuj plik w Shopify Admin przez Online Store / Navigation / URL Redirects / Import.

Filtry wykluczeń (v1.1)

Dwa opcjonalne filtry pozwalają wykluczyć produkty z eksportu, konfigurowalne w Settings / Product filters (exclusions).

Wykluczanie kategorii

Pole tekstowe z listą ID kategorii PrestaShop oddzielonych przecinkami. Produkt należący do co najmniej jednej z tych kategorii jest wykluczany z eksportu Products. Same kategorie pozostają migrowane przez encję Collections (przydatne, jeśli kategoria techniczna nie ma być wyświetlana, ale może zawierać produkty).

Wykluczanie prefiksów referencji

Pole tekstowe z listą prefiksów oddzielonych przecinkami. Każdy produkt, którego referencja zaczyna się od jednego z tych prefiksów, jest wykluczany. Przydatne, aby nie migrować produktów wewnętrznych (NS dla niesprzedawalnych, HB dla poza biznesem, OBSOLETE- dla wycofanych gam itd.). Prefiksy nie rozróżniają wielkości liter.

Naprawa zdjęć (v1.3)

Shopify pobiera zdjęcia asynchronicznie po utworzeniu produktu: pobiera podany przez Ciebie adres URL, a jeśli to zawiedzie po cichu (timeout, zablokowany adres, zbyt duży plik, odrzucony format), nie zwraca żadnego błędu. Produkt jest utworzony jako „success” po stronie API, ale bez zdjęcia.

Encja Repair images naprawia te przypadki. Dla każdego produktu z mapowania:

1. GET /products/{shopify_id}/images.json, aby policzyć bieżące zdjęcia po stronie Shopify.
2. Odczyt odpowiadających zdjęć w PrestaShop.
3. Jeśli Shopify ma już tyle samo zdjęć co PS, produkt jest pomijany.
4. W przeciwnym razie: usunięcie częściowych zdjęć Shopify, następnie wysłanie każdego zdjęcia PS jako załącznik base64 (tryb synchroniczny, Shopify potwierdza utworzenie natychmiast), z fallbackiem na adres URL dla plików powyżej 3 MB.

Tryb API obowiązkowy. Idempotentne: możesz uruchamiać zadanie tyle razy, ile potrzeba.

Variant images (v1.4)

Gdy główne zdjęcia są już na miejscu, pozostaje powiązać każdy wariant Shopify z odpowiadającym mu zdjęciem. Zajmuje się tym encja Variant images: dla każdego produktu z mapowania odpytuje listę wariantów i zdjęć Shopify, a następnie krzyżuje ją z relacjami product_attribute_image z PrestaShop.

Dopasowanie wariantu PS do wariantu Shopify używa najpierw SKU (referencja wariantu), z fallbackiem po krotce opcji (option1/option2/option3 małymi literami), jeśli referencja jest pusta.

Dopasowanie zdjęcia PS do zdjęcia Shopify odbywa się przez wyrównanie pozycji: N-te zdjęcie PS odpowiada N-temu zdjęciu Shopify. Jest to prawidłowe, dopóki nie zmieniłeś ręcznie kolejności zdjęć w panelu Shopify.

Idempotentne: wariant już wskazujący na właściwe image_id jest pomijany (zapis already_ok). Dziennik zlicza per produkt: assigned / already_ok / missing_image / missing_variant.

Features do Metafields (v1.5)

Cechy produktów PrestaShop (Katalog / Atrybuty i Cechy / Cechy) są wysyłane jako metafields Shopify w namespace custom, z automatycznym tworzeniem Metafield Definitions, aby były edytowalne z panelu Shopify.

Faza A: tworzenie Definitions (pierwsza partia)

W pierwszej partii zadania moduł wylistowuje wszystkie odrębne cechy sklepu i tworzy dla każdej Metafield Definition przez mutację GraphQL metafieldDefinitionCreate. Już istniejące definicje (kod TAKEN lub DUPLICATE_KEY) są po cichu pomijane.

Faza B: push wartości (każda partia)

Dla każdego produktu z mapowania moduł wylistowuje istniejące metafields custom.*, a następnie dla każdej cechy PS wykonuje upsert: PUT, jeśli klucz istnieje z inną wartością, POST, jeśli klucz nie istnieje. Wartości już identyczne są pomijane.

Konwersja nazwy na klucz

Nazwa cechy PrestaShop jest konwertowana na klucz metafield Shopify przez transliterację ASCII, zamianę na małe litery, zastąpienie znaków niealfanumerycznych podkreśleniami i skrócenie do 30 znaków. Przykłady:

• Materiał główny staje się material_glowny
• Waga (kg) staje się waga_kg
• Kolor staje się kolor

Worker cron

Moduł udostępnia endpoint front chroniony tokenem, który przetwarza jedno zadanie na tick, po 20 partii na tick. Pełny adres z tokenem jest wyświetlany w zakładce Run a migration, z przyciskiem kopiowania.

Przykładowy wpis crontab dla jednego ticka na minutę:

* * * * * curl -s "https://twoj-prestashop.pl/index.php?fc=module&module=dfshopifymigrator&controller=cron&token=TWOJ_TOKEN" > /dev/null

Bez skonfigurowanego crona zawsze możesz popchnąć zadanie ręcznie przyciskiem Run now z listy zadań (postęp synchroniczny, ograniczony timeoutem PHP back-office, około 30 sekund).

Zalecana kolejność zadań

Dla kompletnej migracji bez niespodzianek uruchamiaj zadania w tej kolejności:

1. Products: tworzy mapowanie PS do Shopify dla produktów, używane przez wszystkie kolejne kroki.
2. Collections: tworzy mapowanie dla kategorii i automatycznie przypisuje produkty.
3. Pages: tworzy mapowanie dla stron CMS.
4. Customers: niezależne od reszty.
5. Orders: wyłącznie poglądowy CSV, uruchamiaj we własnym tempie.
6. Repair images (jeśli konieczne): naprawia zdjęcia utracone podczas asynchronicznego pobierania Shopify.
7. Variant images: ponownie łączy każdy wariant z jego zdjęciem.
8. Features do Metafields: wysyła cechy produktów jako widoczne metafields.
9. Redirects: na końcu, konsumuje całe mapowanie zbudowane powyżej.

Znane ograniczenia (v1)

• Na jedną migrację eksportowany jest jeden język (wybrany w Settings). Wersja v2 doda mapowanie języków PrestaShop na Shopify Markets oraz Translate i Adapt.
• Zamówienia są eksportowane wyłącznie w poglądowym formacie CSV.
• Hasła klientów nie są migrowane.
• Warianty są ograniczone do 3 grup atrybutów (limit Shopify Option1/Option2/Option3).
• Zdjęcia są serwowane z publicznego adresu Twojego PrestaShop: utrzymuj PS online podczas importu Shopify i co najmniej podczas ewentualnego zadania Repair images.

Rozwiązywanie problemów

Shopify API error: Not Found

W pierwszej kolejności sprawdź pole API version w Settings: musi mieć wartość 2026-04 (starsze wersje, takie jak 2024-10, zostały wycofane). Sprawdź też, czy Twoja aplikacja jest zainstalowana na docelowym sklepie w Distribution.

Shopify API error: Invalid API key or access token

Token wygasł (CCG: czas życia 24 h, odnawiany automatycznie) albo aplikacja została odinstalowana. Kliknij Test connection, aby wymusić odnowienie tokenu CCG. Jeśli błąd się utrzymuje, przejdź do Shopify Admin, Apps and sales channels i sprawdź, czy aplikacja Migrator znajduje się na liście zainstalowanych aplikacji.

This action requires merchant approval for write_X scope

Zmodyfikowałeś zakresy po pierwotnej instalacji aplikacji, a sprzedawca nie miał okazji ich zatwierdzić. Odinstaluj aplikację w Shopify Admin, następnie zainstaluj ją ponownie przez link Distribution z Dev Dashboard. Ekran zgody sprzedawcy pojawi się ponownie z nowymi zakresami.

shop_not_permitted podczas wymiany CCG

Twój sklep Shopify nie należy do tej samej organizacji co aplikacja Dev Dashboard. Albo przypisz sklep do swojej organizacji Partners, albo użyj tokenu Admin uzyskanego ręcznie (Authorization Code Grant OAuth, poza zakresem modułu).

Cardinality violation: Subquery returns more than 1 row

Błąd poprawiony w v1.2.1. Zaktualizuj moduł do najnowszej wersji.

Wiele kart Shopify dotarło bez zdjęcia

To udokumentowane zachowanie Shopify dla zdjęć wysyłanych przez adres URL. Uruchom zadanie Repair images w trybie API: wykrywa karty z mniejszą liczbą zdjęć niż w PS i publikuje wszystko ponownie w base64 (tryb synchroniczny, gwarantuje dotarcie).

Wiele wpisów „missing_variant” w dziennikach Variant images

SKU wariantu Shopify nie odpowiada referencji product_attribute w PrestaShop, a fallback po krotce opcji też nie dopasował. Sprawdź, czy Twoje warianty PS mają wypełnione referencje, albo skontaktuj się ze wsparciem DataFirefly w sprawie spersonalizowanej korekty dopasowania.

Zasoby

• Karta produktu DataFirefly Shopify Migrator (pobrania, zakup, licencja)
• Oficjalna dokumentacja Shopify Admin REST API: shopify.dev/docs/api/admin-rest
• Dokumentacja Shopify Client Credentials Grant: shopify.dev/docs/apps/build/authentication-authorization/access-tokens/client-credentials-grant
• Wsparcie DataFirefly: hello@datafirefly.com