API e integrazioni: come far comunicare gestionale, CRM, sito e altri software

Un’integrazione API è un collegamento automatico tra due software: quando succede qualcosa in uno, per esempio arriva un ordine dal sito, l’altro riceve i dati e li registra senza che nessuno li ricopi a mano. L’API è la «porta» che ogni software mette a disposizione per scambiare dati in modo controllato. Collegare gestionale, CRM, ecommerce, pagamenti e fatturazione è quasi sempre possibile; quello che cambia da caso a caso è quanto sono ben documentati i sistemi coinvolti, quanti flussi servono e quanto devono essere affidabili.

Cos’è un’API spiegata senza tecnicismi

Pensa a uno sportello: non entri nel magazzino di un’azienda, chiedi allo sportello e ricevi quello che ti serve, secondo regole precise. Un’API funziona allo stesso modo. Il tuo ecommerce non legge direttamente il database del gestionale: gli chiede «crea questo ordine» o «dammi la disponibilità di questo prodotto», e il gestionale risponde in un formato concordato.

Un’integrazione è l’insieme di queste richieste messe in fila per automatizzare un processo: chi chiama chi, con quali dati, in quale momento e cosa fare se qualcosa va storto.

Perché i software aziendali rimangono spesso isolati

Di solito non è una scelta. Gli strumenti si aggiungono uno alla volta: prima il gestionale, poi il sito, poi un CRM, poi il sistema di pagamento, ognuno scelto per risolvere un problema preciso. Nessuno ha pensato a come si sarebbero parlati.

Il risultato è che il collegamento lo fanno le persone: esportano un file, lo sistemano, lo reimportano, ricopiano un ordine, controllano a mano che un pagamento sia arrivato. Funziona finché i volumi sono bassi; poi diventa tempo perso e fonte di errori, e spesso spinge a valutare se tenere i software attuali o passare a un gestionale su misura o a un software standard.

Un esempio pratico di integrazione

Un flusso tipico, a titolo illustrativo, per un’azienda che vende online:

1. Il cliente compra sul sito.
2. Il sistema di pagamento conferma l’incasso.
3. L’ordine entra nel gestionale, che scala la disponibilità.
4. Parte la richiesta al sistema di fatturazione.
5. Il cliente viene aggiornato nel CRM.
6. Parte l’email di conferma.

L’ordine reale dipende dal processo: c’è chi fattura solo alla spedizione, chi aspetta una conferma manuale, chi gestisce acconti. Per questo un’integrazione non si progetta partendo dai software, ma dal processo: prima si scrive cosa deve succedere, poi si decide quale sistema fa cosa.

Quali software possiamo collegare

In pratica quasi tutti quelli che espongono un’API o un altro canale di scambio dati:

Nel turismo il caso classico è tenere allineate le disponibilità tra sito, telefono e agenzie: ne parlo nell’articolo su come evitare l’overbooking vendendo su più canali. Collegare i dati aziendali è anche la base per un assistente AI che risponde usando i tuoi dati.

API REST, webhook e sincronizzazioni: differenza

Sono tre cose diverse, non tre alternative equivalenti:

• API REST: è l’interfaccia. Un software fa una richiesta («dammi gli ordini di oggi», «crea questo cliente») e riceve una risposta. È il modo più diffuso con cui i software moderni espongono i propri dati.
• Webhook: è una notifica. Invece di chiedere continuamente «ci sono novità?», è il sistema di origine ad avvisare l’altro quando succede qualcosa, per esempio «pagamento ricevuto». Di solito la notifica contiene un riferimento, e chi la riceve usa poi l’API per leggere i dettagli.
• Sincronizzazione: è il processo che tiene allineati i dati tra due sistemi nel tempo, usando API, webhook o entrambi.

Sincronizzazione in tempo reale o programmata

Non tutto deve essere istantaneo.

• Tempo reale (con webhook o chiamate immediate) serve quando un ritardo crea un problema: disponibilità di posti, conferma di un pagamento, stato di una prenotazione.
• Programmata (ogni tot minuti, ogni notte) va bene per ciò che può aspettare: aggiornamento dei listini, invio dei dati al CRM, report.

Spesso la soluzione giusta le combina: il webhook porta la novità subito, e un controllo periodico verifica che non si sia perso nulla. Questo controllo si chiama riconciliazione: confrontare i dati dei due sistemi e sistemare le differenze.

Cosa succede se un software non dispone di API

Non è per forza un vicolo cieco. Le strade possibili, da valutare caso per caso:

• Esportazioni e importazioni automatiche di file (CSV, Excel, XML) su una cartella o un server, lette e scritte a orari stabiliti.
• Connettori autorizzati messi a disposizione dal produttore o da partner certificati.
• Accesso diretto al database, solo se il fornitore lo consente e con molta cautela, perché un aggiornamento del software può cambiare la struttura senza preavviso.

Prima di tutto va verificato cosa permette il contratto con il fornitore: non tutto ciò che è tecnicamente possibile è anche consentito.

Sicurezza e autenticazione

Le API sono sicure quanto lo è il modo in cui vengono configurate. Gli elementi di base:

• Autenticazione: ogni sistema che chiama un’API si identifica con credenziali proprie (chiavi, token), che si possono revocare singolarmente.
• Permessi minimi: un’integrazione deve poter fare solo quello che le serve. Chi legge gli ordini non deve poter cancellare i clienti.
• Connessioni cifrate e credenziali conservate fuori dal codice.
• Log: sapere chi ha fatto cosa e quando, per capire cosa è successo in caso di problemi.

Cosa succede quando un sistema non risponde

Prima o poi succede: un servizio esterno è lento, in manutenzione o restituisce un errore. Un’integrazione fatta bene lo prevede.

• Retry: se una chiamata fallisce, si riprova dopo un po’, con attese crescenti, invece di perdere il dato.
• Idempotenza: se lo stesso ordine arriva due volte (succede, proprio per via dei retry), deve essere registrato una volta sola. Si ottiene con identificativi univoci per ogni operazione.
• Rate limit: molti servizi limitano il numero di richieste in un certo intervallo; l’integrazione deve rispettarlo e mettere in coda il resto.
• Mapping: i due sistemi chiamano le cose in modo diverso (codici IVA, stati dell’ordine, categorie). Le regole di conversione vanno scritte e mantenute.
• Monitoraggio e avvisi: quando qualcosa fallisce in modo definitivo, qualcuno deve saperlo, con il dettaglio di cosa è andato storto e la possibilità di rilanciare l’operazione.

È la parte meno visibile e quella che distingue un collegamento che regge da uno che va controllato a mano ogni giorno.

Quanto costa un’integrazione API

Non esiste un prezzo standard, perché dipende da fattori molto diversi tra un progetto e l’altro:

• Qualità della documentazione dei sistemi da collegare: API ben documentate richiedono meno tempo di analisi.
• Accesso: alcune API sono incluse, altre richiedono piani specifici o autorizzazioni dal fornitore.
• Numero di flussi: sincronizzare solo gli ordini è diverso dal sincronizzare ordini, clienti, catalogo e pagamenti.
• Trasformazioni dei dati: più i due sistemi ragionano in modo diverso, più regole di mapping servono.
• Affidabilità richiesta: retry, riconciliazione, monitoraggio e avvisi sono lavoro in più, ma su un flusso critico sono indispensabili.
• Manutenzione: i software esterni cambiano le loro API nel tempo, e l’integrazione va aggiornata di conseguenza.

Per questo si parte quasi sempre da un’analisi: quali sistemi, quali dati, in quale direzione, con quale urgenza. Spesso conviene iniziare dal flusso che oggi fa perdere più tempo e aggiungere gli altri dopo.

Quando conviene costruire un layer API centrale

Quando i sistemi da collegare sono due, un collegamento diretto basta. Quando diventano molti, collegarli tutti con tutti crea una rete difficile da mantenere: ogni modifica a un sistema rischia di rompere più collegamenti.

Un layer API centrale è un software intermedio che parla con tutti gli altri e diventa il punto unico in cui stanno regole, log e gestione degli errori. Ha senso anche quando sei tu a dover esporre dati a partner esterni. In una piattaforma di gioco che ho sviluppato, gli operatori esterni si collegano tramite API documentate, con autenticazione separata per ogni operatore, una libreria client da integrare nei loro sistemi ed errori standardizzati, così che ogni partner sappia sempre come interpretare una risposta. Puoi vedere il progetto tra i miei lavori.

Cosa verificare prima di partire

• Quali dati ricopi oggi a mano, e quanto spesso.
• Quale sistema è la fonte di verità per ogni dato (chi ha ragione se due valori non coincidono).
• Se i software coinvolti hanno API documentate e se il tuo piano le include.
• Cosa deve succedere se un passaggio fallisce, e chi deve saperlo.
• Chi si occuperà dell’integrazione quando uno dei software cambia.

Se vuoi capire da dove partire, guarda come lavoro sulle integrazioni tra software oppure raccontami quali software usi e quali dati ricopi: valutiamo insieme come collegarli. La prima analisi è gratuita.

Domande frequenti

Tutti i software possono essere integrati?

Quasi tutti, ma non sempre nello stesso modo. Se c’è un’API documentata il collegamento è più diretto; altrimenti si valutano esportazioni automatiche o connettori autorizzati. In alcuni casi il limite è contrattuale più che tecnico.

Cos’è un webhook, in una frase?

È un avviso automatico che un software manda a un altro quando succede qualcosa, così l’altro non deve chiedere continuamente se ci sono novità.

Un’integrazione va mantenuta nel tempo?

Sì. I fornitori aggiornano le loro API, cambiano i processi interni e cambiano i dati. Per questo conviene che log, avvisi e documentazione siano parte del progetto fin dall’inizio.