DataFirefly Shopify Migrator — Guida completa

Panoramica

DataFirefly Shopify Migrator è un modulo PrestaShop 8 e 9 che esporta l’intero catalogo verso Shopify, con due modalità a scelta: CSV (genera file pronti per essere importati manualmente tramite l’admin Shopify, senza chiave API) o API (push diretto verso un negozio Shopify collegato tramite l’Admin REST API 2026-04).

Il modulo gestisce otto entità, nell’ordine tipico di migrazione:

• Prodotti — schede complete, varianti fino a 3 gruppi di attributi, immagini, scorte, prezzi IVA esclusa o IVA inclusa, meta SEO preservati tramite metafields global.title_tag/description_tag
• Collezioni — categorie PrestaShop convertite in custom collections con immagine e descrizione
• Pagine CMS — pagine PrestaShop convertite in pagine Shopify con slug e meta SEO
• Clienti — schede cliente + indirizzo predefinito + statistiche ordini, taggati imported-prestashop
• Ordini — esportazione CSV consultiva soltanto (Shopify non accetta import nativo di ordini tramite CSV standard)
• Reindirizzamenti 301 — tabella di corrispondenza tra vecchi URL PrestaShop e nuovi URL Shopify per preservare il posizionamento
• Repair images e Variant images — due job di riparazione per recuperare le immagini che Shopify ha perso silenziosamente durante il fetch asincrono, e per collegare ogni variante Shopify alla sua immagine
• Features → Metafields — push delle caratteristiche prodotto PrestaShop come metafields Shopify con creazione automatica delle Metafield Definitions tramite GraphQL

L’architettura è asincrona e basata su job: ogni migrazione crea un job in base dati, poi elaborato in lotti configurabili tramite un worker cron protetto da token. Il rate limit di Shopify è rispettato automaticamente (1,8 req/s, retry 429), e un mapping persistente in base dati collega gli identificatori PrestaShop agli identificatori Shopify per consentire i reindirizzamenti ed evitare duplicati nei rilanci.

Prerequisiti

• PrestaShop 8.0 a 9.x
• PHP 7.4 a 8.3
• Per modalità API: un negozio Shopify destinazione (il piano Basic basta), un account Shopify Partners o accesso al Shopify Dev Dashboard
• Per modalità cron: la possibilità di pianificare un URL sull’hosting (crontab, cron-as-a-service, o Plesk/cPanel)
• Lato server: estensioni PHP curl e iconv attivate

Installazione

1. Scarichi lo ZIP dal suo account cliente DataFirefly (sezione Download della scheda prodotto).
2. Nel back-office PrestaShop, vada in Moduli → Gestore moduli → Carica un modulo, rilasci lo ZIP.
3. Clicchi su Installa. Il modulo crea tre tabelle (jobs, mapping, log) e una scheda dedicata in Parametri avanzati → Shopify Migrator.
4. Clicchi su Configura per accedere all’interfaccia principale.

Scegliere tra modalità CSV e modalità API

Modalità CSV

Il modulo genera file CSV nel formato nativo atteso da Shopify Admin (Products Import, Customers Import, URL Redirects Import). Scarica ogni file dalla scheda Jobs e lo importa manualmente in Shopify.

Vantaggi: nessuna chiave API da configurare, possibilità di ispezionare e regolare i file prima dell’import, elaborazione molto rapida lato PrestaShop.

Limitazioni: le collezioni Shopify non hanno import CSV nativo (il file generato serve da riferimento), e gli ordini non sono mai importabili in CSV standard lato Shopify.

Modalità API

Il modulo invia ogni entità direttamente al suo negozio Shopify tramite l’Admin REST API 2026-04, con gestione del rate limit, retry automatico in caso di errore 429, e mapping persistente degli ID per consentire i reindirizzamenti automatici e l’idempotenza dei rilanci.

Vantaggi: migrazione end-to-end in un comando, reindirizzamenti spinti direttamente, collezioni create automaticamente con collegamento dei prodotti, perfetto per i grandi cataloghi.

Limitazioni: richiede un’app Shopify con gli scope corretti, e alcune organizzazioni Shopify create dopo aprile 2025 sono GraphQL-only (il modulo resta compatibile REST per le organizzazioni standard).

Modalità API: creare l’app Shopify

Creazione dell’app nel Dev Dashboard

1. Si connetta al Shopify Dev Dashboard (dev.shopify.com/dashboard) con il suo account Partners.
2. Clicchi su Create app, le dia un nome (per esempio “Migrator”), e confermi.
3. Nella schermata di configurazione, l’App URL può essere lasciato a qualsiasi valore HTTPS valido. È utilizzato solo per OAuth, cosa che non riguarda il nostro caso.

Configurazione degli scope

In Configuration → Admin API integration → Configure access scopes, attivi i seguenti scope:

• 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 (unicamente se utilizza l’entità Features → Metafields)

Clicchi su Save.

Installazione sul negozio destinazione

1. In Distribution, scelga Custom distribution e aggiunga il suo negozio Shopify destinazione.
2. Clicchi sul link di installazione generato, che apre la schermata di consenso merchant lato Shopify Admin.
3. Convalidi l’installazione: arriva alla schermata finale dell’app.

Recupero del Client ID e del Client Secret

In Settings → Credentials dell’app, copi il Client ID, poi clicchi sull’icona occhio accanto a Secret per rivelarlo e copiarlo.

Modalità API: configurazione delle credenziali

Nella scheda Settings del modulo, scelga la modalità Shopify Admin REST API, poi compili:

• Shopify store domain — il nome corto (my-store) o il dominio completo (my-store.myshopify.com).
• API version — per impostazione predefinita 2026-04, la versione stable corrente.
• Authentication method — due opzioni disponibili:

Metodo 1: Admin access token

Per i rari casi in cui dispone già di un token Admin API valido (custom app legacy o token ottenuto manualmente tramite OAuth). Incolli il token nel campo dedicato e salvi.

Metodo 2: Client Credentials Grant (raccomandato)

Il modulo scambia il suo Client ID + Client Secret per un Admin API access token tramite il flow OAuth Client Credentials Grant. Il token è memorizzato in cache (24 h), automaticamente rinnovato meno di 5 minuti prima della sua scadenza. Nessun intervento manuale durante la migrazione.

Compili i due campi e salvi. Clicchi su Test connection: il modulo mostra il nome del suo negozio Shopify e il tempo rimanente prima della scadenza del token.

Migrazione dei prodotti

L’esportazione dei prodotti è la più complessa. Gestisce i prodotti, le varianti (fino a 3 gruppi di attributi come Shopify autorizza), le immagini (URL assoluto dal suo PrestaShop), le scorte, i prezzi, i produttori utilizzati come vendor, le categorie convertite in tag e type, i meta SEO preservati tramite i metafields global.title_tag e global.description_tag.

Avviare il job

1. In Run a migration, selezioni la card Products.
2. Clicchi su Create export job. Il job appare nella lista della scheda Jobs con lo stato pending.
3. Se ha configurato il cron, il worker lo prende in carico entro il minuto successivo. Altrimenti clicchi sul pulsante Run now per farlo avanzare sincronicamente (limitato dal timeout PHP, circa 30 secondi).

Monitoraggio dell’avanzamento

La scheda Jobs si auto-aggiorna ogni 10 secondi. Ogni riga mostra lo stato (pending/running/done/failed/cancelled), la percentuale di avanzamento, il numero di successi e errori, e un pulsante log a discesa che mostra le ultime 30 righe del registro.

Caso della modalità CSV

Il file job_X_products.csv è generato nel formato Shopify Products Import. Lo scarichi dalla lista dei job, poi nell’Shopify Admin vada in Products → Import e rilasci il file. Shopify gestisce poi l’elaborazione dalla sua parte, con una notifica via email alla fine.

Migrazione delle collezioni

Le categorie PrestaShop (escluse radice ed esclusa la categoria ID 1) diventano custom collections Shopify, con il loro titolo, descrizione, immagine, meta SEO e slug ripulito. In modalità API, i prodotti già migrati sono collegati automaticamente a ogni collezione tramite l’endpoint /collects.json.

Migrazione delle pagine CMS

Le pagine PrestaShop attive sono esportate in pagine Shopify con il loro titolo, contenuto HTML (gli URL di immagini relativi sono risolti automaticamente in URL assoluti verso il suo dominio PrestaShop), slug e meta SEO.

Migrazione dei clienti

Per ogni cliente attivo e non eliminato, il modulo esporta nome, email, indirizzo predefinito, totale speso, numero di ordini validi, e opt-in newsletter. Ogni cliente riceve il tag imported-prestashop per facilitare il filtraggio successivo.

Migrazione degli ordini (CSV soltanto)

L’esportazione degli ordini è consultiva: Shopify non offre import nativo degli ordini tramite CSV standard. Il file generato contiene tutte le informazioni utili per archivio o analisi: riferimento, data, stato, cliente, indirizzi di fatturazione e spedizione, valuta, totali IVA esclusa e inclusa, corriere, tracking, e una riga per prodotto acquistato.

Può filtrare per intervallo di date nel form di creazione del job (campi Orders from e Orders to).

Per gli utenti Shopify Plus, strumenti di terze parti come Matrixify accettano questo formato come input per effettuare una vera reimportazione.

Migrazione dei reindirizzamenti 301

È il punto chiave per preservare il suo posizionamento il giorno del cambio di dominio. Il modulo legge la tabella di mapping costruita dalle esportazioni precedenti (prodotti, collezioni, pagine) e genera un CSV a due colonne nel formato nativo Shopify URL Redirects, con i vecchi URL PrestaShop nella prima colonna e i nuovi URL Shopify nella seconda.

In modalità API, il modulo spinge direttamente ogni reindirizzamento tramite POST /redirects.json. In modalità CSV, importi il file nell’Shopify Admin tramite Online Store → Navigation → URL Redirects → Import.

Filtri di esclusione (v1.1)

Due filtri opzionali permettono di escludere prodotti dall’esportazione, configurabili in Settings → Product filters (exclusions).

Escludere categorie

Campo testo con una lista di ID di categorie PrestaShop separati da virgole. Un prodotto che appartiene ad almeno una di queste categorie è escluso dall’esportazione Products. Le categorie in sé restano migrate dall’entità Collections (utile se una categoria tecnica non deve essere visualizzata ma può contenere prodotti).

Escludere prefissi di riferimento

Campo testo con una lista di prefissi separati da virgole. Ogni prodotto la cui riferimento inizia con uno di questi prefissi è escluso. Utile per non migrare prodotti interni (NS per non vendibili, HB per fuori business, OBSOLETE- per gamme dismesse, ecc.). I prefissi sono insensibili al maiuscolo/minuscolo.

Riparazione delle immagini (v1.3)

Shopify scarica le immagini in modo asincrono dopo la creazione di un prodotto: fa fetch dell’URL fornito, e se fallisce silenziosamente (timeout, URL bloccato, file troppo grande, formato rifiutato), non restituisce alcun errore. Il prodotto è creato “success” lato API ma senza immagine.

L’entità Repair images ripara questi casi. Per ogni prodotto del mapping:

1. GET /products/{shopify_id}/images.json per contare le immagini correnti lato Shopify.
2. Lettura delle immagini corrispondenti in PrestaShop.
3. Se Shopify ha già tante immagini quante PS → il prodotto è saltato.
4. Altrimenti: eliminazione delle immagini Shopify parziali, poi upload di ogni immagine PS tramite base64 attachment (modalità sincrona, Shopify conferma la creazione immediatamente), con fallback URL per i file superiori a 3 MB.

Modalità API obbligatoria. Idempotente: può rilanciare il job tante volte quanto necessario.

Variant images (v1.4)

Una volta che le immagini principali sono al loro posto, resta associare ogni variante Shopify alla sua immagine corrispondente. L’entità Variant images se ne occupa: per ogni prodotto del mapping, interroga la lista delle varianti e immagini Shopify, poi incrocia con le relazioni product_attribute_image di PrestaShop.

La corrispondenza variante PS → variante Shopify utilizza prima lo SKU (riferimento della variante), con un fallback per tupla di opzioni (option1/option2/option3 in minuscolo) se il riferimento è vuoto.

La corrispondenza immagine PS → immagine Shopify si fa per allineamento di posizione: l’N-esima immagine PS corrisponde all’N-esima immagine Shopify. Vale finché non ha riorganizzato manualmente le immagini nell’admin Shopify.

Idempotente: una variante già sul corretto image_id è saltata (loggata already_ok). Il registro conta per prodotto: assigned / already_ok / missing_image / missing_variant.

Features → Metafields (v1.5)

Le caratteristiche prodotti PrestaShop (Catalogo → Attributi e Caratteristiche → Caratteristiche) sono spinte come metafields Shopify sotto il namespace custom, con creazione automatica delle Metafield Definitions affinché siano modificabili dall’admin Shopify.

Fase A: creazione delle Definitions (primo lotto)

Al primo batch del job, il modulo elenca tutte le feature distinte dello shop e crea per ciascuna una Metafield Definition tramite la mutation GraphQL metafieldDefinitionCreate. Le definitions già esistenti (codice TAKEN o DUPLICATE_KEY) sono ignorate silenziosamente.

Fase B: push dei valori (ogni batch)

Per ogni prodotto del mapping, il modulo elenca i metafields custom.* esistenti, poi per ogni feature PS effettua un upsert: PUT se la chiave esiste con un valore diverso, POST se la chiave non esiste. I valori già identici sono saltati.

Conversione nome → chiave

Il nome della feature PrestaShop è convertito in chiave metafield Shopify tramite translitterazione ASCII, passaggio a minuscolo, sostituzione di caratteri non alfanumerici con underscore, troncamento a 30 caratteri. Esempi:

• Materiale principale diventa materiale_principale
• Peso (kg) diventa peso_kg
• Colore diventa colore

Worker cron

Il modulo espone un endpoint front protetto da token che elabora un job per tick, al ritmo di 20 lotti per tick. L’URL completo con token è visualizzato nella scheda Run a migration, con un pulsante di copia.

Esempio di voce crontab per un tick al minuto:

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

Senza cron configurato, può sempre far avanzare un job manualmente con il pulsante Run now della lista dei job (avanzamento sincrono, limitato dal timeout PHP del back-office, circa 30 secondi).

Ordine raccomandato dei job

Per una migrazione completa senza sorprese, lanci i job in quest’ordine:

1. Products — crea il mapping PS→Shopify per i prodotti, utilizzato da tutti i passi successivi.
2. Collections — crea il mapping per le categorie e collega automaticamente i prodotti.
3. Pages — crea il mapping per le pagine CMS.
4. Customers — indipendente dal resto.
5. Orders — CSV consultivo soltanto, lancio al suo ritmo.
6. Repair images (se necessario) — ripara le immagini perse durante il fetch asincrono Shopify.
7. Variant images — riassocia ogni variante alla sua immagine.
8. Features → Metafields — spinge le caratteristiche prodotti come metafields visibili.
9. Redirects — per ultimo, consuma tutto il mapping costruito sopra.

Limitazioni note (v1)

• Solo una lingua è esportata per migrazione (la lingua selezionata in Settings). La v2 aggiungerà il mapping delle lingue PrestaShop verso Shopify Markets e Translate & Adapt.
• Gli ordini sono esportati in formato CSV consultivo soltanto.
• Le password dei clienti non sono migrate.
• Le varianti sono limitate a 3 gruppi di attributi (limite Shopify Option1/Option2/Option3).
• Le immagini sono servite dall’URL pubblico del suo PrestaShop: mantenga il suo PS online durante l’import Shopify, e come minimo durante l’eventuale job Repair images.

Risoluzione dei problemi

Shopify API error: Not Found

Verifichi in priorità il campo API version in Settings: deve essere 2026-04 (le versioni vecchie come 2024-10 sono ritirate). Verifichi anche che la sua app sia ben installata sul negozio destinazione in Distribution.

Shopify API error: Invalid API key or access token

Il token è scaduto (CCG: durata di vita 24 h, rinnovato automaticamente) o l’app è stata disinstallata. Clicchi su Test connection per forzare un rinnovo del token CCG. Se l’errore persiste, vada in Shopify Admin → Apps and sales channels e verifichi che l’app Migrator sia nella lista delle applicazioni installate.

This action requires merchant approval for write_X scope

Ha modificato gli scope dopo l’installazione iniziale dell’app, il merchant non ha avuto occasione di approvarli. Disinstalli l’app nell’Shopify Admin poi la reinstalli tramite il link di Distribution del Dev Dashboard. La schermata di consenso merchant apparirà di nuovo con i nuovi scope.

shop_not_permitted durante lo scambio CCG

Il suo negozio Shopify non è nella stessa organization della sua app Dev Dashboard. O colleghi il negozio alla sua organization Partners, o utilizzi un token Admin ottenuto manualmente (Authorization Code Grant OAuth, fuori dall’ambito del modulo).

Cardinality violation: Subquery returns more than 1 row

Bug corretto in v1.2.1. Aggiorni all’ultima versione del modulo.

Molte schede Shopify sono arrivate senza immagine

È il comportamento Shopify documentato per le immagini push tramite URL. Lanci il job Repair images in modalità API: rileva le schede con meno immagini di PS e ripubblica tutto in base64 (modalità sincrona, garantisce l’arrivo).

Molti “missing_variant” nei log di Variant images

Lo SKU della variante Shopify non corrisponde alla riferimento del product_attribute PrestaShop, e il fallback per tupla di opzioni non ha fatto match neanche lui. Verifichi che le sue varianti PS abbiano i riferimenti riempiti, o contatti il supporto DataFirefly per un aggiustamento personalizzato del matching.

Risorse

• Scheda prodotto DataFirefly Shopify Migrator (download, acquisto, licenza)
• Documentazione ufficiale Shopify Admin REST API: shopify.dev/docs/api/admin-rest
• Documentazione Shopify Client Credentials Grant: shopify.dev/docs/apps/build/authentication-authorization/access-tokens/client-credentials-grant
• Supporto DataFirefly: hello@datafirefly.com