Come collegare WooCommerce a un gestionale

Collegare WooCommerce a un gestionale significa decidere tre cose: quali dati passano fra i due sistemi, in quale direzione viaggia ciascuno e quale dei due comanda quando i valori non coincidono. Il collegamento si costruisce sull'SKU, che deve essere identico da entrambe le parti, e si realizza in uno di tre modi: scambio di file, connettore già pronto, integrazione su misura via API. La parte difficile non è tecnica: è stabilire chi ha ragione sul numero di pezzi disponibili.

Se oggi qualcuno riscrive a mano gli ordini del sito nel gestionale e aggiorna le giacenze quando se ne ricorda, alla fine di questa guida avrai lo schema del collegamento e saprai quale dei tre metodi ha senso per la tua situazione.

Cosa serve prima di iniziare

• Un accesso amministratore a WooCommerce e la possibilità di generare chiavi API dal pannello di WordPress.
• La documentazione del gestionale: se espone un'API, in quale formato, con quale autenticazione e con quali limiti di chiamate. Se non espone nulla, quali file sa importare ed esportare.
• Il catalogo riconciliato: un elenco dove per ogni prodotto c'è il codice usato nel gestionale e quello usato sul sito. Varianti comprese, perché è lì che si accumulano le differenze.
• La decisione su quale sistema è la fonte di verità per ciascun dato. Non deve essere lo stesso per tutti: di norma il gestionale comanda su prezzi e scorte, il sito comanda sugli ordini che nascono online.
• Un ambiente di prova, cioè una copia del sito su cui sbagliare. Provare una sincronizzazione bidirezionale direttamente in produzione è il modo più rapido per azzerare le giacenze di un catalogo intero.

Che cosa sincronizzare e in quale direzione

Prima di scegliere lo strumento si disegna il flusso. Questa tabella è lo schema che copre la maggior parte degli e-commerce italiani.

L'unica riga davvero problematica è l'ultima. Un cliente può nascere in negozio e comprare online con un'altra email, e senza una regola di identità scritta prima si creano doppioni su entrambi i lati. Il criterio più solido è la partita IVA per le aziende e l'email per i privati.

I tre metodi possibili

Metodo 1: scambio di file. Il gestionale esporta un CSV di prodotti e giacenze, il sito lo importa con una procedura pianificata; gli ordini fanno il percorso inverso. È il metodo che richiede meno lavoro iniziale e regge bene fino a qualche centinaio di referenze con poche variazioni al giorno. Il limite è la latenza: fra un'esportazione e l'altra il sito vende su dati vecchi. Se parti da qui, la meccanica dell'import è spiegata nella guida su come importare i prodotti da un CSV.

Metodo 2: connettore già pronto. Un plugin che parla con il tuo gestionale specifico. Conviene quando il gestionale è diffuso e il tuo flusso è standard: si configura in qualche ora e la manutenzione è di chi lo sviluppa. Prima di comprarlo verifica tre cose: che gestisca le varianti come le usi tu, che sappia cosa fare quando una chiamata fallisce e che si possa forzare una risincronizzazione manuale di un singolo prodotto.

Metodo 3: integrazione su misura via API. WooCommerce espone una REST API completa e la maggior parte dei gestionali moderni fa lo stesso. Si costruisce un servizio intermedio che riceve gli eventi, li traduce e li consegna al sistema di destinazione, con una coda per i tentativi falliti. È la strada che ha senso quando il processo ha eccezioni proprie, quando i sistemi da tenere allineati sono più di due o quando il collegamento deve durare anni. È anche il tipo di lavoro che seguiamo nei progetti di gestionale e integrazioni su misura.

Come impostare il collegamento, passo per passo

1. Riconcilia gli SKU prima di ogni cosa. Esporta il catalogo dal gestionale e quello dal sito, mettili affiancati e trova le righe che non si accoppiano. Alla fine di questo passaggio ogni prodotto deve avere un solo codice valido su entrambi i lati. È la parte più noiosa e quella che determina se il progetto funzionerà.

2. Genera le chiavi API di WooCommerce. Nel pannello di WordPress apri WooCommerce, Impostazioni, Avanzate, API REST e crea una chiave nuova. Assegnala a un utente amministratore dedicato all'integrazione, non a una persona reale, e imposta i permessi in Lettura/Scrittura. A questo punto avrai una Consumer key e una Consumer secret: si vedono una volta sola, quindi salvale subito in un gestore di password.

3. Definisci per iscritto la fonte di verità di ogni campo. Una riga per dato, come nella tabella qui sopra. Serve a rispondere senza discussioni alla domanda che arriverà: il prezzo sul sito è diverso da quello del gestionale, chi vince.

4. Collega prima un solo flusso, in una sola direzione. Le giacenze dal gestionale al sito sono il candidato migliore: portano il beneficio più immediato e non toccano nulla di irreversibile. Verifica su dieci prodotti che il numero arrivi corretto, comprese le varianti e i prodotti con scorta zero.

5. Aggiungi gli ordini in uscita. L'ordine deve partire verso il gestionale quando il pagamento è confermato, non quando viene creato: altrimenti riempi il gestionale di ordini mai pagati. Il momento giusto corrisponde al passaggio in stato In lavorazione, come descritto nella guida su come gestire un ordine in WooCommerce.

6. Chiudi il cerchio con lo stato di spedizione. Quando il gestionale registra la partenza della merce, l'informazione torna al sito e fa scattare l'email al cliente con il tracking. È il passaggio che riduce di più le richieste di assistenza, perché la domanda più frequente dopo un acquisto è sempre la stessa.

7. Attiva log e allarmi. Ogni scambio deve lasciare traccia di che cosa è stato inviato, quando e con quale esito, e un errore ripetuto deve produrre una notifica a una persona. Alla fine di questo passaggio devi poter rispondere alla domanda "questo ordine è arrivato in magazzino?" guardando un registro, non chiedendolo in giro.

Metodo alternativo: sincronizzare solo gli ordini

Non tutti gli e-commerce hanno bisogno dell'integrazione completa. Se il catalogo cambia raramente e le giacenze sono ampie, il collegamento che ripaga subito è uno solo: gli ordini che arrivano dal sito entrano nel gestionale senza reinserimento manuale.

È un progetto molto più piccolo, si realizza in una direzione sola e toglie l'attività che genera più errori di battitura, cioè la ricopiatura di indirizzi e quantità. Le giacenze restano gestite come oggi, con gli strumenti descritti nella guida su come gestire le scorte, e la sincronizzazione completa si valuta quando il volume la giustifica.

Errori comuni

Partire dalla sincronizzazione bidirezionale. È la configurazione che sembra più completa ed è quella che produce i disastri peggiori, perché due sistemi che si scrivono a vicenda senza una regola di precedenza entrano in conflitto sul primo dato ambiguo. Si comincia sempre da un flusso unidirezionale.

Ignorare le varianti. Un prodotto con taglie e colori nel gestionale può essere una riga sola, mentre in WooCommerce è un prodotto padre con più varianti, ognuna con il suo SKU e la sua giacenza. Se la mappatura non prevede questo caso, le scorte delle varianti si allineano tutte allo stesso numero. Chi lavora con più depositi trova lo scenario esteso nella guida su stock multi magazzino.

Non prevedere che cosa fare in caso di errore. Una chiamata può fallire per un timeout, per una manutenzione o per un dato che il sistema di destinazione rifiuta. Senza una coda e un nuovo tentativo, quel messaggio è perso e nessuno lo sa.

Quanto tempo serve e il passo successivo

Il metodo a file si mette in piedi in una o due giornate, quasi tutte spese sulla riconciliazione dei codici. Un connettore già pronto richiede tipicamente da mezza giornata a due giornate di configurazione e prove. Un'integrazione su misura si misura in settimane, e la variabile principale non è WooCommerce ma quanto è accessibile il gestionale.

Ora che il flusso è definito, il passo successivo naturale è il documento fiscale: una volta che gli ordini arrivano nel gestionale conviene decidere come e quando si genera la fattura, argomento della guida sulla fatturazione elettronica in WooCommerce.

Le indicazioni di questa guida riguardano l'organizzazione tecnica dei flussi. Per gli aspetti fiscali della fatturazione e per il trattamento dei dati personali dei clienti che transitano fra i due sistemi, confrontati con il tuo commercialista e con chi si occupa della protezione dei dati in azienda: le indicazioni ufficiali sono pubblicate dall'Agenzia delle Entrate e dal Garante Privacy.