Come integrare due software aziendali tramite API: la guida pratica per PMI

Ogni azienda che cresce si ritrova, prima o poi, con lo stesso problema: due software che non si parlano. Il gestionale da una parte, l'e-commerce dall'altra. Il CRM che non sa cosa succede in magazzino. Il risultato sono persone che copiano dati a mano da uno schermo all'altro, con la lentezza e gli errori che questo comporta.

La soluzione tecnica si chiama integrazione, e nella maggior parte dei casi passa dalle API. In questo articolo spieghiamo cosa sono, quali sono gli approcci possibili per far dialogare due sistemi, e come si affrontano i problemi concreti: sincronizzazione, errori, duplicati e i sistemi che semplicemente non hanno API.

Cosa sono le API, in parole semplici

API sta per "Application Programming Interface". Al di là della sigla, l'idea è semplice: è un modo standard con cui un software offre i propri dati e le proprie funzioni ad altri software.

Un paragone utile è il cameriere al ristorante. Voi non entrate in cucina a cucinare: dite al cameriere cosa volete, lui porta la richiesta in cucina e vi riporta il piatto. Non dovete sapere come è organizzata la cucina, vi basta il menù e il cameriere. L'API è quel cameriere: permette a un programma di chiedere qualcosa a un altro programma ("dammi l'anagrafica del cliente 4521", "crea questo ordine", "aggiorna la giacenza di questo prodotto") senza sapere come è fatto dentro.

Quando due software hanno delle API, farli comunicare diventa possibile in modo pulito e controllato. Quando non le hanno, la faccenda si complica, e ci torniamo più avanti.

Gli approcci per far dialogare due software

Non esiste un solo modo di integrare. La scelta dipende da come sono fatti i sistemi, da quanto devono essere reattivi e dal budget. Vediamo i quattro approcci principali.

API REST. È lo standard più diffuso oggi. Un sistema "interroga" l'altro tramite richieste su web, ricevendo in risposta dati in un formato strutturato (di solito JSON). È l'approccio giusto quando serve leggere o scrivere dati su richiesta: per esempio, quando l'e-commerce riceve un ordine e lo "spinge" dentro il gestionale creando il documento di vendita. È flessibile, ben documentato e supportato praticamente da qualsiasi software moderno.

Webhook. I webhook rovesciano la logica. Invece di chiedere continuamente "ci sono novità?", è il sistema che avvisa in automatico quando qualcosa accade. L'e-commerce, appena arriva un ordine, "chiama" il gestionale e gli dice "è arrivato questo ordine, prendilo". È efficiente perché lo scambio avviene solo quando serve, e mantiene i dati aggiornati quasi in tempo reale. Spesso REST e webhook lavorano insieme: il webhook segnala l'evento, poi si usano le API REST per scambiare i dettagli.

Middleware. Quando i sistemi da collegare sono più di due, o quando la logica di trasformazione dei dati è complessa, conviene inserire un software "intermediario" che fa da centralino. Il middleware riceve i dati da un sistema, li converte nel formato che l'altro si aspetta e li consegna, gestendo tempi, errori e code. È l'approccio più robusto per scenari articolati, ma richiede più lavoro iniziale.

Scambio file. L'approccio più vecchio, ma ancora vivo. Un sistema esporta un file (CSV, XML) in una cartella o su un server, l'altro lo legge a intervalli regolari. Non è elegante e non è in tempo reale, ma a volte è l'unica strada praticabile, soprattutto con software datati. Da usare quando le altre porte sono chiuse.

Se volete approfondire come impostiamo questi collegamenti, ne parliamo nella pagina dedicata all'integrazione tramite API.

I problemi veri: sincronizzazione, errori e duplicati

Collegare due sistemi è la parte facile. La parte difficile è farli restare coerenti nel tempo. Qui si gioca la differenza tra un'integrazione che funziona e una che genera più problemi di quanti ne risolva.

Sincronizzazione. Bisogna decidere in quale direzione viaggiano i dati e chi comanda. Le anagrafiche clienti le gestisce il gestionale o l'e-commerce? Se un prezzo viene cambiato in entrambi, quale vince? Serve stabilire una "fonte di verità" per ogni tipo di dato. Va poi scelto il ritmo: in tempo reale (via webhook), oppure a intervalli (ogni cinque minuti, ogni ora, ogni notte). Le giacenze di magazzino, per esempio, spesso richiedono aggiornamenti frequenti per evitare di vendere prodotti esauriti; le anagrafiche possono aggiornarsi più lentamente.

Gestione degli errori. Le connessioni cadono, i server vanno in manutenzione, un dato arriva malformato. Un'integrazione seria non può fermarsi al primo intoppo. Servono meccanismi di ripetizione automatica (se una richiesta fallisce, si riprova dopo qualche secondo), una coda che trattiene i dati non ancora consegnati, e soprattutto notifiche: se qualcosa si blocca, qualcuno deve saperlo, invece di scoprirlo giorni dopo dai reclami dei clienti.

Duplicati. È il problema più insidioso. Se un webhook parte due volte, o l'integrazione riparte dopo un errore, si rischia di creare due volte lo stesso ordine o lo stesso cliente. La soluzione tecnica si chiama idempotenza: ogni operazione porta un identificativo univoco, così il sistema ricevente riconosce di aver già elaborato quel dato e non lo duplica. È un dettaglio che l'utente non vede mai, ma che separa un'integrazione affidabile da una che sporca il database.

Questi meccanismi sono anche il motivo per cui l'infrastruttura conta. Un'integrazione ben progettata va monitorata e deve poter essere aggiornata senza fermare l'attività: sono temi che rientrano nel cloud e nelle pratiche DevOps.

Quando un sistema è chiuso e non ha API

Capita spesso, soprattutto con gestionali datati o software verticali di nicchia: non c'è nessuna API. Cosa si fa?

Le strade sono diverse, in ordine di preferenza. La prima è verificare se esiste comunque un modo di esportare e importare dati, anche solo via file: molti software "chiusi" permettono comunque export in CSV o accesso al database. La seconda, se il software è installato su un vostro server, è collegarsi direttamente al database sottostante, con cautela e in sola lettura quando possibile, per non rischiare di corrompere i dati.

Quando anche questo non basta, si ricorre a tecniche di automazione che simulano un operatore umano (i cosiddetti bot RPA): sono soluzioni-ponte, utili ma fragili, perché si rompono se l'interfaccia del programma cambia. L'ultima opzione, la più onesta da valutare con lucidità, è chiedersi se quel software chiuso valga davvero la pena di tenerlo. A volte il costo di aggirarlo supera il costo di sostituirlo con un gestionale su misura che nasce già pronto a integrarsi.

Un esempio concreto: gestionale ed e-commerce

Mettiamo insieme i pezzi con lo scenario più comune, quello di un negozio che vende anche online.

Ordini. Un cliente compra sul sito. L'e-commerce, tramite webhook, avvisa il gestionale che arriva un nuovo ordine e ne trasmette i dettagli via API. Il gestionale crea il documento di vendita, con un identificativo univoco che impedisce doppioni. L'ufficio non deve trascrivere nulla.

Giacenze. Quando parte la merce dal magazzino, il gestionale aggiorna la disponibilità e comunica il nuovo valore all'e-commerce. Così il sito mostra sempre lo stock reale ed evita di vendere ciò che non c'è. Qui la frequenza di aggiornamento è cruciale: più il catalogo si muove, più lo scambio deve essere frequente.

Anagrafiche. Cliente e prodotti restano allineati tra i due sistemi. Si decide chi è la fonte di verità (spesso il gestionale per i dati fiscali, l'e-commerce per le descrizioni commerciali) e si sincronizza di conseguenza, evitando che lo stesso cliente esista in due versioni diverse.

Il risultato non è "magia": è un flusso di dati progettato con attenzione, che elimina il lavoro manuale e i suoi errori, lasciando alle persone le attività che contano davvero.

Parliamone

Ogni integrazione è un caso a sé: dipende dai software che avete, da quanto sono aperti e da cosa vi serve ottenere. A volte basta un collegamento semplice, a volte serve un middleware ben pensato. Se state valutando come far dialogare due sistemi e volete capire quale approccio ha senso nella vostra situazione, senza sovradimensionare, scriveteci per un confronto. Vi diciamo con franchezza cosa è realistico e cosa no.