Importazione ed esportazione dei prodotti in PrestaShop: metodi CSV, XML e API

Far entrare i prodotti in PrestaShop e riportarli fuori è il lavoro poco appariscente da cui prima o poi dipende ogni catalogo: una migrazione da un'altra piattaforma, un flusso notturno del fornitore che cambia 4.000 prezzi in poche ore, un ERP che gestisce le scorte e ha bisogno che PrestaShop le rispecchi. PrestaShop ti offre tre strumenti davvero diversi per farlo — l'importatore CSV integrato, la Webservice API e SQL Manager per l'esportazione — e l'errore più costoso che i commercianti commettono è scegliere quello sbagliato. Il lancio di 200 prodotti e una sincronizzazione notturna di 40.000 SKU non sono lo stesso lavoro, e lo strumento perfetto per uno dei due può cedere silenziosamente sull'altro. Questa guida riguarda nello specifico i dati di prodotto: catalogo, combinazioni, immagini, scorte e prezzi, in entrata e in uscita. (Se ciò che ti serve davvero è esportare dati di ordini e fatture da PrestaShop — per contabilità o riconciliazione — il percorso è diverso ed è spiegato in esportazioni CSV per ordini e fatture.)

Ultimo aggiornamento: giugno 2026.

L'importatore CSV integrato: da dove iniziano quasi tutti

PrestaShop include un importatore nativo in Parametri avanzati → Importa (il AdminImportController). Accetta CSV per prodotti, combinazioni, categorie, clienti, indirizzi, marchi (produttori), fornitori, alias e — quando la tua versione li espone — negozi; scegli prima il tipo di entità, poi carichi il file. Per un catalogo sotto qualche migliaio di prodotti, senza esigenze di sincronizzazione ricorrente, questa è la risposta giusta e puoi anche saltare la sezione sull'API. Il vantaggio è concreto: carichi l'intero negozio da un foglio di calcolo, dal pannello di amministrazione, senza sviluppatori e senza una riga di codice.

Le regole del formato CSV che causano la maggior parte degli errori

L'importatore non perdona gli errori di formato, e un file malformato è il motivo principale per cui un'importazione "non funziona". Sistema questi aspetti prima di caricare qualsiasi cosa:

• Codifica: UTF-8 senza BOM. Se hai creato il file in Excel, usa Salva con nome → CSV UTF-8 — il semplice "CSV" salva in Windows-1252 e trasforma ogni carattere accentato in mojibake (é diventa é). Se il file ha già un BOM, rimuovilo: sed -i '1s/^\xEF\xBB\xBF//' file.csv.
• Separatore: punto e virgola (;) per impostazione predefinita. Si può cambiare nella schermata di importazione, ma non passare mai alla virgola se le descrizioni contengono virgole — e le contengono praticamente sempre.
• Qualificatore di testo: virgolette doppie ("). Racchiudi qualsiasi campo che contiene il separatore o un'interruzione di riga.
• Fine riga: Unix LF è la scelta più sicura; CRLF è accettato, ma a volte introduce righe vuote fantasma che vengono importate come prodotti vuoti.
• Riga di intestazione: i nomi delle colonne devono corrispondere ai campi di PrestaShop, oppure li associ manualmente nella schermata successiva. L'importatore ricorda una mappatura con nome, quindi un file ricorrente del fornitore va mappato una sola volta.

Un file prodotto minimale:

ID;Active;Name;Categories;Price (tax excl.);Tax rules ID;Reference;Quantity;Description

L'impostazione che decide tra aggiornamento e duplicazione

È questa a creare problemi alla seconda importazione. L'importatore ha due modalità che sembrano quasi identiche, ma si comportano in modo opposto. Per impostazione predefinita crea righe. Per fargli aggiornare i prodotti esistenti invece di clonarli, devi spuntare "Use product reference as key" (oppure fornire la colonna ID reale e spuntare l'equivalente che usa l'ID come chiave). Saltala durante un aggiornamento prezzi e non aggiorni 4.000 prodotti — crei 4.000 duplicati e raddoppi il catalogo. Che cosa significa in pratica? Un flusso ricorrente del fornitore deve riportare un Reference stabile (o un ID) su ogni riga, e quella casella deve essere attiva, ogni singola volta.

Combinazioni: si importano a parte, e l'ordine conta

Le combinazioni (varianti) sono un'entità a sé — importi prima i prodotti padre, poi esegui una seconda importazione selezionando l'entità Combinations. Ogni riga fa riferimento al prodotto padre tramite ID o riferimento e contiene gruppo attributo, valore, impatto sul prezzo, quantità, EAN13 e riferimento della combinazione:

Product ID;Attribute (Name:Type:Position);Value (Value:Position);Reference;Supplier reference;EAN13;Impact on price;Quantity

La trappola classica: PrestaShop crea automaticamente gruppi di attributi e valori che non ha ancora visto, e li abbina in base alla stringa esatta. "Size", "size" e "SIZE" diventano tre gruppi di attributi separati, e il menu a discesa delle taglie finisce nel caos. Normalizza maiuscole, minuscole e grafia nel file prima dell'importazione, non dopo.

Immagini tramite URL — e perché qui il server può andare in crisi

Puoi popolare le immagini inserendo nella colonna immagini un elenco di URL separati da virgole; il primo diventa la copertina. A mettere in difficoltà sono i meccanismi interni, perché ogni URL avvia un download sincrono durante la richiesta di importazione:

• Tempesta di download: 5.000 prodotti × 3 immagini = 15.000 richieste HTTP dentro un solo processo di importazione. Un'importazione avviata via web andrà in timeout molto prima di concludersi. Lo schema affidabile è in due passaggi: prima importi i prodotti senza immagini, poi fai un secondo passaggio, in lotti più piccoli, solo per le immagini.
• Moltiplicazione delle miniature: ogni immagine importata viene rigenerata in ogni formato definito in Design → Image Settings. Otto formati significano otto operazioni di ridimensionamento per immagine. Prima di una grande importazione immagini, rimuovi temporaneamente i formati inutilizzati, poi rigenera una sola volta alla fine.
• "Delete all images before import": questa opzione rimuove tutte le immagini esistenti sui prodotti corrispondenti — comprese quelle aggiunte a mano — prima di caricare il nuovo set. È lo strumento giusto per una risincronizzazione pulita e un disastro se non era ciò che intendevi fare.

Far sopravvivere importazioni grandi: timeout, memoria e CLI

L'importatore web lavora senza troppi problemi fino a circa 5.000 prodotti. Oltre quella soglia smetti di combattere con il formato CSV e inizi a combattere con PHP e il server web:

• Tempo di esecuzione: il valore standard di max_execution_time, 30 secondi, è inutile per un file grande. Portalo a 600+ in php.ini (o per singola importazione tramite il worker), altrimenti non completerai nemmeno un lotto.
• Memoria: un CSV da 50 MB con circa 20.000 prodotti richiede 256 MB+ di memoria PHP; imposta memory_limit a 512M per avere margine.
• Lavora a lotti: dividi in file da 1.000–2.000 righe. Se fallisce la riga 7.400, rilanci un solo lotto, non tutti i 40.000 prodotti.
• Disattiva l'indicizzazione durante l'esecuzione: in Parametri negozio → Ricerca disattiva "Index products on save" e non rigenerare immagini a metà importazione. Reindicizza una sola volta alla fine. Sui cataloghi grandi è il risparmio di tempo più importante — reindicizzare ogni riga rappresenta gran parte del tempo totale.
• Sposta i lavori grandi fuori dalla richiesta web: il core di PrestaShop non include un comando console prestashop:import integrato, quindi per una migrazione una tantum di 10.000+ prodotti le soluzioni pratiche sono lottizzare in modo aggressivo (file da 1.000–2.000 righe), alzare i limiti del server indicati sotto, oppure pilotare il caricamento da un modulo di importazione dedicato o da uno script API lanciato da riga di comando — qualsiasi cosa eseguita fuori dal server web, così non c'è un timeout di richiesta da colpire.

Estrarre i dati prodotto: le opzioni di esportazione di PrestaShop

L'esportazione è il lato più debole della piattaforma, ed è meglio dirlo chiaramente. La pagina Importa nativa serve per importazioni e file di esempio — non è uno strumento completo per esportare prodotti. La cosa più vicina integrata nel pannello di amministrazione è il pulsante Esporta nella lista prodotti, ma produce solo i campi base mostrati nella lista — non combinazioni, non prezzi specifici, non scorte per magazzino. Per un lavoro reale hai due strade migliori.

SQL Manager: il cavallo da lavoro dell'esportazione

Parametri avanzati → Database → SQL Manager ti permette di scrivere una query di lettura e scaricare il risultato come CSV. È il modo più rapido per ottenere esattamente le colonne che vuoi. Per esportare ogni prodotto con la scorta attuale:

SELECT p.id_product, pl.name, p.reference, p.price, sa.quantity FROM ps_product p JOIN ps_product_lang pl ON p.id_product = pl.id_product AND pl.id_lang = 1 JOIN ps_stock_available sa ON p.id_product = sa.id_product AND sa.id_product_attribute = 0;

(Sostituisci ps_ con il prefisso reale delle tue tabelle.) Funziona benissimo insieme all'importatore per modifiche massive: esporti in CSV, cambi prezzi o scorte in un foglio di calcolo, reimporti con il riferimento come chiave attivo. Il limite è che SQL Manager è in sola lettura e manuale — è un eccellente strumento ad hoc, ma una pessima automazione, perché qualcuno deve cliccarlo.

Quando l'esportazione deve diventare un flusso ricorrente

Flussi prezzi giornalieri, flussi per marketplace e Google Shopping, un passaggio notturno a un sistema esterno — questi richiedono un file generato secondo una pianificazione, non una persona dentro SQL Manager. Qui entrano in gioco i moduli: un generatore che crea un flusso prodotti multilingua (e, per la reperibilità, mantiene la sitemap allineata al catalogo live) tramite cron, così il file resta aggiornato senza che nessuno tocchi il pannello di amministrazione. Se il vero lavoro è generare flussi, esplora i moduli di esportazione e flusso dati su mypresta.rocks — il vantaggio è un flusso sempre aggiornato e un amministratore che non deve ricordarsi di eseguirlo.

XML e Webservice API: per integrazioni, non migrazioni

XML è la lingua franca dei flussi B2B, degli ERP e dei marketplace, e il punto chiave è questo: l'importatore CSV di PrestaShop non legge affatto XML. Hai due opzioni oneste, adatte a obiettivi diversi.

Opzione 1 — convertire l'XML in CSV

Se un fornitore ti consegna un flusso XML e vuoi solo caricarlo una volta nel catalogo, trasformalo nella struttura CSV di PrestaShop con un foglio di stile XSLT, un breve script Python (xml.etree.ElementTree gestisce la maggior parte dei flussi fornitore piatti in ben meno di 50 righe), oppure uno strumento dati come Talend o Akeneo. Poi passalo all'importatore nativo. Semplice, nessuna API da abilitare, ideale per un caricamento una tantum.

Opzione 2 — parlare direttamente con la Webservice API

Per una sincronizzazione bidirezionale continua, la Webservice API è il livello giusto. È un'interfaccia in stile REST con CRUD completo su prodotti, combinazioni, categorie, scorte, clienti e ordini. Il Webservice classico (legacy) è orientato prima di tutto a XML — è questo il formato su cui costruire attraverso le versioni supportate; JSON in genere non è disponibile sul webservice legacy, quindi se ti serve specificamente JSON verifica se la tua versione di PrestaShop include invece la nuova Admin API basata su Symfony. Abilitalo in Parametri avanzati → Webservice, poi crea una chiave e concedile solo le risorse e i verbi necessari — non dare mai a una chiave accesso indiscriminato a tutte le risorse. Crea un prodotto con una POST verso https://yourstore.com/api/products con un corpo XML; aggiorna con PUT e l'ID prodotto nell'URL; la risposta restituisce l'entità con il suo nuovo ID.

Tre realtà da considerare prima di costruirci sopra:

• Una entità per richiesta. Non esiste un endpoint massivo — 10.000 prodotti significano 10.000 chiamate. Nel webservice legacy del core non c'è un rate limiting API integrato, ma l'hosting, un livello di sicurezza/WAF oppure la tua configurazione Apache (mod_evasive) o Nginx (limit_req) possono limitare un picco, quindi distanzia le chiamate di circa 100–200 ms e un'importazione da 10k diventa una finestra pianificata di circa 30 minuti, non una sorpresa.
• Le immagini si caricano, non si scaricano. Invia il file con POST a /api/images/products/{id} e PrestaShop lo memorizza direttamente — molto più affidabile dell'approccio CSV con download da URL, perché nulla dipende dal fatto che il server recuperi un URL remoto durante l'importazione.
• Prevedi una logica di retry. L'API risponde con codici HTTP (201 creato, 200 aggiornato, 404 non trovato, 500 errore server). Registra ogni risposta e ritenta i 500 — su migliaia di chiamate qualcuna fallirà in modo transitorio, e una sincronizzazione che non può riprendere è una sincronizzazione di cui non puoi fidarti.

Errori che vedrai davvero — e come correggerli

• "Property X is empty": un campo obbligatorio (nome, prezzo, categoria) è vuoto. Controlla che ogni colonna obbligatoria abbia un valore in ogni riga.
• "The category does not exist": hai indicato un ID categoria che non esiste. Importa prima le categorie, oppure usa i nomi delle categorie — l'importatore accetta entrambi e crea quelle mancanti.
• Prezzi errati dopo l'importazione: l'importatore legge i prezzi al netto delle imposte. Se il file contiene prezzi IVA inclusa, dividi prima per (1 + aliquota) oppure associa la regola fiscale corretta.
• Accenti trasformati in caratteri illeggibili: il file non è UTF-8. Convertilo: iconv -f Windows-1252 -t UTF-8 input.csv > output.csv.
• L'importazione ha "funzionato", ma i prodotti sono invisibili: controlla Active=1, una categoria reale assegnata, l'associazione corretta al negozio in multinegozio e che l'indice prodotti sia stato ricostruito.
• Duplicati dopo una reimportazione: hai dimenticato "Use product reference as key" (o l'ID come chiave). Aggiorna invece di clonare — vedi l'avviso sopra.

Scegliere il metodo giusto

Abbina lo strumento al lavoro, non all'abitudine:

Domande frequenti

La mia seconda importazione ha creato duplicati invece di aggiornare. Che cosa mi è sfuggito?

La casella "Use product reference as key" (o l'equivalente che usa l'ID come chiave). Per impostazione predefinita l'importatore crea righe, quindi un aggiornamento prezzi senza quella casella spuntata clona ogni prodotto invece di aggiornarlo. Assicurati che ogni riga contenga un Reference o un ID stabile e attiva l'opzione chiave a ogni esecuzione ricorrente.

Perché tutti i caratteri accentati sono diventati illeggibili dopo l'importazione?

Il file non è UTF-8. Il salvataggio semplice "CSV" di Excel usa Windows-1252, che rovina gli accenti — usa invece Salva con nome → CSV UTF-8 e rimuovi un BOM iniziale se presente. La sezione del post sulla codifica mostra esattamente l'aspetto dei caratteri rotti e il comando iconv in una riga che converte un file Windows-1252 in UTF-8 pulito.

L'importatore integrato può leggere un flusso XML?

No — l'importatore CSV non legge affatto XML. Per un caricamento una tantum, trasforma prima l'XML nella struttura CSV di PrestaShop (un foglio di stile XSLT o un breve script xml.etree.ElementTree gestisce la maggior parte dei flussi fornitore piatti). Per una sincronizzazione bidirezionale continua, usa direttamente la Webservice API invece di convertire file ogni volta.

La mia importazione continua ad andare in timeout su un catalogo grande. Come la porto a termine?

L'importatore web lavora senza troppi problemi fino a circa 5.000 prodotti. Oltre quella soglia, dividi in lotti da 1.000–2.000 righe, aumenta max_execution_time (a 600+) e memory_limit (a 512M), e disattiva "Index products on save" durante l'esecuzione — reindicizzare ogni riga rappresenta gran parte del tempo totale. Il core di PrestaShop non include un comando console prestashop:import, quindi per una migrazione da 10.000+ prodotti pilota il caricamento da un modulo di importazione o da uno script API eseguito fuori dalla richiesta web.

Come modifico prezzi o scorte in massa senza reimportare tutto il catalogo?

Fai un ciclo di esportazione e reimportazione con SQL Manager: esporta in CSV le colonne che ti servono, modificale in un foglio di calcolo, poi reimporta con il riferimento come chiave, così aggiorna invece di clonare. Per modifiche frequenti dei prezzi, i nostri moduli per aggiornamento massivo dei prezzi e flussi prodotto lo fanno dal pannello di amministrazione secondo una pianificazione, così non devi eseguire SQL Manager a mano e ricordarti ogni volta la casella della chiave.

Dove importazione/esportazione incontrano il resto delle operazioni

Importazione ed esportazione raramente vivono da sole — di solito sono una mossa dentro un flusso più ampio di catalogo o magazzino. Alcuni aspetti vicini da conoscere:

• Scorte via CSV. Un aggiornamento massivo delle quantità è semplicemente un'importazione di due colonne con riferimento come chiave. Ma la domanda più profonda — quale livello dovrebbero avere quei numeri, e quando riassortire — è una disciplina a sé: vedi quando riordinare le scorte.
• Superare il foglio di calcolo. Se continui a far viaggiare CSV avanti e indietro solo per tenere in ordine le scorte, di solito è il segnale che serve uno strumento di gestione inventario vero — quando i fogli di calcolo smettono di bastare spiega il passaggio.
• Esportazione di ordini e fatture. Entità diversa, percorso diverso — l'estrazione dei dati degli ordini per la contabilità è trattata in esportazioni CSV per ordini e fatture.

I dati prodotto sono quel tipo di lavoro che nessuno celebra e da cui tutti dipendono: importazioni pulite significano schede accurate, prezzi corretti e scorte allineate alla realtà. Il principio sotto tutti e tre i metodi è lo stesso — mantieni una chiave stabile su ogni prodotto, scegli lo strumento adatto alla scala del lavoro e non lasciare mai che un'importazione venga eseguita due volte senza sapere se crea o aggiorna. Se ciò che ti serve davvero è generare flussi ricorrenti o pianificare il passaggio dei dati prodotto, i moduli di esportazione e sitemap su mypresta.rocks sono costruiti esattamente per questo — un flusso che resta aggiornato senza che nessuno debba ricordarsi di premere un pulsante.