DataFirefly Shopify Migrator — Komplettes Handbuch

Übersicht

DataFirefly Shopify Migrator ist ein PrestaShop-8- und 9-Modul, das den gesamten Katalog nach Shopify exportiert, mit zwei Modi zur Auswahl: CSV (erzeugt Dateien zum manuellen Import über den Shopify-Admin, ohne API-Schlüssel) oder API (direkter Push an einen verbundenen Shopify-Shop über die Admin REST API 2026-04).

Das Modul verwaltet acht Entitäten, in der typischen Migrationsreihenfolge:

• Produkte — vollständige Produktdatensätze, Varianten bis zu 3 Attributgruppen, Bilder, Bestände, Preise netto oder brutto, SEO-Meta erhalten über die Metafields global.title_tag/description_tag
• Kollektionen — PrestaShop-Kategorien werden in Custom Collections mit Bild und Beschreibung umgewandelt
• CMS-Seiten — PrestaShop-Seiten werden in Shopify-Seiten mit Slug und SEO-Meta umgewandelt
• Kunden — Kundendatensätze + Standardadresse + Bestellstatistiken, mit dem Tag imported-prestashop versehen
• Bestellungen — nur konsultativer CSV-Export (Shopify akzeptiert keinen nativen Bestellimport über Standard-CSV)
• 301-Weiterleitungen — Zuordnungstabelle von alten PrestaShop-URLs zu neuen Shopify-URLs zur Erhaltung des Rankings
• Repair images und Variant images — zwei Reparatur-Jobs, um Bilder wiederherzustellen, die Shopify während des asynchronen Fetches stillschweigend verloren hat, und um jede Shopify-Variante mit ihrem Bild zu verknüpfen
• Features → Metafields — schiebt PrestaShop-Produkteigenschaften als Shopify-Metafields mit automatischer Metafield-Definition-Erstellung über GraphQL

Die Architektur ist asynchron und job-basiert: Jede Migration erstellt einen Job in der Datenbank, der dann in konfigurierbaren Stapeln über einen tokengeschützten Cron-Worker verarbeitet wird. Shopify-Rate-Limits werden automatisch beachtet (1,8 Req/s, 429-Retry), und ein persistentes ID-Mapping in der Datenbank verknüpft PrestaShop-Identifikatoren mit Shopify-Identifikatoren, um Weiterleitungen zu ermöglichen und Duplikate bei Wiederholungen zu vermeiden.

Voraussetzungen

• PrestaShop 8.0 bis 9.x
• PHP 7.4 bis 8.3
• Für API-Modus: ein Ziel-Shopify-Shop (Basic-Plan reicht), ein Shopify-Partners-Konto oder Zugang zum Shopify Dev Dashboard
• Für Cron-Modus: die Möglichkeit, eine URL beim Hoster zu planen (Crontab, Cron-as-a-Service, oder Plesk/cPanel)
• Serverseitig: PHP-Erweiterungen curl und iconv aktiviert

Installation

1. Laden Sie das ZIP aus Ihrem DataFirefly-Kundenkonto herunter (Downloads-Bereich der Produktseite).
2. Gehen Sie im PrestaShop-Back-Office zu Module → Modulverwaltung → Modul hochladen, legen Sie das ZIP ab.
3. Klicken Sie auf Installieren. Das Modul erstellt drei Tabellen (jobs, mapping, log) und einen eigenen Tab unter Erweiterte Parameter → Shopify Migrator.
4. Klicken Sie auf Konfigurieren, um zur Hauptoberfläche zu gelangen.

Wahl zwischen CSV-Modus und API-Modus

CSV-Modus

Das Modul erzeugt CSV-Dateien im nativen Format, das von Shopify Admin erwartet wird (Products Import, Customers Import, URL Redirects Import). Sie laden jede Datei aus dem Jobs-Tab herunter und importieren sie manuell in Shopify.

Vorteile: kein API-Schlüssel zu konfigurieren, Möglichkeit, die Dateien vor dem Import zu prüfen und anzupassen, sehr schnelle Verarbeitung auf PrestaShop-Seite.

Einschränkungen: Shopify-Kollektionen haben keinen nativen CSV-Import (die erzeugte Datei dient als Referenz), und Bestellungen sind auf Shopify-Seite niemals über Standard-CSV importierbar.

API-Modus

Das Modul sendet jede Entität direkt an Ihren Shopify-Shop über die Admin REST API 2026-04, mit Rate-Limit-Handhabung, automatischem Retry bei 429-Fehlern und persistentem ID-Mapping für automatische Weiterleitungen und idempotente Wiederholungen.

Vorteile: Ende-zu-Ende-Migration in einem Befehl, Weiterleitungen direkt gepusht, Kollektionen automatisch mit Produktanhang erstellt, perfekt für große Kataloge.

Einschränkungen: erfordert eine Shopify-App mit den richtigen Scopes, und einige Shopify-Organisationen, die nach April 2025 erstellt wurden, sind GraphQL-only (das Modul bleibt REST-kompatibel für Standardorganisationen).

API-Modus: Erstellen der Shopify-App

Erstellen der App im Dev Dashboard

1. Melden Sie sich am Shopify Dev Dashboard (dev.shopify.com/dashboard) mit Ihrem Partners-Konto an.
2. Klicken Sie auf Create app, geben Sie einen Namen ein (zum Beispiel „Migrator“) und bestätigen Sie.
3. Im Konfigurationsbildschirm kann die App URL auf einen beliebigen gültigen HTTPS-Wert belassen werden. Sie wird nur für OAuth verwendet, was unseren Fall nicht betrifft.

Konfigurieren der Scopes

Aktivieren Sie unter Configuration → Admin API integration → Configure access scopes die folgenden Scopes:

• 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 (nur wenn Sie die Entität Features → Metafields verwenden)

Klicken Sie auf Save.

Installation im Ziel-Shop

1. Wählen Sie unter Distribution die Option Custom distribution und fügen Sie Ihren Ziel-Shopify-Shop hinzu.
2. Klicken Sie auf den generierten Installationslink, der den Merchant-Einwilligungsbildschirm auf der Shopify-Admin-Seite öffnet.
3. Bestätigen Sie die Installation: Sie erreichen den finalen App-Bildschirm.

Abrufen von Client ID und Client Secret

Kopieren Sie in Settings → Credentials der App die Client ID, klicken Sie dann auf das Augensymbol neben Secret, um es anzuzeigen und zu kopieren.

API-Modus: Konfigurieren der Anmeldedaten

Wählen Sie im Tab Settings des Moduls den Modus Shopify Admin REST API, dann füllen Sie aus:

• Shopify store domain — entweder der Kurzname (my-store) oder die vollständige Domain (my-store.myshopify.com).
• API version — Standard ist 2026-04, die aktuelle Stable-Version.
• Authentication method — zwei Optionen sind verfügbar:

Methode 1: Admin access token

Für die seltenen Fälle, in denen Sie bereits einen gültigen Admin-API-Token besitzen (Legacy-Custom-App oder manuell über OAuth erhaltener Token). Fügen Sie den Token in das dafür vorgesehene Feld ein und speichern Sie.

Methode 2: Client Credentials Grant (empfohlen)

Das Modul tauscht Ihre Client ID + Client Secret gegen einen Admin-API-Access-Token über den OAuth-Client-Credentials-Grant-Flow aus. Der Token wird zwischengespeichert (24 h), weniger als 5 Minuten vor seinem Ablauf automatisch erneuert. Keine manuelle Intervention während der Migration erforderlich.

Füllen Sie beide Felder aus und speichern Sie. Klicken Sie auf Test connection: Das Modul zeigt den Namen Ihres Shopify-Shops und die verbleibende Zeit bis zum Tokenablauf.

Produktmigration

Der Produktexport ist der komplexeste. Er verwaltet Produkte, Varianten (bis zu 3 Attributgruppen, wie Shopify erlaubt), Bilder (absolute URL von Ihrem PrestaShop), Bestände, Preise, Hersteller als Vendor, Kategorien in Tags und Type umgewandelt, SEO-Meta erhalten über die Metafields global.title_tag und global.description_tag.

Job starten

1. Wählen Sie in Run a migration die Karte Products.
2. Klicken Sie auf Create export job. Der Job erscheint in der Liste des Jobs-Tabs mit dem Status pending.
3. Wenn Sie den Cron konfiguriert haben, übernimmt der Worker ihn innerhalb der nächsten Minute. Sonst klicken Sie auf die Schaltfläche Run now, um ihn synchron voranzubringen (begrenzt durch PHP-Timeout, etwa 30 Sekunden).

Fortschrittsverfolgung

Der Jobs-Tab aktualisiert sich automatisch alle 10 Sekunden. Jede Zeile zeigt den Status (pending/running/done/failed/cancelled), den Fortschritt in Prozent, die Erfolgs- und Fehleranzahl sowie eine ausklappbare Log-Schaltfläche, die die letzten 30 Logzeilen anzeigt.

Fall CSV-Modus

Die Datei job_X_products.csv wird im Shopify-Products-Import-Format erzeugt. Laden Sie sie aus der Job-Liste herunter, gehen Sie dann im Shopify-Admin zu Products → Import und legen Sie die Datei ab. Shopify übernimmt dann die Verarbeitung auf seiner Seite mit einer E-Mail-Benachrichtigung am Ende.

Kollektionsmigration

PrestaShop-Kategorien (außer Root und außer Kategorie-ID 1) werden zu Shopify-Custom Collections mit Titel, Beschreibung, Bild, SEO-Meta und bereinigtem Slug. Im API-Modus werden bereits migrierte Produkte automatisch über den Endpunkt /collects.json an jede Kollektion angehängt.

CMS-Seiten-Migration

Aktive PrestaShop-Seiten werden als Shopify-Seiten mit ihrem Titel, HTML-Inhalt (relative Bild-URLs werden automatisch in absolute URLs zu Ihrer PrestaShop-Domain aufgelöst), Slug und SEO-Meta exportiert.

Kundenmigration

Für jeden aktiven, nicht gelöschten Kunden exportiert das Modul Name, E-Mail, Standardadresse, Gesamtumsatz, Anzahl gültiger Bestellungen und Newsletter-Opt-in. Jeder Kunde erhält das Tag imported-prestashop für einfachere spätere Filterung.

Bestellmigration (nur CSV)

Der Bestellexport ist konsultativ: Shopify bietet keinen nativen Bestellimport über Standard-CSV. Die erzeugte Datei enthält alle nützlichen Informationen für Archiv oder Analyse: Referenz, Datum, Status, Kunde, Rechnungs- und Lieferadressen, Währung, Summen netto und brutto, Spediteur, Tracking und eine Zeile pro gekauftem Produkt.

Sie können nach Datumsbereich im Job-Erstellungsformular filtern (Felder Orders from und Orders to).

Für Shopify-Plus-Benutzer akzeptieren Drittanbietertools wie Matrixify dieses Format als Eingabe für einen echten Reimport.

301-Weiterleitungs-Migration

Dies ist der Schlüsselpunkt, um Ihr Ranking am Tag der Domainumstellung zu erhalten. Das Modul liest die durch die vorherigen Exporte (Produkte, Kollektionen, Seiten) erstellte Mapping-Tabelle und generiert eine zweispaltige CSV im nativen Shopify-URL-Redirects-Format, mit alten PrestaShop-URLs in der ersten Spalte und neuen Shopify-URLs in der zweiten.

Im API-Modus pusht das Modul jede Weiterleitung direkt über POST /redirects.json. Im CSV-Modus importieren Sie die Datei im Shopify-Admin über Online Store → Navigation → URL Redirects → Import.

Ausschlussfilter (v1.1)

Zwei optionale Filter ermöglichen es, Produkte vom Export auszuschließen, konfigurierbar in Settings → Product filters (exclusions).

Kategorien ausschließen

Textfeld mit einer kommagetrennten Liste von PrestaShop-Kategorie-IDs. Ein Produkt, das zu mindestens einer dieser Kategorien gehört, wird vom Produkt-Export ausgeschlossen. Die Kategorien selbst bleiben über die Entität Collections migriert (nützlich, wenn eine technische Kategorie nicht angezeigt werden soll, aber Produkte enthalten kann).

Referenzpräfixe ausschließen

Textfeld mit einer kommagetrennten Liste von Präfixen. Jedes Produkt, dessen Referenz mit einem dieser Präfixe beginnt, wird ausgeschlossen. Nützlich, um interne Produkte (NS für nicht verkaufbar, HB für off-business, OBSOLETE- für eingestellte Reihen usw.) zu überspringen. Präfixe sind nicht groß-/kleinschreibungssensitiv.

Bilder reparieren (v1.3)

Shopify lädt Bilder asynchron nach der Erstellung eines Produkts herunter: Es holt die von Ihnen bereitgestellte URL, und wenn das stillschweigend fehlschlägt (Timeout, blockierte URL, zu große Datei, abgelehntes Format), gibt es keinen Fehler zurück. Das Produkt wird auf der API-Seite „success“ erstellt, aber ohne Bilder.

Die Entität Repair images behebt diese Fälle. Für jedes Produkt im Mapping:

1. GET /products/{shopify_id}/images.json, um aktuelle Bilder auf Shopify zu zählen.
2. Lesen der entsprechenden Bilder auf PrestaShop.
3. Wenn Shopify bereits so viele Bilder wie PS hat → Produkt übersprungen.
4. Sonst: partielle Shopify-Bilder löschen, dann jedes PS-Bild über Base64-Attachment hochladen (synchroner Modus, Shopify bestätigt die Erstellung sofort), mit URL-Fallback für Dateien über 3 MB.

API-Modus erforderlich. Idempotent: Sie können den Job beliebig oft erneut ausführen.

Variant images (v1.4)

Sobald die Hauptbilder vorhanden sind, muss jede Shopify-Variante noch mit ihrem entsprechenden Bild verknüpft werden. Die Entität Variant images übernimmt dies: Für jedes Produkt im Mapping fragt sie die Liste der Varianten und Bilder auf Shopify ab und kreuzt sie mit den product_attribute_image-Beziehungen von PrestaShop.

Der Abgleich PS-Variante → Shopify-Variante verwendet zuerst die SKU (Variantenreferenz), mit einem Fallback nach Optionstupel (option1/option2/option3 in Kleinschreibung), wenn die Referenz leer ist.

Der Abgleich PS-Bild → Shopify-Bild erfolgt über Positionsausrichtung: Das N-te PS-Bild entspricht dem N-ten Shopify-Bild. Dies gilt, solange Sie Bilder im Shopify-Admin nicht manuell neu angeordnet haben.

Idempotent: Eine Variante, die bereits auf der korrekten image_id ist, wird übersprungen (geloggt already_ok). Das Log zählt pro Produkt: assigned / already_ok / missing_image / missing_variant.

Features → Metafields (v1.5)

PrestaShop-Produkteigenschaften (Katalog → Attribute & Eigenschaften → Eigenschaften) werden als Shopify-Metafields unter dem Namespace custom gepusht, mit automatischer Metafield-Definition-Erstellung, damit sie im Shopify-Admin editierbar sind.

Phase A: Definition-Erstellung (erster Stapel)

Beim ersten Batch des Jobs listet das Modul alle distinkten Features im Shop auf und erstellt für jedes eine Metafield Definition über die GraphQL-Mutation metafieldDefinitionCreate. Bestehende Definitions (TAKEN- oder DUPLICATE_KEY-Code) werden stillschweigend ignoriert.

Phase B: Werte-Push (jeder Stapel)

Für jedes Produkt im Mapping listet das Modul vorhandene custom.*-Metafields auf, dann führt es für jedes PS-Feature einen Upsert durch: PUT wenn der Schlüssel existiert mit einem anderen Wert, POST wenn der Schlüssel nicht existiert. Bereits identische Werte werden übersprungen.

Name-zu-Schlüssel-Konvertierung

Der PrestaShop-Feature-Name wird in einen Shopify-Metafield-Schlüssel umgewandelt durch ASCII-Transliteration, Kleinschreibung, Ersetzen nicht-alphanumerischer Zeichen durch Unterstriche, Kürzung auf 30 Zeichen. Beispiele:

• Hauptmaterial wird zu hauptmaterial
• Gewicht (kg) wird zu gewicht_kg
• Farbe wird zu farbe

Cron-Worker

Das Modul stellt einen tokengeschützten Front-Endpunkt bereit, der einen Job pro Tick verarbeitet, mit 20 Stapeln pro Tick. Die vollständige URL mit Token wird im Tab Run a migration angezeigt, mit einer Kopierschaltfläche.

Beispiel-Crontab-Eintrag für einen Tick pro Minute:

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

Ohne konfigurierten Cron können Sie einen Job jederzeit manuell mit der Schaltfläche Run now in der Jobliste vorantreiben (synchrones Vorankommen, begrenzt durch PHP-Back-Office-Timeout, etwa 30 Sekunden).

Empfohlene Job-Reihenfolge

Für eine vollständige Migration ohne Überraschungen führen Sie die Jobs in dieser Reihenfolge aus:

1. Products — erstellt das PS→Shopify-Mapping für Produkte, das von allen nachfolgenden Schritten verwendet wird.
2. Collections — erstellt das Mapping für Kategorien und hängt automatisch Produkte an.
3. Pages — erstellt das Mapping für CMS-Seiten.
4. Customers — unabhängig vom Rest.
5. Orders — nur konsultative CSV, in Ihrem eigenen Tempo ausführen.
6. Repair images (falls erforderlich) — behebt während des asynchronen Shopify-Fetches verlorene Bilder.
7. Variant images — verknüpft jede Variante mit ihrem Bild neu.
8. Features → Metafields — pusht Produkteigenschaften als sichtbare Metafields.
9. Redirects — als Letztes, konsumiert das gesamte oben erstellte Mapping.

Bekannte Einschränkungen (v1)

• Nur eine Sprache wird pro Migration exportiert (die in Settings ausgewählte Sprache). v2 wird die Zuordnung von PrestaShop-Sprachen zu Shopify Markets und Translate & Adapt hinzufügen.
• Bestellungen werden nur als konsultative CSV exportiert.
• Kundenpasswörter werden nicht migriert.
• Varianten sind auf 3 Attributgruppen begrenzt (Shopify-Limit Option1/Option2/Option3).
• Bilder werden von der öffentlichen URL Ihres PrestaShop bereitgestellt: Halten Sie Ihr PS während des Shopify-Imports online, und mindestens während eines eventuellen Repair-images-Jobs.

Fehlerbehebung

Shopify API error: Not Found

Prüfen Sie zuerst das Feld API version in Settings: Es muss 2026-04 sein (ältere Versionen wie 2024-10 sind eingestellt). Prüfen Sie auch, dass Ihre App ordnungsgemäß im Ziel-Shop unter Distribution installiert ist.

Shopify API error: Invalid API key or access token

Der Token ist abgelaufen (CCG: 24-h-Lebensdauer, automatisch erneuert) oder die App wurde deinstalliert. Klicken Sie auf Test connection, um eine CCG-Token-Erneuerung zu erzwingen. Wenn der Fehler bestehen bleibt, gehen Sie zu Shopify Admin → Apps and sales channels und prüfen Sie, dass die Migrator-App in der Liste der installierten Anwendungen erscheint.

This action requires merchant approval for write_X scope

Sie haben Scopes nach der initialen App-Installation geändert, der Merchant hatte keine Gelegenheit, sie zu genehmigen. Deinstallieren Sie die App im Shopify-Admin, installieren Sie sie dann über den Distribution-Link im Dev Dashboard neu. Der Merchant-Einwilligungsbildschirm erscheint mit den neuen Scopes erneut.

shop_not_permitted während des CCG-Austauschs

Ihr Shopify-Shop ist nicht in derselben Organization wie Ihre Dev-Dashboard-App. Verknüpfen Sie entweder den Shop mit Ihrer Partners-Organization, oder verwenden Sie einen manuell erhaltenen Admin-Token (Authorization Code Grant OAuth, außerhalb des Modulumfangs).

Cardinality violation: Subquery returns more than 1 row

In v1.2.1 behobener Fehler. Aktualisieren Sie auf die neueste Modulversion.

Viele Shopify-Produkte kamen ohne Bilder an

Dies ist das dokumentierte Shopify-Verhalten für über URL gepushte Bilder. Starten Sie den Repair images-Job im API-Modus: Er erkennt Produkte mit weniger Bildern als PS und veröffentlicht alles in Base64 erneut (synchroner Modus, garantierte Ankunft).

Viele „missing_variant“-Einträge in Variant-images-Logs

Die Shopify-Varianten-SKU stimmt nicht mit der PrestaShop-product_attribute-Referenz überein, und der Optionstupel-Fallback hat auch nicht gematcht. Prüfen Sie, dass Ihre PS-Varianten Referenzen ausgefüllt haben, oder kontaktieren Sie den DataFirefly-Support für eine benutzerdefinierte Matching-Anpassung.

Ressourcen

• DataFirefly Shopify Migrator Produktseite (Downloads, Kauf, Lizenz)
• Offizielle Shopify Admin REST API Dokumentation: shopify.dev/docs/api/admin-rest
• Shopify Client Credentials Grant Dokumentation: shopify.dev/docs/apps/build/authentication-authorization/access-tokens/client-credentials-grant
• DataFirefly-Support: hello@datafirefly.com