Un'integrazione tra e-commerce e gestionale sincronizza quattro flussi: catalogo e anagrafiche, giacenze, ordini e documenti. Per ogni dato serve un solo sistema che comanda, con gli altri in sola lettura. I webhook danno reattività, una riconciliazione programmata dà certezza, e idempotenza più coda con retry evitano ordini duplicati o persi.
Un cliente ci ha mostrato il suo processo ordini: l'e-commerce manda una mail, una persona apre il gestionale e ribatte i dati a mano. Trenta ordini al giorno, due minuti l'uno, più gli errori. Funzionava, nel senso che l'azienda era ancora in piedi. Ma quel lavoro non aggiungeva niente a niente.
Collegare un negozio online a un gestionale è uno dei progetti con il ritorno più chiaro che ci capita di fare, e anche uno di quelli che si sbagliano più spesso. Il motivo è che sembra un problema tecnico, mentre la parte difficile viene prima.
Prima domanda: chi è la fonte di verità
Per ogni dato che vive in due sistemi va deciso quale dei due comanda. Il prezzo lo stabilisce il gestionale o il negozio? La giacenza? La scheda cliente? Se questa mappa non esiste, l'integrazione decide per conto suo, con la logica di chi ha scritto l'ultimo script, e si finisce con due sistemi che si sovrascrivono a turno.
La regola che funziona quasi sempre: un dato, un padrone, tutti gli altri in sola lettura. Le eccezioni si contano e si scrivono, non si scoprono in produzione.
I quattro flussi che contano
Quasi tutte le integrazioni si riducono a quattro flussi, e conviene trattarli separatamente perché hanno frequenze diverse e tolleranze diverse all'errore.
Catalogo e anagrafiche. Di solito viaggiano dal gestionale al negozio, con frequenza bassa. La trappola qui non è tecnica ma editoriale: una descrizione prodotto scritta per una fattura è illeggibile su una scheda articolo, quindi il negozio ha spesso campi suoi che la sincronizzazione non deve toccare mai.
Giacenze. Il flusso più delicato, perché un errore qui significa vendere qualcosa che non hai. Va tenuto vicino al tempo reale, e serve una politica per i casi scomodi: merce impegnata ma non ancora spedita, scorte di sicurezza sui prodotti che girano, articoli venduti in negozio nello stesso momento.
Ordini. Dal negozio al gestionale, ed è qui che si nasconde il lavoro di mappatura: metodi di pagamento, aliquote IVA, spese di spedizione come riga d'ordine, codici sconto, spedizioni parziali. Un ordine che il gestionale rifiuta deve finire in un posto visibile, non in un log che nessuno apre.
Documenti e spedizioni. Il viaggio di ritorno: fattura, DDT, numero di tracking, cambi di stato che innescano le mail al cliente. Qui dentro stanno anche resi e note di credito, che sono la parte che si rinvia e poi si gestisce a mano per due anni.
Sincronizzare senza rompere niente
Tre meccanismi, in ordine di preferenza: webhook, dove il negozio ti avvisa che è successo qualcosa e tu reagisci; polling, dove chiedi ogni N minuti cosa è cambiato; file batch, l'ultima spiaggia. Chi va in produzione con i soli webhook prima o poi perde un evento, perché una notifica si perde sempre. Si tiene il webhook per la reattività e si aggiunge una riconciliazione notturna per la certezza.
Due cose non sono negoziabili. L'idempotenza: la stessa notifica processata due volte non deve creare due ordini, quindi ogni entità porta con sé l'identificativo dell'altro sistema. E una coda con retry ed errori visibili: quando il gestionale è spento per il backup notturno, gli ordini si accumulano e poi passano, non svaniscono.
Quando il gestionale non ha API decenti
Metà dei gestionali che incontriamo non ha API pensate per questo. Le vie d'uscita, in ordine di eleganza decrescente: una API che esiste ma non è documentata, cosa più comune di quanto i fornitori ammettano perché la usa il loro stesso modulo mobile; una vista sul database in sola lettura più una tabella di appoggio per le scritture; uno scambio di file su cartella condivisa o FTP con un formato concordato. Funzionano tutte e tre. La differenza la fa mettere il contratto nero su bianco prima, perché un'integrazione appoggiata a un dettaglio interno si rompe in silenzio il giorno in cui il fornitore rilascia un aggiornamento.
Il caso peggiore è il gestionale a cui nessuno mette più mano, dove ogni modifica passa da un consulente che risponde a settimane. Lì il progetto di integrazione diventa l'occasione per una domanda diversa, che abbiamo affrontato altrove: quanto ti sta costando davvero tenerlo.
Middleware sì o no
Con due sistemi e quattro flussi, un connettore diretto è più facile da capire e da mantenere. Il middleware inizia a pagarsi quando i punti da collegare diventano tre o più, per esempio negozio, gestionale, magazzino di terzi e un marketplace, perché ti dà un posto solo dove leggere i log e uno solo dove cambiare le trasformazioni dei dati. Comprare una piattaforma di integrazione per due sistemi è un costo fisso pagato per un problema che non hai ancora.
Le domande che facciamo prima di partire
Quattro risposte, e sono quasi sempre le stesse quattro. Quali dati devono muoversi e in quale direzione. Quanto vecchio può essere un valore prima che diventi un problema, perché una giacenza a cinque minuti va bene e a un'ora no, e quella singola risposta cambia l'architettura. Cosa deve succedere quando un sistema è giù. Chi guarda gli errori la mattina dopo. Con queste in mano, il codice è la parte meno rischiosa del progetto.
Questo lavoro lo facciamo da entrambi i lati del filo, dal negozio online ai sistemi che stanno dietro. Se oggi ribatti gli ordini a mano, è il problema meno costoso da togliere di mezzo di questa lista.
