L'e-commerce funziona quando la macchina dietro funziona. Eppure quasi tutti i progetti che ereditiamo hanno la stessa malattia: WooCommerce da una parte, gestionale dall'altra, e in mezzo un foglio Excel che gira via mail. Vediamo i pattern di integrazione che applichiamo davvero, non quelli da slide commerciale.
I quattro flussi che vanno integrati
- Anagrafica prodotti: dal gestionale (Mexal, TeamSystem, Zucchetti, Danea, Mago) verso WooCommerce.
- Giacenze: dal gestionale verso WooCommerce in tempo reale o quasi.
- Ordini: da WooCommerce verso il gestionale, con tutti i dati cliente e fatturazione.
- Stati ordine e tracking: dal gestionale e dai corrieri verso WooCommerce e verso il cliente.
Pattern 1: middleware Node.js dedicato
Per la maggior parte dei nostri progetti la scelta è un servizio Node.js (TypeScript + Prisma) che fa da hub: legge dal gestionale (via export CSV pianificato, query SQL diretta o API), trasforma e scrive su WooCommerce via REST API. È più lavoro iniziale ma è l'unica via per gestire anagrafiche complesse, taglie/colori e listini multipli.
Lo stack tipico:
- Job scheduler (cron, BullMQ) per la sincronizzazione periodica.
- Webhook da WooCommerce per gli ordini in tempo reale.
- Tabella di mapping tra SKU gestionale e ID WooCommerce.
- Log strutturato (JSON) e dashboard di monitoraggio.
- Retry con backoff esponenziale e DLQ per gli errori non recuperabili.
Pattern 2: plugin commerciali "tutto incluso"
Esistono plugin che dichiarano di sincronizzare con il gestionale X o Y. Funzionano, finché funzionano. Le criticità ricorrenti che vediamo:
- Mappature non personalizzabili oltre un certo limite.
- Aggiornamenti del plugin che rompono la sincronizzazione senza preavviso.
- Dipendenza dal plugin: se il fornitore sparisce o smette di mantenere, sei bloccato.
Li proponiamo solo quando il cliente è davvero standard: un solo magazzino, un listino, un canale, e budget davvero contenuto.
Pattern 3: gestionale già "headless"
Alcuni gestionali moderni espongono API REST decenti. In quel caso il middleware si semplifica e a volte si può sostituire con un workflow su n8n o Make. Funziona bene fino a 50-100 ordini/giorno, sopra serve qualcosa di più robusto.
Le trappole italiane
- Fatturazione elettronica: il gestionale di solito è autorevole, WooCommerce no. Le fatture devono partire dal gestionale, mai dal sito.
- IVA su prodotti misti: alimentari, libri, e altri beni con aliquote diverse. La sincronizzazione deve trasportare l'aliquota corretta, non solo il prezzo.
- Codici a barre e SKU duplicati: esistono nel gestionale per ragioni storiche. Vanno disambiguati prima di sincronizzare, non dopo.
- Promozioni: il gestionale ha listini con scaglioni e regole; WooCommerce ragiona a coupon e categorie. La traduzione è un progetto a sé.
Il consiglio finale
Prima di integrare, semplifica. Tre quarti dei progetti che riceviamo hanno un catalogo che potrebbe essere ridotto del 30% e un listino che potrebbe essere dimezzato. La migliore integrazione è quella che non devi fare.