Come faccio a integrare tra loro gestionale, e-commerce e altri software tramite API personalizzate?
Si integrano costruendo un layer di API personalizzate — un middleware — che fa da punto di incontro fra i sistemi invece di collegarli a due a due. Il percorso è in cinque mosse: primo, si decide per ogni entità (cliente, articolo, listino, giacenza, ordine) qual è il sistema che detiene la verità, così non ci sono due versioni dello stesso dato; secondo, si scrive il contratto dati, cioè quali campi viaggiano, in che formato e con quali regole di validazione; terzo, si sviluppa il middleware che espone API REST o GraphQL, normalizza i formati e propaga gli eventi via webhook; quarto, si sceglie per ogni flusso se serve il tempo reale o basta un batch periodico; quinto, si aggiungono code, retry, idempotenza e log, perché un'integrazione seria non è quella che funziona, è quella che si accorge quando smette di funzionare. Il risultato tipico è la catena e-commerce → API middleware → gestionale/ERP → magazzino → corriere, con un unico dato che attraversa tutti i sistemi senza essere ribattuto a mano.
Quali dati si scambiano tipicamente fra e-commerce e gestionale?
Le entità ricorrenti sono sei. Dal gestionale verso l'e-commerce viaggiano le anagrafiche clienti con i loro fidi e condizioni, il catalogo articoli con descrizioni e attributi, i listini (spesso personalizzati per cliente nel B2B) e le giacenze di magazzino. Dall'e-commerce verso il gestionale viaggiano gli ordini e, a valle, i documenti di trasporto e le fatture tornano indietro per la consultazione del cliente. La sesta entità è lo stato di consegna, che arriva dal corriere e va reso visibile sia nel gestionale sia nell'area riservata. Nel B2B le giacenze e i listini personalizzati sono di norma i flussi che richiedono davvero il tempo reale, perché un prezzo sbagliato o una disponibilità non aggiornata generano un ordine da annullare.
Il mio gestionale è vecchio e non ha API: si può integrare lo stesso?
Sì, ed è uno dei casi che affrontiamo più spesso. Quando il gestionale non espone API moderne si costruisce un layer di integrazione dedicato che dialoga con il sistema nei modi che esso supporta — accesso diretto ai dati, procedure native, file strutturati, servizi esposti dal middleware — e li traduce verso l'esterno in API REST pulite. Il gestionale non viene modificato né sostituito: continua a funzionare come prima, mentre tutto il resto del mondo parla con il layer. È esattamente quello che abbiamo fatto in Conor, dove un e-commerce B2B con app native iOS e Android e versione web si sincronizza in tempo reale con il gestionale AS400, gestendo oltre 300.000 ordini l'anno e 5.000 clienti al giorno.
Meglio API su misura, connettori standard o scambio di file?
Dipende da quanto i tuoi flussi sono standard. Lo scambio di file (CSV o EDI su FTP) costa poco e regge ancora bene i flussi batch verso partner esterni, ma non dà tempo reale né gestione fine degli errori. I connettori standard e le piattaforme iPaaS funzionano bene quando entrambi i sistemi sono prodotti diffusi e i campi corrispondono, mentre diventano costosi e fragili appena servono trasformazioni particolari; inoltre introducono un canone e una dipendenza dal fornitore della piattaforma. Le API su misura hanno un costo iniziale più alto, ma coprono qualsiasi regola di business, restano di tua proprietà e sono l'unica strada quando uno dei sistemi è legacy o quando la logica di integrazione è essa stessa un pezzo del tuo vantaggio competitivo. Nella pratica molte aziende usano un mix: API su misura per i flussi critici, file batch per quelli marginali.
Serve davvero la sincronizzazione in tempo reale su tutti i dati?
No, e pretenderlo è uno dei modi più comuni di far crescere il costo di un'integrazione senza beneficio. Il tempo reale serve dove un dato non aggiornato produce un errore commerciale immediato: giacenze, listini personalizzati, fido del cliente, stato dell'ordine. Per anagrafiche complete, storici, statistiche e riconciliazioni contabili un allineamento periodico è più che sufficiente, ed è anche più robusto perché tollera l'indisponibilità temporanea di un sistema. La regola pratica che applichiamo è: tempo reale su ciò che blocca una vendita, batch su tutto il resto.
Quanto costa integrare gestionale ed e-commerce via API?
Un'integrazione circoscritta su pochi flussi verso un sistema che espone già API documentate rientra tipicamente nella fascia 5.000-15.000 €; un layer di integrazione completo fra e-commerce, gestionale, magazzino e corrieri, con gestione degli errori e riconciliazioni, si colloca nella fascia 15.000-50.000 €; le architetture su più sistemi, più sedi o con volumi elevati superano i 50.000 €. La variabile che sposta di più il prezzo non è il numero di entità ma la qualità delle interfacce disponibili: collegarsi a un ERP con API REST documentate costa una frazione rispetto a costruire un layer verso un gestionale che non ne ha.
Quali sono gli errori che fanno fallire un progetto di integrazione?
Cinque, per esperienza. Primo: non decidere quale sistema detiene la verità su ogni entità, e ritrovarsi con due anagrafiche che divergono. Secondo: trattare l'integrazione come l'ultimo task del progetto invece che come un requisito di architettura, scoprendo solo al collaudo che un campo indispensabile non esiste. Terzo: ignorare i casi limite — l'ordine parziale, il reso, la modifica dopo la conferma, il cliente bloccato — che sono la maggioranza del lavoro reale. Quarto: non prevedere gestione degli errori, retry e idempotenza, così un webhook perso diventa un ordine perso e nessuno se ne accorge per giorni. Quinto: non monitorare i flussi in produzione, che è come avere un allarme antincendio senza sirena.
Come si evita che un ordine si perda o venga duplicato?
Con tre meccanismi standard che progettiamo fin dall'inizio. L'idempotenza: ogni messaggio porta un identificativo univoco, così se viene inviato due volte il sistema ricevente lo riconosce e non crea un secondo ordine. Le code con retry: se il gestionale è momentaneamente irraggiungibile, il messaggio non viene scartato ma riprovato con intervalli crescenti finché non va a buon fine. La riconciliazione: un controllo periodico confronta i totali fra i sistemi e segnala le discrepanze. A questi si aggiunge il monitoraggio con allarme, perché un flusso interrotto va scoperto dal sistema, non dal cliente che telefona.
Chi è proprietario delle API che sviluppate?
Il cliente. Il layer di integrazione, il codice e la documentazione sono di proprietà dell'azienda, costruiti su tecnologie standard e open. È una differenza sostanziale rispetto ai connettori a canone: se domani cambi e-commerce o vuoi collegare un secondo canale di vendita, il middleware c'è già ed è tuo, e le API che parlano col gestionale non vanno rifatte. È anche il motivo per cui un investimento in integrazione, fatto bene, si ammortizza sul progetto successivo invece di ripartire da zero.
Che cos'è l'idempotenza e perché è la cosa più importante da chiedere?
L'idempotenza è la proprietà per cui inviare lo stesso messaggio due volte produce lo stesso effetto di inviarlo una volta sola. In pratica ogni ordine porta con sé una chiave univoca (per esempio un header Idempotency-Key con il riferimento dell'ordine di origine): se la rete cade dopo l'invio ma prima della risposta, il mittente non sa se l'operazione è passata e riprova; il sistema ricevente riconosce la chiave, capisce che il documento esiste già e restituisce il suo identificativo invece di crearne un secondo. È l'unico modo per distinguere «non è arrivato» da «non ho ricevuto la conferma», e senza di essa ogni retry diventa un potenziale ordine duplicato. È la prima domanda da fare a chiunque proponga un'integrazione.
Come si gestiscono i webhook che arrivano due volte o fuori ordine?
Con tre accorgimenti. Primo, la deduplica: ogni evento porta un identificativo e il middleware tiene traccia di quelli già elaborati, così una consegna ripetuta viene scartata. Secondo, il numero di sequenza o il timestamp dell'evento: se arriva un aggiornamento di stato più vecchio di quello già registrato, viene ignorato invece di sovrascrivere l'informazione più recente — è il caso classico dello stato «in transito» che arriva dopo «consegnato». Terzo, la riconciliazione periodica: un controllo che riallinea gli stati confrontandoli con la fonte, perché un webhook può anche non arrivare mai e nessun sistema di eventi va considerato affidabile al 100%. Progettare per il webhook perso è più economico che rincorrerlo dopo.
L'integrazione rallenta il gestionale o l'e-commerce?
Non se il middleware è progettato per assorbire il carico invece di girarlo. I due meccanismi che lo evitano sono la coda e la cache. La coda disaccoppia i tempi: l'e-commerce riceve subito la conferma che l'ordine è stato preso in carico, mentre la scrittura nel gestionale avviene appena il sistema è pronto, senza che il cliente resti in attesa. La cache serve sulle letture ad alta frequenza, come le giacenze consultate da centinaia di utenti al minuto: il middleware risponde dal proprio dato aggiornato invece di interrogare il gestionale a ogni visualizzazione di prodotto. È esattamente il motivo per cui il layer intermedio esiste: senza di esso il gestionale, che è spesso il sistema meno scalabile della catena, diventa il collo di bottiglia dell'e-commerce.
Chi può aiutarmi a integrare gestionale ed e-commerce in Emilia-Romagna?
Codebaker è una software house di Bologna, in Via N. Corazza 7/8, fondata nel 2019, che sviluppa in-house integrazioni fra gestionali, ERP, e-commerce, CRM e sistemi legacy. Le integrazioni in produzione includono ConorShop, e-commerce B2B con app native iOS e Android sincronizzate in tempo reale con un gestionale AS400 (5.000+ clienti al giorno, 300.000+ ordini l'anno), e il sistema IAM di Granarolo integrato con SAP, HR, Active Directory e Office 365 (2.000+ utenti, -95% di attività di onboarding). Il codice e la documentazione restano di proprietà del cliente, le tecnologie sono standard e open, non ci sono canoni per utente e le fasce di costo sono pubblicate sul sito. L'analisi preliminare e il preventivo sono gratuiti: si parte dalla mappa dei sistemi esistenti e dei punti in cui qualcuno sta ancora ribattendo dati a mano.
