Documentazione

1. Requisiti di sistema

Prima di installare, verifica che l'hosting soddisfi questi requisiti minimi:

2. Installazione

Metodo 1: Back Office PrestaShop (consigliato)

1. Scarica il file excelsyncstock.zip dall'email di conferma acquisto.
2. Accedi al tuo Back Office PrestaShop.
3. Vai in Moduli → Gestione Moduli.
4. Clicca su Carica un modulo in alto.
5. Seleziona il file ZIP scaricato.
6. PrestaShop esegue l'installazione automatica. A fine processo vedrai il modulo nella lista.
7. Vai al menu Catalogo → Excel Stock Sync per accedere alla dashboard.

Metodo 2: Upload via FTP

1. Estrai il contenuto dello ZIP sul tuo computer.
2. Con un client FTP (FileZilla, Cyberduck) collegati al tuo server.
3. Naviga a /modules/.
4. Carica l'intera cartella excelsyncstock/.
5. In Back Office vai in Moduli → Gestione Moduli, cerca "Excel Stock Sync" e clicca Installa.

Post-installazione

A installazione completata, il modulo crea automaticamente:

• Due tabelle nel database: ps_excelsyncstock_log e ps_excelsyncstock_log_detail
• Un link nel menu di back office: Catalogo → Excel Stock Sync
• Le cartelle uploads/ e logs/ con permessi di scrittura
• File .htaccess di protezione sulle cartelle sensibili

3. Primo import in 4 step

Il flusso consigliato per il primo utilizzo è sempre: upload → mappatura → simulazione → import reale. Ecco come procedere.

Step 1: Carica il file

1. Apri Catalogo → Excel Stock Sync.
2. Clicca su Upload File nel menu laterale.
3. Seleziona il tuo file CSV o XLSX (max 50 MB per hosting standard).
4. Clicca Carica.

Il file viene salvato in uploads/ ed impostato come file corrente.

Step 2: Configura la mappatura

1. Vai alla sezione Mappatura.
2. Se il delimitatore CSV non è stato rilevato correttamente, selezionalo manualmente (; , tab o |).
3. Per ogni colonna del tuo file, associa il campo PrestaShop corrispondente.
4. Campi obbligatori: Quantità + almeno un identificativo tra ID, Reference, EAN.
5. Clicca Salva Mappatura.

Step 3: Simula l'import

1. Vai alla sezione Simulazione.
2. Clicca Esegui Simulazione.
3. Attendi il completamento (tipicamente 10-30 secondi su file medi).
4. Analizza il report: prodotti trovati, non trovati, errori.
5. Se tutto è corretto, procedi.

Step 4: Esegui l'import reale

1. Dalla pagina simulazione, clicca Esegui Import Reale.
2. Oppure dalla Dashboard, clicca Importa Locale.
3. Conferma l'operazione.
4. Attendi il completamento.
5. Verifica il riepilogo finale e il log dettagliato.

4. Mappatura colonne in dettaglio

La mappatura è il cuore del modulo: stabilisce come le colonne del tuo file si traducono nei campi di PrestaShop. Una volta salvata, viene ricordata e riapplicata automaticamente ai file successivi con la stessa struttura.

Campi PrestaShop disponibili

Ordine di priorità nel matching

Se il file contiene più identificativi, il modulo li usa in questo ordine:

1. id_product_attribute (match diretto, più veloce)
2. Coppia id_product + id_product_attribute
3. reference di combinazione (ricerca in ps_product_attribute)
4. reference di prodotto (prima cerca nelle combinazioni, poi nei prodotti base)
5. ean13 (prima cerca nelle combinazioni, poi nei prodotti base)

5. Configurazione FTP

Per far scaricare automaticamente il file da un server remoto:

1. Vai in Moduli → Gestione Moduli → Excel Stock Sync → Configura.
2. Compila la sezione Configurazione FTP:
   • Host: indirizzo server (es. ftp.tuoserver.com)
   • Porta: tipicamente 21 per FTP standard
   • Username: utente FTP
   • Password: password FTP (viene cifrata prima del salvataggio)
   • Percorso remoto: cartella dove si trova il file (es. /stock/)
   • Nome file: nome esatto del file da scaricare (es. stock.csv)
3. Clicca Testa connessione FTP per verificare.
4. Se il test è positivo, clicca Salva.

Modalità passiva

Se sei dietro firewall o NAT, attiva la modalità passiva nella configurazione. È quella raccomandata per la maggior parte degli hosting condivisi.

Password sicure

La password FTP non viene mai salvata in chiaro nel database. Il modulo usa cifratura simmetrica con chiave derivata dal _COOKIE_KEY_ del tuo PrestaShop.

6. Schedulazione CRON

Per automatizzare la sincronizzazione a intervalli regolari:

1. Abilita il CRON nel modulo

1. Vai nella sezione Configurazione del modulo.
2. Attiva Abilita CRON automatico.
3. Scegli la frequenza: 15min, 30min, 1h, 2h, 6h, 12h, 24h.
4. Scegli la sorgente: FTP remoto o File locale.
5. Salva.

2. Configura il crontab del server

Il modulo ti mostra un comando curl pronto da incollare. Esempi:

# Ogni ora alle :00
0 * * * * curl -s "https://tuonegozio.com/module/excelsyncstock/cron?secure_key=TUACHIAVE"

# Ogni 6 ore
0 */6 * * * curl -s "https://tuonegozio.com/module/excelsyncstock/cron?secure_key=TUACHIAVE"

# Ogni giorno alle 6:00
0 6 * * * curl -s "https://tuonegozio.com/module/excelsyncstock/cron?secure_key=TUACHIAVE"

Se il tuo hosting usa cPanel o Plesk, puoi aggiungere questo comando dall'interfaccia grafica dei cron job.

7. Uso della simulazione

La simulazione esegue tutto il ciclo di import (download FTP, parsing, matching, calcolo nuove quantità) senza scrivere nel database. È obbligatoria prima di ogni import reale quando cambi il file sorgente o la mappatura.

Il report di simulazione include:

• Numero totale di righe processate
• Prodotti trovati (con quantità vecchia e nuova)
• Prodotti non trovati (con identificativo cercato)
• Eventuali errori di parsing (righe malformate)
• Warning (es. quantità negative su incremento)

Le simulazioni vengono salvate in ps_excelsyncstock_log con is_simulation = 1, per distinguerle dagli import reali.

8. Interpretazione dei log

Tabella ps_excelsyncstock_log

Un record per ogni import (o simulazione). Campi principali:

Tabella ps_excelsyncstock_log_detail

Un record per ogni riga del file. Permette di ricostruire esattamente cosa è stato fatto su ogni SKU.

Stati possibili

• success — il prodotto è stato trovato e aggiornato
• unchanged — il prodotto è stato trovato ma la quantità era già corretta
• not_found — l'identificativo non corrisponde a nessun prodotto in catalogo
• error — errore durante l'aggiornamento (dettaglio nel campo message)
• crash — presente solo in record sintetici creati dallo shutdown handler in caso di crash PHP

9. Risoluzione problemi

Il file CSV mostra una sola colonna

Causa: delimitatore errato o file con righe racchiuse tra virgolette non riconosciute.

Soluzione: seleziona il delimitatore corretto nella mappatura. Il modulo gestisce automaticamente righe quotate con ".

Molti prodotti risultano "not_found"

Verifica:

• Il reference/ean nel file corrisponde esattamente a quello in PrestaShop (attenzione a maiuscole/minuscole, trim spazi)
• Per le combinazioni, il file deve contenere il reference della combinazione, non del prodotto padre
• Il prodotto esiste effettivamente in PrestaShop (non disabilitato né cancellato)

Errore connessione FTP

Verifica:

• Host e porta corretti
• Credenziali valide (prova via FileZilla per conferma)
• Percorso esistente e leggibile dall'utente FTP
• Firewall del server hosting non blocca connessioni FTP in uscita
• Modalità passiva abilitata se necessario

File XLSX non supportato

Soluzione: installa la libreria PhpSpreadsheet nel tuo PrestaShop:

cd /path/to/prestashop
composer require phpoffice/phpspreadsheet

Se non hai accesso alla shell, contattaci: forniamo una versione del modulo con PhpSpreadsheet già embedded.

Il CRON non parte

Verifica:

• Il crontab del server è stato effettivamente salvato (controlla con crontab -l)
• L'URL è accessibile dall'esterno (prova a visitarlo col browser, dovresti vedere una risposta JSON)
• Il secure_key nell'URL corrisponde a quello salvato nel modulo
• Il file di log logs/sync.log contiene qualche traccia

10. Aggiornamenti del modulo

Il modulo include un sistema di auto-update che controlla periodicamente la disponibilità di nuove versioni sul nostro server.

Notifica di nuova versione

Quando è disponibile un update, vedi un banner sulla dashboard del modulo con il numero di versione e le note di rilascio.

Procedura di aggiornamento

1. Clicca Aggiorna ora sul banner.
2. Il modulo crea automaticamente un backup della versione corrente in backups/.
3. Scarica la nuova versione dal nostro server.
4. Sostituisce i file del modulo mantenendo le configurazioni esistenti.
5. Esegue eventuali script di migrazione database (cartella upgrade/).
6. Al termine, vedi il messaggio di successo con la nuova versione.

11. Struttura database e API interne

Per sviluppatori che devono integrare il modulo con sistemi esterni o estenderne le funzionalità.

Hook PrestaShop registrati

• actionCronJob — per compatibilità con moduli cron manager PrestaShop

Classi principali

• classes/ExcelSyncStockImporter.php — parsing e matching
• classes/ExcelSyncStockLogger.php — gestione log su DB
• classes/ExcelSyncStockUpdater.php — sistema auto-update

Controller CRON

Endpoint pubblico: /module/excelsyncstock/cron?secure_key=XXXXX

Risponde JSON con l'esito dell'import. Esempio:

{
  "success": true,
  "total_rows": 4217,
  "updated": 4205,
  "not_found": 12,
  "errors": 0,
  "duration_ms": 14234,
  "source": "ftp"
}

Tabella ps_stock_available

Il modulo aggiorna esclusivamente questa tabella tramite StockAvailable::setQuantity(). Non scrive su ps_stock_mvt (registro movimenti): se hai bisogno di questo comportamento, contattaci per una versione personalizzata.

Non hai trovato la risposta che cercavi? Scrivici a supporto@i-creativi.com.
Rispondiamo entro 48 ore lavorative.