Sincronizzazione Google Sheets Bidirezionale — Guida completa

Il modulo DataFirefly Sheet Sync mantiene il tuo catalogo PrestaShop sincronizzato con un foglio Google in entrambi i sensi: modifichi prezzo, quantità in stock, titolo e stato attivo dei tuoi prodotti nel foglio, e il modulo li applica in PrestaShop; viceversa, ogni modifica fatta nel back office torna automaticamente nel foglio. Questa guida copre l’installazione, la creazione dell’account di servizio Google, la condivisione del foglio, la configurazione, il funzionamento della sincronizzazione, il cron e la risoluzione dei problemi.

Requisiti

• PrestaShop dalla 8.0 alla 9.x.
• PHP dalla 7.4 alla 8.3 con le estensioni cURL e OpenSSL attive.
• Un account Google con accesso alla console Google Cloud per creare un account di servizio (gratuito).
• Accesso al cron (attività pianificata sul server o servizio di cron esterno) per la sincronizzazione automatica.

Installazione

1. Nel back office, apri Moduli > Gestore moduli, poi Carica un modulo e rilascia il file dfsheetsync.zip.
2. Una volta installato, apri la pagina di configurazione con il pulsante Configura.

All’installazione, il modulo crea la sua tabella di stato della sincronizzazione, registra i valori predefiniti e genera automaticamente un token di cron.

Creare l’account di servizio Google

Un account di servizio è un’identità Google che il modulo usa per leggere e scrivere nel tuo foglio, senza flusso OAuth né schermata di consenso.

1. Nella console Google Cloud, crea (o seleziona) un progetto.
2. Attiva l’API Google Sheets per questo progetto (menu API e servizi > Libreria, cerca «Google Sheets API», poi Abilita).
3. Apri API e servizi > Credenziali, clicca su Crea credenziali > Account di servizio, assegnagli un nome e conferma.
4. Apri l’account di servizio creato, scheda Chiavi, poi Aggiungi chiave > Crea nuova chiave > JSON. Viene scaricato un file .json: è la chiave che incollerai nel modulo.

Condividere il foglio con l’account di servizio

Il file JSON contiene un campo client_email nella forma nome@progetto.iam.gserviceaccount.com. È l’indirizzo da autorizzare.

1. Apri (o crea) il tuo foglio Google.
2. Clicca su Condividi e aggiungi l’indirizzo client_email dell’account di servizio con il ruolo Editor.

Configurazione

La pagina di configurazione raccoglie le seguenti impostazioni:

• JSON dell’account di servizio: incolla qui il contenuto completo del file .json. Lascia il campo vuoto per conservare la chiave già salvata.
• ID o URL del foglio di calcolo: incolla l’ID del foglio o il suo URL completo — l’ID viene estratto automaticamente.
• Nome della scheda: la scheda da usare all’interno del foglio (predefinito Products). Viene riempita con una riga di intestazione al primo avvio.
• Lingua dei titoli: la lingua in cui i titoli dei prodotti vengono letti e scritti.
• Priorità in caso di conflitto: decide quale lato vince quando un prodotto è stato modificato su entrambi i lati (il foglio Google, o PrestaShop).
• Esporta solo i prodotti attivi: limita la sincronizzazione ai prodotti attivi.

Salva, poi controlla il pannello di stato: mostra l’e-mail dell’account di servizio connesso, l’URL del cron, la data dell’ultima sincronizzazione e un link diretto al foglio.

Struttura del foglio

Il foglio ha sei colonne, la cui intestazione viene creata automaticamente al primo avvio:

1. ID — l’identificatore del prodotto PrestaShop. Non modificare.
2. Riferimento — riferimento prodotto (in sola lettura per la sincronizzazione).
3. Nome — il titolo del prodotto nella lingua configurata.
4. Prezzo IVA esclusa — il prezzo base al netto delle imposte.
5. Quantità — la quantità di stock globale.
6. Attivo — 1 per attivo, 0 per inattivo.

Come funziona la sincronizzazione

Il modulo memorizza l’impronta (checksum) dell’ultimo stato sincronizzato di ogni prodotto. A ogni passaggio, confronta lo stato attuale del negozio e quello del foglio con questa impronta per determinare cosa è cambiato, e su quale lato:

• Foglio modificato, negozio invariato → i valori del foglio vengono applicati al prodotto.
• Negozio modificato, foglio invariato → i valori del negozio vengono scritti nel foglio.
• Entrambi modificati → la regola di priorità configurata decide (vince il foglio, o vince il negozio), e la decisione viene registrata.
• Prodotto assente dal foglio → viene aggiunto automaticamente, con il negozio come riferimento.

Vengono scritte solo le righe realmente modificate, nel verso giusto; le scritture verso Google sono raggruppate in lotti per rispettare le quote dell’API e restare rapide anche su un catalogo esteso.

Sincronizzazione manuale e ripristino

Nella configurazione sono disponibili due pulsanti:

• Sincronizza ora: avvia immediatamente una sincronizzazione completa e mostra un rapporto (righe inviate al foglio, prodotti aggiornati, righe aggiunte, conflitti risolti, righe ignorate).
• Ripristina stato: svuota la tabella di stato della sincronizzazione. Al passaggio successivo, il negozio è considerato la fonte di verità per ogni prodotto. Utile dopo una riorganizzazione manuale del foglio.

Configurazione del cron

Per una sincronizzazione automatica, pianifica l’URL del cron mostrato nella configurazione, ogni 5-15 minuti:

curl "https://il-tuo-negozio.com/module/dfsheetsync/cron?token=IL_TUO_TOKEN"

Il token viene generato all’installazione e protegge l’endpoint. La chiamata restituisce un rapporto JSON della sincronizzazione.

Validazione dei dati

Prima di scrivere nel negozio, il modulo convalida ogni riga del foglio. Una riga viene ignorata e registrata (senza interrompere il resto della sincronizzazione) nei seguenti casi:

• nome prodotto vuoto o contenente caratteri non consentiti;
• prezzo negativo;
• ID che non corrisponde ad alcun prodotto del negozio.

Il rapporto di sincronizzazione indica il numero di righe ignorate, e il dettaglio è consultabile nei log di PrestaShop.

Campi sincronizzati e limitazioni

La versione 1.0.0 sincronizza, per ogni prodotto: il titolo (nella lingua configurata), il prezzo base IVA esclusa, la quantità di stock globale e lo stato attivo/inattivo.

Risoluzione dei problemi

• Errore «autorizzazione negata»: verifica che il foglio sia condiviso come Editor con l’indirizzo client_email dell’account di servizio.
• Errore «JSON non valido»: il contenuto incollato deve essere il file di chiave completo, contenente almeno client_email e private_key.
• Nessuna sincronizzazione: verifica che l’ID del foglio sia indicato e che il cron venga eseguito, oppure avvia una sincronizzazione manuale.
• Errore di autenticazione Google: assicurati che l’API Google Sheets sia abilitata per il progetto e che l’orologio del server sia allineato (il JWT ha una marca temporale).
• Una riga non viene applicata: nome vuoto/non valido o prezzo negativo; correggi la riga nel foglio.
• Un prodotto torna al valore precedente: controlla la regola di priorità in caso di conflitto; il lato prioritario sovrascrive l’altro quando entrambi sono cambiati.

Disinstallazione

La disinstallazione elimina la tabella di stato della sincronizzazione e la configurazione del modulo (inclusa la chiave dell’account di servizio e il token del cron). I tuoi prodotti e il tuo foglio Google non vengono modificati. Per un semplice aggiornamento, basta sostituire i file del modulo: lo stato della sincronizzazione viene conservato.