1. Perché il gestionale contabile non deve restare isolato
Nella maggior parte delle aziende il gestionale contabile è la fonte di verità per fatture, incassi e saldi. Il magazzino, la logistica e l'e-commerce, però, generano ogni giorno dati che devono finire nello stesso posto. Quando questo passaggio è manuale, il risultato è noto: stock diversi tra sito e magazzino, ordini ricopiati a mano, fatture emesse su dati non aggiornati.
Un collegamento automatico risolve una parte del problema, ma ne crea un'altra: due sistemi che scrivono sugli stessi dati possono entrare in conflitto. Per questo prima della tecnologia serve una decisione organizzativa su cosa succede a ogni dato, chi lo modifica, con quale frequenza e chi verifica che i totali tornino. Il progetto riguarda soprattutto processi e responsabilità. Chiedi a ciascun reparto quali errori ricorrenti vede ogni mese: sono il miglior punto di partenza per la mappa.
2. Flussi bidirezionali: cosa scambiare e in quale direzione
Un flusso bidirezionale è quello in cui due sistemi scrivono e leggono gli stessi dati. È la parte più delicata dell'integrazione, perché richiede una regola chiara per ogni campo. Non tutto deve essere bidirezionale: un dato di sola lettura, come il piano dei prezzi, è più sicuro da sincronizzare in un solo senso, dal gestionale verso l'e-commerce, così non ci sono due versioni del prezzo.
La tabella seguente aiuta a mappare i flussi più comuni in un progetto di questo tipo. Per ogni flusso indica chi è la sorgente, chi è la destinazione e qual è il rischio principale. Compila la tabella con i responsabili reali prima di scrivere una riga di codice, e aggiornala ogni volta che si aggiunge un canale di vendita. Un confronto tra responsabili, fatto con la tabella davanti, emerge più velocemente di una riunione tecnica.
| Flusso | Sorgente del dato | Destinazione | Rischio principale |
|---|---|---|---|
| Anagrafiche clienti e fornitori | Gestionale contabile | E-commerce e logistica | Duplicati e codici diversi per lo stesso soggetto |
| Ordini ricevuti | E-commerce | Gestionale contabile | Ordini doppi o persi in caso di errore di rete |
| Disponibilità di magazzino | Logistica | E-commerce e gestionale | Scorte mostrate diverse da quelle reali |
| Stato di fatturazione e incassi | Gestionale contabile | Portale clienti | Informazioni vecchie se il flusso è periodico |
3. Interfacce REST: cosa verificare nel gestionale
Un'API REST è un modo standard di esporre funzioni tramite richieste HTTP, di solito con dati in formato JSON. Molti prodotti moderni la offrono, ma non tutte le versioni di un gestionale la includono. Il primo lavoro è verificare con il produttore quali interfacce sono disponibili per il tuo prodotto e per la tua versione, con quali moduli aggiuntivi e a quali condizioni. Se mancano, esistono strade alternative, come lo scambio di file o i connettori del produttore.
Quando l'interfaccia c'è, chiedi informazioni precise: metodo di autenticazione, limiti di chiamate nel tempo, paginazione dei risultati, gestione delle versioni e disponibilità di un ambiente di test. Verifica anche se le operazioni di scrittura sono idempotenti, cioè se un invio ripetuto non crea un duplicato. Nei prodotti di linea l'interfaccia può essere limitata o richiedere un modulo a parte: è un costo da includere nella valutazione, non un dettaglio.
4. Conflitti, sincronizzazione e ordine degli eventi
Il conflitto più frequente nasce quando lo stesso articolo viene rettificato in due posti contemporaneamente: un inventario in magazzino e una vendita sul sito. Un altro problema è l'ordine degli eventi: una fattura creata prima della conferma dell'ordine, oppure un ordine arrivato dopo la chiusura contabile del periodo. Ogni regola va scritta: quale sistema prevale, come si gestiscono gli ordini a cavallo di un periodo e chi autorizza le eccezioni.
Usa un identificativo univoco per ogni ordine che attraversa i sistemi e riportalo in entrambi. Un confronto periodico dei totali tra e-commerce, logistica e contabilità permette di scoprire le differenze presto, quando sono ancora piccole. Non cancellare mai un documento contabile tramite integrazione: usa stati, annullamenti e storni, come nella contabilità tradizionale, così la traccia resta leggibile per il commercialista e per i controlli.
5. Checklist di progetto
Prima di approvare il progetto, il responsabile amministrativo e il responsabile e-commerce devono firmare la stessa mappa dei dati. Se ognuno ha in mente una versione diversa del flusso, il progetto fallirà al primo ordine reso, qualunque sia la qualità del codice. Ogni dato senza un responsabile nominato è un conflitto in attesa di accadere, e va risolto prima dello sviluppo.
La checklist seguente riassume le condizioni minime. Ogni voce non spuntata è un rischio da accettare per iscritto o da risolvere prima dell'avvio dello sviluppo. Usa la checklist come verbale: ogni voce ha un responsabile e una data di verifica, e il verbale resta nel fascicolo del progetto come riferimento per le future modifiche. Riguardala ogni volta che il progetto cambia perimetro.
- Mappa dei dati con un solo proprietario per ciascun campo.
- Versione del gestionale e moduli necessari per le interfacce.
- Autenticazione con utenza tecnica a privilegi minimi.
- Regole di conflitto documentate per i dati scritti da più sistemi.
- Gestione della coda degli errori e riprova sicura, senza duplicati.
- Confronto periodico dei totali tra i sistemi, con report consultabile.
- Ambiente di test e procedura formale per portare le modifiche in produzione.
- Regole per la chiusura contabile e per gli ordini a cavallo di periodo.
6. Errori frequenti in questi progetti
Il primo errore è trattare il gestionale come un database qualsiasi. Il software applica regole di contabilità, numerazione e stati che un'integrazione non deve aggirare. Creare un documento scrivendo direttamente nelle tabelle, anche se sembra più veloce, produce documenti non conformi o non riconciliabili con il registro IVA e con la contabilità. Ogni integrazione andrebbe testata con una serie di casi ripetibili, da rieseguire a ogni modifica.
Il secondo è non gestire resi, note di credito e annullamenti, che sono i casi più frequenti nell'e-commerce e spesso i meno testati. Il terzo è avere lo stock calcolato in due posti senza una regola: la vendita sul sito riduce la disponibilità, ma l'inventario in magazzino la aggiorna in ritardo, e si crea un doppio movimento. Il quarto è non prevedere chi risolve le eccezioni: un ordine bloccato per un codice articolo errato deve finire in una lista visibile a una persona, non in un file di log.
7. Come iniziare: un flusso con regole chiare
Parti da un solo flusso bidirezionale, ad esempio l'ordine dall'e-commerce al gestionale con il ritorno dello stato di evasione. Prima di scrivere codice, definisci i dati, il proprietario di ciascun campo e i casi di errore. Questo lavoro di analisi è spesso il tempo più utile di tutto il progetto, perché evita di costruire un flusso tecnicamente corretto ma inadatto ai processi reali.
Il primo passo concreto è chiedere al fornitore del gestionale e ai responsabili di e-commerce e logistica una scheda per ogni flusso, con sorgente, destinazione, frequenza, regola di conflitto e gestione dell'errore. Se la scheda non si riempie in modo condiviso, il progetto non è ancora pronto. Quando la scheda è completa, il flusso pilota può partire con test reali e un responsabile per le eccezioni.
Domande frequenti
Serve un'API REST per collegare il gestionale all'e-commerce?
No. Esistono altre strade, come lo scambio di file, le interfacce del produttore o un connettore standard. L'API REST è comoda perché è diffusa e facile da testare, ma conta di più che l'integrazione rispetti le regole del gestionale. Verifica con il produttore cosa è disponibile per la tua versione e quali moduli servono.
Lo stock deve essere sincronizzato in tempo reale?
Dipende dal rischio di vendere merce non disponibile. Per un catalogo con poche vendite concorrenti una sincronizzazione periodica può bastare. Per un magazzino con molte vendite simultanee serve un flusso più frequente e una regola chiara per le prenotazioni. In ogni caso serve un confronto periodico dei totali tra i sistemi.
Come gestisco un ordine rimasto a metà?
Ogni ordine deve avere stati espliciti, per esempio ricevuto, validato, trasmesso e confermato. Un ordine che si blocca resta in uno stato visibile e riprovabile. La riprova deve usare l'identificativo univoco per non creare un duplicato. Chi riceve la notifica deve avere un'azione chiara da compiere, altrimenti l'ordine resta fermo per giorni.
Posso modificare un documento contabile già creato?
In genere no, e non andrebbe fatto neanche tramite integrazione. Le correzioni si fanno con note di credito o storni secondo le regole del gestionale, così la traccia resta leggibile. Se un'integrazione permette di modificare documenti chiusi, valuta il rischio con il commercialista prima di attivarla.
Chi deve testare l'integrazione?
Il test deve essere condiviso tra chi gestisce la contabilità, chi gestisce logistica ed e-commerce e il tecnico che costruisce il flusso. I casi di prova devono includere situazioni reali: resi, annullamenti, prezzi diversi, clienti con più sedi, chiusure di periodo. Un test con dati di prova che non assomigliano ai dati reali non dimostra nulla.