DataFirefly Shopify Migrator — Guide complet

Présentation

DataFirefly Shopify Migrator est un module PrestaShop 8 et 9 qui exporte l’intégralité d’un catalogue vers Shopify, avec deux modes au choix : CSV (génération de fichiers prêts à importer manuellement via l’admin Shopify, sans clé API) ou API (push direct vers une boutique Shopify connectée via l’Admin REST API 2026-04).

Le module gère huit entités, dans l’ordre où elles doivent typiquement être migrées :

• Produits — fiches complètes, déclinaisons jusqu’à 3 groupes d’attributs, images, stocks, prix HT ou TTC, balises SEO préservées via metafields global title_tag/description_tag
• Collections — catégories PrestaShop converties en custom collections avec image et description
• Pages CMS — pages PrestaShop converties en pages Shopify avec slug et meta SEO
• Clients — fiches client + adresse par défaut + statistiques de commandes, tagués imported-prestashop
• Commandes — export CSV consultatif uniquement (Shopify n’accepte pas d’import natif des commandes via CSV standard)
• Redirections 301 — table de correspondance anciennes URLs PrestaShop → nouvelles URLs Shopify pour préserver le référencement
• Repair images et Variant images — deux jobs de réparation pour récupérer les images que Shopify a silencieusement perdues pendant le fetch asynchrone, et pour rattacher chaque déclinaison Shopify à son image
• Features → Metafields — push des caractéristiques produits PrestaShop comme metafields Shopify avec création automatique des Metafield Definitions via GraphQL

L’architecture est asynchrone par jobs : chaque migration crée un job en base, ensuite traité par lots configurables via un worker cron protégé par token. Le rate limit de Shopify est respecté automatiquement (1,8 req/s, retry 429), et un mapping persistant en base relie les identifiants PrestaShop aux identifiants Shopify pour permettre les redirections et éviter les doublons en cas de relance.

Prérequis

• PrestaShop 8.0 à 9.x
• PHP 7.4 à 8.3
• Pour le mode API : une boutique Shopify cible (plan Basic suffit), un compte Shopify Partners ou un accès au Shopify Dev Dashboard
• Pour le mode cron : la possibilité de planifier une URL côté hébergeur (crontab, cron-as-a-service, ou Plesk/cPanel)
• Côté serveur : extensions PHP curl et iconv activées

Installation

1. Téléchargez le ZIP depuis votre compte client DataFirefly (espace Téléchargements de la fiche produit).
2. Dans le back-office PrestaShop, allez dans Modules → Gestionnaire de modules → Téléverser un module, déposez le ZIP.
3. Cliquez sur Installer. Le module crée trois tables (jobs, mapping, log) et un onglet dédié dans Paramètres avancés → Shopify Migrator.
4. Cliquez sur Configurer pour accéder à l’interface principale.

Choisir entre mode CSV et mode API

Mode CSV

Le module génère des fichiers CSV au format natif attendu par Shopify Admin (Products Import, Customers Import, URL Redirects Import). Vous téléchargez chaque fichier depuis l’onglet Jobs puis l’importez manuellement dans Shopify.

Avantages : aucune clé API à configurer, possibilité d’inspecter et d’ajuster les fichiers avant import, traitement très rapide côté PrestaShop.

Limites : les collections Shopify n’ont pas d’import CSV natif (le fichier généré sert de référence), et les commandes ne sont jamais importables en CSV standard côté Shopify.

Mode API

Le module envoie chaque entité directement à votre boutique Shopify via l’API Admin REST 2026-04, avec gestion du rate limit, retry automatique sur erreur 429, et mapping persistant des IDs pour permettre les redirections automatiques et l’idempotence des relances.

Avantages : migration de bout en bout en une commande, redirections poussées directement, collections créées automatiquement avec attachement des produits, parfait pour les gros catalogues.

Limites : nécessite une app Shopify avec les bons scopes, et certaines organisations Shopify créées après avril 2025 sont GraphQL-only (le module reste compatible REST pour les organisations standard).

Mode API : créer l’app Shopify

Création de l’app dans le Dev Dashboard

1. Connectez-vous au Shopify Dev Dashboard (dev.shopify.com/dashboard) avec votre compte Partners.
2. Cliquez sur Create app, donnez-lui un nom (par exemple « Migrator »), puis confirmez.
3. Dans l’écran de configuration, l’App URL peut être laissée à n’importe quelle valeur HTTPS valide. Elle n’est utilisée que pour l’OAuth, ce qui ne concerne pas notre cas.

Configuration des scopes

Dans Configuration → Admin API integration → Configure access scopes, activez les scopes suivants :

• 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 (uniquement si vous utilisez l’entité Features → Metafields)

Cliquez sur Save.

Installation sur la boutique cible

1. Dans Distribution, choisissez Custom distribution et ajoutez votre boutique Shopify cible.
2. Cliquez sur le lien d’installation généré, qui ouvre l’écran de consentement merchant côté Shopify Admin.
3. Validez l’installation : vous obtenez l’écran final de l’app.

Récupération du Client ID et du Client Secret

Dans Settings → Credentials de l’app, copiez le Client ID, puis cliquez sur l’icône œil à côté de Secret pour le révéler et le copier.

Mode API : configuration des credentials

Dans l’onglet Settings du module, choisissez le mode Shopify Admin REST API, puis renseignez :

• Shopify store domain — soit le nom court (my-store) soit le domaine complet (my-store.myshopify.com).
• API version — par défaut 2026-04, la version stable courante.
• Authentication method — deux choix sont possibles :

Méthode 1 : Admin access token

Pour les rares cas où vous disposez déjà d’un token Admin API valide (custom app legacy ou token obtenu manuellement via OAuth). Collez le token dans le champ dédié et sauvegardez.

Méthode 2 : Client Credentials Grant (recommandée)

Le module échange votre Client ID + Client Secret contre un Admin API access token via le flow OAuth Client Credentials Grant. Le token est mis en cache (24 h), automatiquement renouvelé moins de 5 minutes avant son expiration. Aucune intervention manuelle pendant la migration.

Renseignez les deux champs et sauvegardez. Cliquez sur Test connection : le module affiche le nom de votre boutique Shopify et le temps restant avant expiration du token.

Migration des produits

L’export produits est le plus complexe. Il gère les produits, les déclinaisons (jusqu’à 3 groupes d’attributs comme Shopify l’autorise), les images (URL absolue depuis votre PrestaShop), les stocks, les prix, les fabricants utilisés comme vendor, les catégories converties en tags et type, les balises SEO préservées via les metafields global.title_tag et global.description_tag.

Lancer le job

1. Dans Run a migration, sélectionnez la carte Products.
2. Cliquez sur Create export job. Le job apparaît dans la liste de l’onglet Jobs avec le statut pending.
3. Si vous avez configuré le cron, le worker le prend en charge dans la minute qui suit. Sinon cliquez sur le bouton Run now pour le faire avancer synchronement (limité par le timeout PHP, environ 30 secondes).

Suivi de la progression

L’onglet Jobs auto-actualise toutes les 10 secondes. Chaque ligne affiche le statut (pending/running/done/failed/cancelled), le pourcentage d’avancement, le nombre de succès et d’erreurs, et un bouton de logs déroulant qui affiche les 30 dernières lignes du journal.

Cas du mode CSV

Le fichier job_X_products.csv est généré au format Shopify Products Import. Téléchargez-le depuis la liste des jobs, puis dans Shopify Admin allez dans Products → Import et déposez le fichier. Shopify gère ensuite le traitement de son côté, avec une notification par email à la fin.

Migration des collections

Les catégories PrestaShop (hors racine et hors catégorie ID 1) deviennent des custom collections Shopify, avec leur titre, description, image, balises SEO et le slug nettoyé. En mode API, les produits déjà migrés sont automatiquement attachés à chaque collection via l’endpoint /collects.json.

Migration des pages CMS

Les pages PrestaShop actives sont exportées en pages Shopify avec leur titre, contenu HTML (les URLs d’images relatives sont automatiquement résolues en URL absolues vers votre domaine PrestaShop), slug et balises SEO.

Migration des clients

Pour chaque client actif et non supprimé, le module exporte le nom, l’email, l’adresse par défaut, le total dépensé, le nombre de commandes valides, et l’opt-in newsletter. Chaque client reçoit le tag imported-prestashop pour faciliter le filtrage ultérieur.

Migration des commandes (CSV uniquement)

L’export commandes est consultatif : Shopify ne propose pas d’import natif des commandes via CSV standard. Le fichier généré contient toutes les informations utiles pour archive ou analyse : référence, date, statut, client, adresses de facturation et livraison, devise, totaux HT et TTC, transporteur, suivi, et une ligne par produit acheté.

Vous pouvez filtrer par plage de dates dans le formulaire de création du job (champs Orders from et Orders to).

Pour les utilisateurs Shopify Plus, des outils tiers comme Matrixify acceptent ce format en entrée pour effectuer une véritable réimportation.

Migration des redirections 301

C’est le point clé pour préserver votre référencement le jour du basculement de domaine. Le module lit la table de mapping construite par les exports précédents (produits, collections, pages) et génère un CSV à deux colonnes au format natif Shopify URL Redirects, avec les anciennes URLs PrestaShop en première colonne et les nouvelles URLs Shopify en seconde.

En mode API, le module pousse directement chaque redirection via POST /redirects.json. En mode CSV, importez le fichier dans Shopify Admin via Online Store → Navigation → URL Redirects → Import.

Filtres d’exclusion (v1.1)

Deux filtres optionnels permettent d’exclure des produits de l’export, configurables dans Settings → Product filters (exclusions).

Exclure des catégories

Champ texte avec une liste d’IDs de catégories PrestaShop séparés par des virgules. Un produit appartenant à au moins une de ces catégories est exclu de l’export Products. Les catégories elles-mêmes restent migrées par l’entité Collections (utile si une catégorie technique n’a pas vocation à être affichée mais peut contenir des produits).

Exclure des préfixes de référence

Champ texte avec une liste de préfixes séparés par des virgules. Tout produit dont la référence commence par un de ces préfixes est exclu. Utile pour ne pas migrer des produits internes (NS pour non-vendables, HB pour hors-business, OBSOLETE- pour les gammes arrêtées, etc.). Les préfixes sont insensibles à la casse.

Réparation des images (v1.3)

Shopify télécharge les images de manière asynchrone après la création d’un produit : il fetch l’URL que vous avez fournie, et si ça échoue silencieusement (timeout, URL bloquée, fichier trop gros, format refusé), il ne renvoie aucune erreur. Le produit est créé « success » côté API mais sans image.

L’entité Repair images répare ces cas. Pour chaque produit du mapping :

1. GET /products/{shopify_id}/images.json pour compter les images actuelles côté Shopify.
2. Lecture des images correspondantes en PrestaShop.
3. Si Shopify a déjà autant d’images que PS → le produit est sauté.
4. Sinon : suppression des images Shopify partielles, puis upload de chaque image PS via base64 attachment (mode synchrone, Shopify confirme la création immédiatement), avec fallback URL pour les fichiers de plus de 3 MB.

Mode API obligatoire. Idempotent : vous pouvez relancer le job autant de fois que nécessaire.

Variant images (v1.4)

Une fois les images principales en place, il reste à associer chaque déclinaison Shopify à son image correspondante. L’entité Variant images s’en charge : pour chaque produit du mapping, elle interroge la liste des variantes et des images Shopify, puis croise avec les relations product_attribute_image de PrestaShop.

La correspondance variante PS → variante Shopify utilise d’abord le SKU (référence de la déclinaison), avec un fallback par tuple d’options (option1/option2/option3 en minuscules) si la référence est vide.

La correspondance image PS → image Shopify se fait par alignement de position : la N-ième image PS correspond à la N-ième image Shopify. C’est valable tant que vous n’avez pas réorganisé manuellement les images dans l’admin Shopify.

Idempotent : un variant déjà sur le bon image_id est sauté (loggé already_ok). Le journal compte par produit : assigned / already_ok / missing_image / missing_variant.

Features → Metafields (v1.5)

Les caractéristiques produits PrestaShop (Catalogue → Attributs et Caractéristiques → Caractéristiques) sont poussées comme metafields Shopify sous le namespace custom, avec création automatique des Metafield Definitions pour qu’elles soient éditables depuis l’admin Shopify.

Phase A : creation des Definitions (premier lot)

Au premier batch du job, le module liste toutes les features distinctes du shop et crée pour chacune une Metafield Definition via la mutation GraphQL metafieldDefinitionCreate. Les definitions déjà existantes (code TAKEN ou DUPLICATE_KEY) sont silencieusement ignorées.

Phase B : push des valeurs (chaque batch)

Pour chaque produit du mapping, le module liste les metafields custom.* existants, puis pour chaque feature PS effectue un upsert : PUT si la clé existe avec une valeur différente, POST si la clé n’existe pas. Les valeurs déjà identiques sont sautées.

Conversion nom → clé

Le nom de la feature PrestaShop est converti en clé metafield Shopify par translittération ASCII, mise en minuscules, remplacement des caractères non alphanumériques par des underscores, troncature à 30 caractères. Exemples :

• Matière principale devient matiere_principale
• Poids (kg) devient poids_kg
• Couleur devient couleur

Worker cron

Le module expose un endpoint front protégé par token qui traite un job par tick, à raison de 20 lots par tick. L’URL complète avec token est affichée dans l’onglet Run a migration, avec un bouton de copie.

Exemple d’entrée crontab pour un tick par minute :

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

Sans cron configuré, vous pouvez toujours faire avancer un job à la main avec le bouton Run now de la liste des jobs (avancement synchrone, limité par le timeout PHP du back-office, environ 30 secondes).

Ordre recommandé des jobs

Pour une migration complète sans surprise, lancez les jobs dans cet ordre :

1. Products — crée le mapping PS→Shopify pour les produits, utilisé par toutes les étapes suivantes.
2. Collections — crée le mapping pour les catégories et attache automatiquement les produits.
3. Pages — crée le mapping pour les pages CMS.
4. Customers — indépendant du reste.
5. Orders — CSV consultatif uniquement, lancement à votre rythme.
6. Repair images (si nécessaire) — répare les images perdues pendant le fetch asynchrone Shopify.
7. Variant images — réassocie chaque déclinaison à son image.
8. Features → Metafields — pousse les caractéristiques produits comme metafields visibles.
9. Redirects — en dernier, consomme tout le mapping construit ci-dessus.

Limites connues (v1)

• Une seule langue est exportée par migration (la langue sélectionnée dans Settings). La v2 ajoutera le mapping des langues PrestaShop vers Shopify Markets et Translate & Adapt.
• Les commandes sont exportées au format CSV consultatif uniquement.
• Les mots de passe clients ne sont pas migrés.
• Les déclinaisons sont limitées à 3 groupes d’attributs (limite Shopify Option1/Option2/Option3).
• Les images sont servies depuis l’URL publique de votre PrestaShop : gardez votre PS en ligne pendant l’import Shopify, et au minimum pendant l’éventuel job Repair images.

Dépannage

Shopify API error: Not Found

Vérifiez en priorité le champ API version dans Settings : il doit être 2026-04 (les anciennes versions comme 2024-10 sont retirées). Vérifiez aussi que votre app est bien installée sur la boutique cible dans Distribution.

Shopify API error: Invalid API key or access token

Le token a expiré (CCG : durée de vie 24 h, rafraîchi automatiquement) ou l’app a été désinstallée. Cliquez sur Test connection pour forcer un renouvellement du token CCG. Si l’erreur persiste, allez dans Shopify Admin → Apps and sales channels et vérifiez que l’app Migrator est bien dans la liste des applications installées.

This action requires merchant approval for write_X scope

Vous avez modifié les scopes après l’installation initiale de l’app, le merchant n’a pas eu l’occasion de les approuver. Désinstallez l’app dans Shopify Admin puis réinstallez-la via le lien de Distribution du Dev Dashboard. L’écran de consentement merchant apparaîtra à nouveau avec les nouveaux scopes.

shop_not_permitted lors de l’échange CCG

Votre boutique Shopify n’est pas dans la même organization que votre app Dev Dashboard. Soit rattachez la boutique à votre organization Partners, soit utilisez un token Admin obtenu manuellement (Authorization Code Grant OAuth, hors périmètre du module).

Cardinality violation: Subquery returns more than 1 row

Bug corrigé en v1.2.1. Mettez à jour vers la dernière version du module.

Beaucoup de fiches Shopify sont arrivées sans image

C’est le comportement Shopify documenté pour les images push via URL. Lancez le job Repair images en mode API : il détecte les fiches avec moins d’images que PS et republie tout en base64 (mode synchrone, garantit l’arrivée).

Beaucoup de « missing_variant » dans les logs de Variant images

Le SKU de la déclinaison Shopify ne correspond pas à la référence du product_attribute PrestaShop, et le fallback par tuple d’options n’a pas matché non plus. Vérifiez que vos déclinaisons PS ont bien des références renseignées, ou contactez le support DataFirefly pour un ajustement personnalisé du matching.

Ressources

• Fiche produit DataFirefly Shopify Migrator (téléchargements, achat, licence)
• Documentation officielle Shopify Admin REST API : shopify.dev/docs/api/admin-rest
• Documentation Shopify Client Credentials Grant : shopify.dev/docs/apps/build/authentication-authorization/access-tokens/client-credentials-grant
• Support DataFirefly : hello@datafirefly.com