Integrare E-commerce e Gestionale: catalogo, stock, ordini

Un e-commerce che vive separato dal gestionale funziona finché gli ordini sono pochi. Poi arriva il momento in cui qualcuno passa le giornate a ricopiare ordini, le giacenze online non corrispondono a quelle in magazzino e si vende un prodotto che non c'è. L'integrazione tra e-commerce e gestionale non è un lusso da grandi aziende: è il passaggio che trasforma un negozio online da esperimento a canale di vendita vero. Vediamo come si progetta, quali sono le decisioni che contano e dove si sbaglia più spesso.

La domanda che viene prima di tutte: chi comanda su cosa

Prima di scrivere una riga di codice va stabilita la sorgente di verità per ogni tipo di dato. È la decisione che determina il 90% dell'architettura, e l'errore più costoso è lasciarla implicita.

La regola d'oro: ogni campo ha una sola sorgente di verità. Quando due sistemi possono modificare lo stesso dato si generano conflitti che nessuna logica di sincronizzazione risolve in modo pulito, e prima o poi qualcuno perde una modifica.

Le quattro architetture possibili

1. Export e import di file

Il gestionale produce un CSV o un XML, l'e-commerce lo legge a intervalli regolari. È il metodo più semplice e ancora oggi il più diffuso, adatto quando il gestionale è chiuso o quando i cataloghi cambiano poco. Limiti: nessun aggiornamento in tempo reale, gestione degli errori rudimentale, difficoltà a capire cosa è cambiato tra un file e l'altro.

2. Integrazione diretta via API

I due sistemi si parlano direttamente attraverso API REST. È la soluzione più pulita quando entrambi i lati espongono interfacce decenti. Vantaggi: dati aggiornati, errori visibili subito, possibilità di reagire agli eventi. Svantaggio: un accoppiamento diretto che va rifatto se un giorno cambi uno dei due sistemi.

3. Middleware di integrazione

Un componente intermedio che parla con entrambi, traduce i formati, registra ogni scambio e gestisce i tentativi falliti. È l'architettura che consiglio quando i sistemi collegati sono più di due — per esempio shop, gestionale, marketplace e corriere — o quando è prevedibile un cambio di piattaforma. Costa di più all'inizio e si ripaga alla prima sostituzione.

4. Sistema unico

Niente integrazione perché e-commerce e gestione ordini vivono nella stessa applicazione. È la strada di chi sviluppa un e-commerce su misura quando i processi di vendita sono particolari: la sincronizzazione semplicemente non esiste come problema. Ha senso quando il modello di business non entra nelle piattaforme standard.

Lo stock: il punto più delicato

La giacenza è il dato che crea più danni quando è sbagliato, perché l'errore diventa visibile al cliente finale. Le regole che funzionano:

• Sincronizzazione frequente e differenziale: non ricalcolare tutto il catalogo ogni volta, ma propagare solo ciò che è cambiato. Su cataloghi ampi è la differenza tra pochi secondi e mezz'ora
• Scorta di sicurezza: pubblicare online una quantità leggermente inferiore a quella reale assorbe il ritardo di sincronizzazione e previene la vendita di ciò che non c'è
• Prenotazione della merce al momento dell'ordine: la quantità va impegnata subito, non quando l'ordine arriva in magazzino
• Gestione esplicita degli articoli a zero: nascondere, mostrare come non disponibile o accettare preordini sono tre scelte commerciali diverse, e vanno decise, non subite
• Canali multipli: se vendi anche in negozio o su marketplace, la giacenza va gestita centralmente. Altrimenti l'overselling è solo questione di tempo

Gli ordini: dal carrello al documento fiscale

Il flusso di un ordine ben integrato attraversa passaggi espliciti e tracciati:

• Ordine confermato sullo shop, con pagamento autorizzato
• Trasmissione al gestionale con un identificativo univoco che permette di riconoscere il duplicato
• Creazione dell'ordine di vendita, aggancio o creazione del cliente in anagrafica
• Preparazione, documento di trasporto, spedizione con codice di tracciamento
• Ritorno dello stato e del tracking verso lo shop, che aggiorna il cliente
• Emissione del documento fiscale e trasmissione al sistema di fatturazione elettronica

Il requisito tecnico non negoziabile è l'idempotenza: se lo stesso ordine viene trasmesso due volte per un errore di rete o un tentativo automatico, il gestionale deve riconoscerlo e non creare un duplicato. Gli ordini doppi sono il bug più imbarazzante di questa categoria di integrazioni, perché finiscono in magazzino e in contabilità.

Cosa va previsto fin dall'inizio

• Registro di ogni scambio: chi ha inviato cosa, quando, con quale esito. Senza log, ogni discussione con il cliente diventa una questione di opinioni
• Tentativi automatici con attesa crescente: le API cadono, i server si riavviano. Un'integrazione seria riprova e non perde nulla
• Coda di lavorazione invece di chiamate sincrone dentro il checkout: il cliente non deve aspettare il gestionale per completare l'acquisto, e un gestionale lento non deve mai bloccare una vendita
• Notifica degli errori a una persona: un'integrazione che fallisce in silenzio è peggio di nessuna integrazione
• Mappatura dei codici: taglie, colori, unità di misura e aliquote IVA sono scritti diversamente nei due sistemi. La tabella di conversione va progettata, non improvvisata a colpi di condizioni nel codice
• Ambiente di prova su entrambi i lati: testare le integrazioni in produzione significa mandare ordini finti in contabilità

Gli errori che vedo più spesso

• Sincronizzare tutto, sempre: un job notturno che riscrive l'intero catalogo consuma risorse, allunga i tempi e rende impossibile capire cosa è cambiato
• Nessuna gestione delle varianti: prodotti con taglie e colori richiedono una mappatura esplicita, altrimenti le giacenze si sommano in modo errato
• Prezzi gestiti da entrambe le parti: si finisce con promozioni sovrascritte a metà campagna, tipicamente di venerdì sera
• Integrazione affidata a un plugin generico senza verificarne il comportamento sugli errori: funziona nella demo, non nel giorno di picco
• Nessuna documentazione: quando il sistema si rompe due anni dopo, ricostruire la logica costa più che riscriverla

Quanto costa e cosa restituisce

Un'integrazione tra un e-commerce standard e un gestionale con API documentate richiede in genere 5-12 giornate. Se il gestionale è chiuso e si passa da file di scambio, i tempi si accorciano ma cresce la manutenzione futura. Se i sistemi da collegare sono più di due, il middleware porta l'impegno iniziale a 15-25 giornate.

Il ritorno si misura su tre voci concrete: ore di digitazione manuale eliminate, errori di prezzo e di giacenza evitati, ordini gestibili senza aumentare il personale. Su un negozio con qualche centinaio di ordini al mese il recupero dell'investimento si colloca quasi sempre entro l'anno, come ho osservato anche nel caso studio del gestionale ordini in Yii2.

Domande frequenti

Il mio gestionale non ha API. È tutto perduto?

Quasi mai. Si lavora con file di scambio in una cartella condivisa o, se le condizioni di licenza lo permettono, direttamente sul database. Sono soluzioni meno eleganti ma solide, a patto di isolarle dietro un livello di astrazione che permetta di sostituirle in futuro.

Ogni quanto vanno sincronizzate le giacenze?

Dipende dalla rotazione. Per la maggior parte dei negozi un intervallo di 5-15 minuti con aggiornamento immediato dopo ogni ordine è un buon compromesso. Il tempo reale puro serve solo dove lo stesso articolo si vende contemporaneamente su più canali con quantità molto basse.

Meglio integrare o rifare tutto in un sistema unico?

Se il gestionale funziona e l'azienda lo conosce, si integra: sostituirlo è un progetto di tutt'altra scala. Il sistema unico si valuta quando il gestionale è comunque da rifare o quando i processi di vendita sono così particolari da richiedere sviluppo su misura in ogni caso.

MameTech: integrazioni che non si rompono in silenzio

Progetto e sviluppo integrazioni tra e-commerce, gestionali, marketplace e sistemi di fatturazione in PHP e Yii2, con code di lavorazione, registro completo degli scambi, tentativi automatici e notifiche in caso di errore. Lavoro con aziende e web agency in tutta Italia, da remoto, con un referente tecnico unico per tutto il progetto. Raccontaci il tuo scenario: la prima analisi di fattibilità, con architettura proposta e stima, è gratuita.