Integrazione API e Middleware: collegare gestionali, CRM ed e-commerce

Quasi ogni azienda che incontriamo ha lo stesso problema, anche se lo chiama in modi diversi: il gestionale fa bene l’amministrazione, il CRM segue le vendite, l’e-commerce vende, ma nessuno dei tre sa cosa fanno gli altri. In mezzo ci sono persone che copiano dati a mano, file Excel che girano per email e numeri che non tornano mai. L’integrazione con API e middleware è il modo in cui si fanno dialogare i software che l’azienda usa già, senza buttarli via e senza ricominciare da zero.

In questa guida spieghiamo cosa sono API e middleware (senza gergo), quando servono davvero, quali sono i casi più comuni e, soprattutto, dove sta la vera difficoltà di un progetto di integrazione. Che quasi mai è quella tecnica.

API e middleware, spiegati senza gergo

Un’API (Application Programming Interface) è lo sportello che un software apre verso l’esterno. Come uno sportello vero, ha regole precise: cosa si può chiedere, in che formato, chi è autorizzato a farlo. Quando l’e-commerce chiede al gestionale “quanti pezzi ho di questo articolo?” e riceve una risposta, sta usando un’API. Due software, una domanda, una risposta: è un collegamento diretto, punto a punto.

Un middleware è invece uno strato di software che sta in mezzo a più sistemi. Somiglia a un centralino con un interprete: riceve i dati da un sistema, li traduce nel formato che serve all’altro, decide a chi consegnarli, tiene traccia di cosa è passato e riprova se qualcosa va storto. Il middleware non sostituisce le API, le usa: parla con ogni sistema attraverso il suo sportello e coordina il traffico.

La regola pratica che usiamo: finché i sistemi da collegare sono due o tre, un’integrazione diretta via API è quasi sempre la scelta giusta. Quando si superano i quattro o cinque, i collegamenti punto a punto si moltiplicano (con cinque sistemi possono diventare dieci) e ogni modifica rischia di romperne un altro. È lì che un middleware inizia a ripagarsi.

Quando serve un’integrazione tra gestionale, CRM ed e-commerce

I segnali sono quasi sempre gli stessi, e di solito si vedono prima nelle persone che nei software:

• C’è doppia digitazione: gli ordini arrivati dall’e-commerce vengono ribattuti nel gestionale.
• I dati sono disallineati: il magazzino dice 100 pezzi, il sito ne mostra 120.
• L’amministrazione prepara a mano i file per il commercialista o per la banca.
• Gli ordini si perdono tra email, fogli Excel e post-it.
• Non esiste una vista unica del cliente: ogni reparto ne conosce un pezzo.
• Ogni campagna marketing parte con un’estrazione manuale delle liste.

Se ne riconosci due o più, il costo lo stai già pagando, solo che non compare in nessuna fattura: è fatto di ore, errori e ritardi. Ne abbiamo parlato nel dettaglio in Le 200 ore che non trovi in nessun bilancio.

I casi di integrazione più comuni

Gestionale e e-commerce

È l’integrazione più richiesta. Catalogo, prezzi, disponibilità, ordini e fatture devono passare da un sistema all’altro senza interventi manuali. Nella configurazione tipica il gestionale comanda su prodotti e giacenze, mentre l’e-commerce invia al gestionale ordini e nuovi clienti.

CRM e gestionale

Il commerciale vuole vedere nel CRM se il cliente ha pagato, cosa ha ordinato e se ci sono insoluti; l’amministrazione vuole che le anagrafiche inserite dai commerciali arrivino complete e corrette. Abbiamo fatto i conti su un caso reale in Il ritorno di un’integrazione CRM-gestionale, voce per voce.

CRM e marketing automation

I contatti del CRM vengono segmentati e inviati alla piattaforma di email marketing (Mailchimp, Brevo, HubSpot, ActiveCampaign); aperture, clic e disiscrizioni tornano indietro per aggiornare lo stato del contatto.

ERP e produzione

Gli ordini di produzione passano dall’ERP al sistema MES e i consuntivi tornano indietro per aggiornare costi e chiudere le commesse. Ne parliamo nell’articolo su MES e SCADA su misura.

E-commerce e corrieri, banca e gestionale

Etichette di spedizione e tracking generati in automatico tramite le API di BRT, GLS, Poste, DHL o UPS. Sul fronte finanziario, riconciliazione dei movimenti bancari con le fatture emesse attraverso flussi CBI o PSD2.

Come si collegano due software: i metodi possibili

Non tutti i software espongono le stesse porte d’ingresso. La scelta del metodo dipende da cosa offrono i sistemi coinvolti e da quanto devono essere “freschi” i dati.

• REST API: lo standard moderno, richieste HTTP con dati in JSON. La maggior parte dei software gestionali e cloud recenti (Fatture in Cloud, HubSpot, Salesforce, Stripe, molti prodotti Zucchetti) le mette a disposizione.
• SOAP e XML: tipici dei sistemi più datati o enterprise. Più pesanti, ma ancora diffusi in ambito bancario e industriale.
• Scambio di file (CSV, XML, EDI): esportazioni periodiche depositate su SFTP o cartelle condivise. Rodato e affidabile quando non serve il tempo reale; spesso è l’unica strada con i gestionali installati in azienda da molti anni.
• Webhook: il sistema di origine avvisa gli altri appena succede qualcosa (nuovo ordine, pagamento confermato). Evita di interrogare di continuo un sistema per sapere se ci sono novità.
• Broker di messaggi (RabbitMQ, Kafka, code cloud): per architetture con molti sistemi che producono e consumano eventi. È il cuore di molti middleware.

La vera difficoltà: la governance dei dati

Qui sta il punto che fa la differenza tra un’integrazione che funziona per anni e una che si trasforma in un problema nuovo. Collegare due API è la parte facile. La parte difficile è decidere cosa devono significare i dati quando passano da un sistema all’altro, e chi ne è responsabile. È quello che si chiama governance dei dati, e in un progetto di integrazione pesa più di qualsiasi scelta tecnologica.

Un’integrazione automatizza le regole che l’azienda ha già. Se le regole non ci sono, automatizza il disordine, e lo fa molto più velocemente di prima.

Chi comanda su ogni dato

Per ogni informazione va stabilita una fonte di verità: il sistema che ha l’ultima parola. Sembra ovvio, ma è la domanda a cui le aziende faticano di più a rispondere, perché nel tempo ogni reparto si è abituato a correggere i dati nel proprio software.

La tabella è un esempio, non una regola: in ogni azienda va costruita con chi usa quei dati tutti i giorni.

Stesso codice, stesso significato

Il codice articolo del gestionale spesso non coincide con lo SKU dell’e-commerce; lo stesso cliente può esistere tre volte con tre ragioni sociali scritte in modo leggermente diverso. Prima di collegare i sistemi servono chiavi univoche condivise o tabelle di transcodifica mantenute nel tempo, altrimenti l’integrazione crea doppioni invece di eliminarli.

Cosa succede quando due sistemi non sono d’accordo

Il commerciale aggiorna l’indirizzo nel CRM, l’amministrazione lo corregge nel gestionale lo stesso giorno. Quale vince? Le regole di conflitto vanno scritte prima, campo per campo, non scoperte dopo il primo errore in fattura.

Dati puliti prima, non dopo

Integrare dati sporchi significa distribuirli ovunque. Una fase di bonifica (duplicati, campi obbligatori vuoti, formati incoerenti) prima del go-live costa meno di qualsiasi correzione successiva.

Un responsabile, anche dopo il rilascio

Ogni flusso ha bisogno di una persona in azienda che sappia cosa fa e che riceva gli avvisi quando qualcosa si blocca. Serve anche attenzione alla privacy: in ottica GDPR i dati personali devono viaggiare solo verso i sistemi che ne hanno davvero bisogno, e i log devono permettere di ricostruire chi ha ricevuto cosa.

Per questo i nostri progetti di integrazione iniziano con una mappatura dei flussi e delle responsabilità, non con il codice. È la fase che spieghiamo in Il nostro metodo in 4 fasi.

Come si sviluppa un progetto di integrazione

1. Mappatura dei flussi e delle regole: quali dati, da dove a dove, con quale frequenza, quale sistema comanda e chi è responsabile.
2. Analisi delle API disponibili: documentazione, autenticazione, limiti di chiamate e volumi di ogni sistema coinvolto.
3. Scelta dell’architettura: collegamento diretto per i casi semplici, middleware centralizzato quando i sistemi sono molti.
4. Sviluppo dei connettori: autenticazione, mappatura dei campi, trasformazioni di formato, gestione degli errori.
5. Test in ambiente separato: casi normali e casi limite (sistema offline, dati malformati, duplicati, aggiornamenti simultanei).
6. Monitoraggio e avvisi: log centralizzati, cruscotto di stato, notifiche automatiche quando un flusso si ferma.
7. Avvio graduale: si parte con volumi ridotti e si aumenta quando la stabilità è dimostrata.

Tecnologie che usiamo

• Linguaggi per i connettori: Node.js, Python, PHP, Go, scelti in base ai sistemi da collegare e alle librerie disponibili.
• Piattaforme di integrazione: Zapier e Make per i flussi semplici, n8n self-hosted quando i dati devono restare in casa, middleware su misura quando servono logiche di business complesse.
• Code e broker: RabbitMQ, Kafka, code cloud per le architetture a eventi.
• Affidabilità: tentativi automatici con attese crescenti, code per i messaggi non elaborati, riconciliazione per i casi eccezionali.
• Monitoraggio: Grafana, Elastic o soluzioni dedicate con log strutturati.

Quanto costa un progetto di integrazione

• Integrazione semplice (due sistemi, API REST ben documentate, flusso in una sola direzione): 3.000 – 10.000 euro.
• Integrazione media (flusso bidirezionale, trasformazioni dei dati, gestione errori robusta): 10.000 – 30.000 euro.
• Middleware su misura (piattaforma centrale per più sistemi, monitoraggio, reportistica): 30.000 – 100.000 euro.
• Integrazione enterprise (decine di sistemi, volumi elevati, requisiti di compliance): oltre 100.000 euro.

A questo si aggiunge la manutenzione annuale, tipicamente tra il 15 e il 25 percento del costo di sviluppo: le API dei sistemi terzi cambiano più spesso di quanto si pensi, e ogni cambiamento va assorbito senza fermare l’azienda.

Gli errori più frequenti

1. Collegare prima di decidere chi comanda: senza una fonte di verità per ogni dato, i sistemi si sovrascrivono a vicenda.
2. Non gestire i fallimenti: ogni API prima o poi va offline. Senza tentativi automatici, code e avvisi ci si ritrova con dati mancanti senza accorgersene.
3. Troppi collegamenti punto a punto: oltre i quattro o cinque sistemi la ragnatela diventa ingestibile.
4. Ignorare i limiti delle API: molte API commerciali limitano il numero di chiamate al minuto o al giorno, e il flusso va progettato per rispettarli.
5. Log insufficienti: quando qualcosa si rompe sei mesi dopo il rilascio, senza log dettagliati non si capisce cosa sia successo.
6. Testare solo il caso ideale: un’integrazione che funziona nel 95 percento dei casi crea più lavoro di quanto ne tolga.

SPS Project: integrazione tra sistemi per le PMI del Nord Italia

Far dialogare i software che un’azienda usa già è la nostra specialità come software house. Dalla sede di Castelnuovo del Garda, in provincia di Verona, realizziamo integrazioni API e middleware per PMI del Veneto, della Lombardia, del Trentino e dell’Emilia-Romagna: gestionali italiani ed esteri collegati a e-commerce, CRM, piattaforme marketing, banche, corrieri e sistemi industriali. Un esempio concreto è raccontato in Quando tre software diventano uno solo.

Il nostro approccio parte sempre dai flussi reali e dalle regole sui dati, e arriva a una soluzione stabile, monitorata e documentata, il cui codice resta di proprietà del cliente.

I tuoi sistemi non si parlano? Con una analisi dei flussi e dei progetti di integrazione individuiamo insieme quali collegamenti rendono di più e da dove conviene partire.