Automatia
Cerca
Contatti

Cosa sono le API e come fanno parlare i software tra loro

Per chi dirige un'azienda e non scrive codice: cosa sono le API, come due programmi si passano ordini e fatture, cosa può fermarli e chi se ne occupa.

Team Automatia · pubblicata il · aggiornata il · 10 minuti di lettura

Schema che mostra cosa sono le API: il gestionale collegato al negozio online, ai pagamenti, al Sistema di Interscambio e a un programma senza API.
Ogni collegamento funziona in modo diverso: il webhook del negozio, la chiave dei pagamenti, il canale SdICoop. Dove l'API manca restano file, database o RPA.

In breve. Le API sono le porte da cui un programma accetta richieste da altri programmi, con regole scritte: quali dati dare, a chi, quante volte. Con un'integrazione tramite API l'ordine pagato sul sito entra nel gestionale senza che nessuno lo ricopi. Ogni collegamento usa una chiave con permessi propri e va seguito nel tempo, perché limiti e versioni cambiano.

Negozio online, fatturazione, CRM, pagamenti: molti dei programmi che un'azienda compra oggi dichiarano di avere delle API. Da quella parola dipende se due programmi lavorano insieme o se tra loro serve una persona che ricopia.

Qui trovi cosa sono le API e cosa sapere prima di chiedere un collegamento.

Una chiave per collegamento, solo i permessi che servono. Dati di esempio.

Cosa sono le API, spiegato con un esempio concreto

Un'API è una porta che un programma apre agli altri programmi: si fanno solo le richieste previste, in un formato preciso, e le risposte arrivano sempre nello stesso modo.

Cosa significa API lo dice la sigla: Application Programming Interface, cioè interfaccia di programmazione delle applicazioni. L'API fa per un altro programma quello che lo schermo del gestionale fa per una persona.

Un esempio con nomi di fantasia mostra a cosa servono le API meglio di una definizione. Ricambi Eta vende online e tiene magazzino e fatture in un gestionale, dove ogni mattina qualcuno ricopia gli ordini del sito. Quando i due programmi si parlano attraverso le API, il giro diventa questo:

  1. Il cliente paga sul sito

    Il negozio registra l'ordine 2051 e avvisa subito il gestionale.

  2. Il gestionale chiede i dettagli

    Con la sua chiave legge dall'API del negozio i dati del cliente, le righe e l'indirizzo.

  3. L'ordine entra nel gestionale

    Il cliente si riconosce dalla partita IVA, la merce si impegna, il DDT è pronto.

  4. La giacenza torna al sito

    Il gestionale aggiorna i pezzi disponibili, così nessuno compra merce finita.

Nessuno ha copiato niente, e ogni passaggio resta in un registro. Quali dati far passare e in che verso lo spiega la guida su come integrare e-commerce e gestionale.

Un'API ce l'ha anche il Sistema di Interscambio delle fatture elettroniche: il canale SdICoop, un web service riservato a chi si accredita, descritto nella documentazione dello SdI. Ha API ufficiali anche il RENTRI, il registro dei rifiuti: la guida su FIR digitale e RENTRI spiega come collegarlo al gestionale.

Le parole che tornano in ogni integrazione. Le altre sono nel glossario.
TermineSignificato in pratica
EndpointL'indirizzo di una singola richiesta, per esempio quella che elenca gli ordini
Chiave o tokenLa credenziale con cui un programma si fa riconoscere
WebhookL'avviso che un programma manda da solo quando succede qualcosa
Ambiente di provaUna copia del servizio, la sandbox, per provare senza toccare dati veri
Limite di richiesteQuante richieste si possono fare in un certo tempo

API REST: come si scrivono domande e risposte

Molti programmi in cloud offrono un'API REST, che usa le regole delle pagine web. Ogni ordine, cliente o fattura ha un suo indirizzo, su cui si fanno poche operazioni: leggere, creare, modificare, cancellare.

Ogni risposta porta un codice di tre cifre, fissato dagli standard del web (RFC 9110 e, per il 429, RFC 6585). Sono i numeri che compaiono nei messaggi di errore, e dicono da che parte sta il problema:

I codici di risposta più frequenti, e chi deve intervenire.
CodiceCosa vuol direChi interviene
200, 201Riuscita; con 201 è stato creato qualcosa, per esempio un clienteNessuno
401Chiave mancante, scaduta, revocata o sbagliataChi gestisce le chiavi
403Richiesta capita ma rifiutata, spesso per un permesso che mancaChi gestisce l'account
404Non esiste: un ordine cancellato, un codice articolo sbagliatoChi cura le anagrafiche
429Troppe richieste in poco tempoNessuno, se il collegamento aspetta e riprova
500, 503Errore o sovraccarico dall'altra parteIl collegamento riprova; se dura, il fornitore

Nelle API REST le risposte sono di solito in JSON, un elenco di nomi e valori che si capisce anche senza essere programmatori: {"numero": "2051", "totale": 184.50, "pagato": true}.

Webhook: quando è il programma ad avvisare

Un webhook è un avviso automatico. Invece di chiedere ogni quarto d'ora al negozio se ci sono ordini nuovi, il gestionale gli lascia un indirizzo, e il negozio lo chiama appena succede qualcosa.

Controllo a intervalliWebhook
Il gestionale chiede a orari fissi se ci sono novitàIl negozio avvisa appena l'ordine è pagato
Molte richieste vanno a vuotoNessuna richiesta a vuoto
L'ordine aspetta il controllo successivoLo stesso avviso può arrivare due volte, o perdersi
Funziona con qualunque APIServe un indirizzo raggiungibile da internet

I difetti vanno gestiti. La documentazione dei webhook di Stripe, per esempio, avverte che in modalità live la consegna si ritenta per un massimo di tre giorni, che lo stesso evento può arrivare più di una volta e che non si deve contare sull'ordine di arrivo.

Per questo un collegamento fatto bene verifica la firma di ogni avviso, scarta i doppioni dal codice dell'evento e ogni notte confronta i dati dei due programmi. Un caso completo, con una sola fattura per ogni pagamento, è nella guida su Stripe e fatturazione elettronica.

Chiave API e permessi: chi può fare cosa

Una chiave API è la credenziale con cui un programma si presenta: chi la possiede fa tutto quello che la chiave permette, finché qualcuno non la revoca. Va trattata come la chiave dell'ufficio.

  • Una chiave per collegamento. Si revoca quella del negozio senza fermare il CRM.
  • Solo i permessi che servono. WooCommerce fa scegliere tra lettura, scrittura o entrambe; Stripe consiglia chiavi con permessi limitati invece di quella che può tutto.
  • Mai per email o in chat. L'API key sta sul server che la usa; spesso il programma la mostra una volta sola.
  • Si cambia quando qualcuno se ne va. Lo raccomanda anche Stripe per chi aveva accesso alle chiavi.

Molti servizi in cloud usano OAuth 2.0: autorizzi il programma dal tuo account, per alcune operazioni, e lo revochi quando vuoi, senza consegnare la password. Tra i problemi della password condivisa che lo standard (RFC 6749) vuole evitare ci sono un accesso troppo ampio e una revoca possibile solo per tutti insieme.

Documentazione delle API: cosa guardare prima

La documentazione delle API è il manuale per chi deve collegarsi: richieste possibili, dati restituiti, permessi e limiti. Va letta prima di firmare un preventivo, perché dice se il collegamento si può fare e quanto lavoro chiede.

I punti da verificare nella documentazione prima del preventivo: per il gestionale di Ricambi Eta due restano da chiarire con il produttore.

Una documentazione seria ha esempi, codici di errore spiegati e un registro delle modifiche con le date. Un buon segno è un file OpenAPI: lo standard aperto che descrive un'API in un documento YAML o JSON, da cui gli strumenti ricavano un portale per provare le richieste, il codice per collegarsi e i casi di test.

Senza documentazione si procede per tentativi, e ogni sorpresa si paga.

Limiti delle API: richieste contate e versioni che cambiano

I limiti delle API che pesano di più su un collegamento sono due: quante richieste si possono fare in un certo tempo, e quanto vive una versione. Oltre il limite di richieste il servizio risponde con il codice 429 e può indicare quanto aspettare.

I numeri variano molto da un servizio all'altro: Stripe accetta in modalità live fino a 100 richieste al secondo per account; Fatture in Cloud 300 ogni 5 minuti per azienda, con quote di 1.000 all'ora e 40.000 al mese.

Un collegamento che chiede ogni minuto se ci sono fatture nuove fa, solo per controllare, 43.200 richieste in un mese di 30 giorni: più della quota. Finita la quota mensile, le richieste ricevono il codice 403, lo stesso di un permesso che manca, fino all'inizio del mese successivo. Con i webhook, che Fatture in Cloud offre a tutti gli utenti, si chiede solo quando c'è qualcosa da leggere.

Ogni controllo è una richiesta, e ogni fattura nuova un'altra per leggerla. La quota è quella mensile di Fatture in Cloud.

Poi le versioni: Shopify ne pubblica una ogni tre mesi e mantiene ciascuna per almeno 12 mesi; la Graph API di Meta garantisce ogni versione per almeno due anni.

Quando una versione si spegne, con questi due servizi le richieste non si fermano: Shopify risponde con la più vecchia ancora attiva, Meta passa le chiamate alla successiva utilizzabile. Il collegamento gira con regole diverse da quelle per cui era scritto, ed è un guasto difficile da vedere.

Se il programma non ha API: file, database o RPA

Molti gestionali installati in ufficio non hanno un'API, o la offrono solo con alcune licenze. Se l'API del gestionale manca, il collegamento si fa lo stesso, per altre strade:

Le alternative all'API, dalla più stabile alla più fragile.
StradaCome funzionaPunto debole
Scambio di fileFile CSV, Excel o XML esportati o importati in una cartella, a orari fissiDati a intervalli; se cambia il tracciato, l'import si ferma
Lettura del databaseI dati si leggono dove il programma li salvaScriverci salta i controlli: solo con il consenso del produttore
RPAUn robot software usa le schermate al posto di una personaSi ferma quando cambia una schermata: è l'ultima risorsa

Quando conviene un robot software lo spiega la guida su RPA e automazione robotica dei processi.

Due esperienze dei nostri team. Il gestionale costruito per uno studio di ingegneria con due partite IVA prepara il file XML delle fatture da importare nella piattaforma del commercialista, che non offre API e che firma e trasmette allo SdI.

Una rete di imprese lavorava invece sul portale di un fornitore esterno, da cui i dati uscivano solo leggendo le pagine web. Oggi ha un gestionale suo e offre ai negozi online degli iscritti un'API e una pagina di pagamento, in produzione da settembre 2026. Entrambi i casi sono nella pagina dei progetti.

Le API e l'intelligenza artificiale in azienda

Anche l'intelligenza artificiale passa dalle API. Il gestionale manda un documento al modello e riceve i dati estratti; un agente AI agisce sui programmi dell'azienda attraverso le loro API, con chiavi e permessi come quelli visti sopra.

Stripe, per esempio, permette di segnare una chiave come chiave di un agente autonomo: rimborsi, trasferimenti verso la banca e altre azioni sensibili aspettano l'approvazione di una persona designata. Il resto è nelle guide su come integrare l'intelligenza artificiale in azienda e sugli agenti AI.

Chi mantiene un'integrazione tra software

Di solito un'integrazione tra software la mantiene chi l'ha costruita, e conviene scrivere nell'accordo come. Si rompe per motivi che non dipendono da te: una versione che si spegne, una chiave che scade, un campo che cambia nome dall'altra parte.

Un connettore pronto lo aggiorna chi lo vende: prima di sceglierlo guarda quando è uscito l'ultimo aggiornamento. Un flusso di Make, Zapier o n8n lo ripara chi l'ha disegnato (vedi n8n, Make, Zapier o sviluppo su misura). Un collegamento su misura rientra nell'assistenza e manutenzione del software.

A chi costruisce il collegamento conviene chiedere:

  • Un registro di ogni scambio, consultabile anche da voi.
  • Avvisi chiari a chi deve intervenire, con il numero dell'ordine o della fattura.
  • Chi segue le nuove versioni e chi rinnova chiavi e autorizzazioni.
  • Un documento che dice cosa passa, in che verso e quale programma comanda su ogni dato.
  • Un controllo periodico che confronta i dati dei due programmi.

Quanto costa un'integrazione tramite API

Il costo di un'integrazione tramite API ha tre parti: costruirla, pagare i servizi di terzi che usa, mantenerla nel tempo.

La costruzione dipende da quanti programmi si collegano, in quante direzioni e con quante regole: clienti da riconoscere, codici da far corrispondere, eccezioni. Pesa anche la qualità dell'API dall'altra parte.

I costi di terzi si dimenticano spesso. Odoo, secondo la sua pagina dei prezzi, comprende l'API esterna solo nel piano Custom; sulla WhatsApp Business Platform Meta fa pagare i messaggi a modello consegnati e, dal 1° ottobre 2026, anche le risposte oltre le prime 1.000 al mese per numero, come spiega la guida sulla WhatsApp Business API.

La manutenzione comprende server, adeguamenti alle nuove versioni e controllo degli errori. Dopo l'analisi ricevi una proposta scritta con costi, tempi e formula (a corpo, a canone o mista, vedi formule e costi), con i costi dei fornitori indicati a parte. Come lavoriamo è nella pagina sulle integrazioni tra software.

Se i dati da passare sono pochi e cambiano di rado, un'esportazione fatta a mano una volta al mese può bastare: in quel caso te lo diciamo nella prima chiamata.

Domande frequenti

Come faccio a sapere se il mio gestionale ha le API?

Cerca nel sito del produttore una sezione per sviluppatori, o le parole API, web service e REST nel manuale. Altrimenti chiedi al rivenditore se l'API esiste per la tua versione, se è compresa nella licenza e se la documentazione è pubblica. Nell'analisi lo verifichiamo noi, perché da quelle risposte dipendono tempi e costi.

Un collegamento via API mette a rischio i dati dei clienti?

Dipende da dove passano i dati. In un collegamento diretto vanno da un programma all'altro, su una connessione che deve essere cifrata; con una piattaforma intermedia, come uno strumento no-code, passano anche dai suoi server, e va verificato dove stanno. Se il fornitore che gestisce il collegamento tratta dati personali per conto tuo, l'art. 28 del GDPR chiede che quel trattamento sia regolato da un contratto o da un altro atto giuridico. Cosa deve contenere lo spiega la guida su fornitore di software, GDPR e NIS2.

Quanto tempo serve per collegare due programmi via API?

Tra due sistemi, di solito alcune settimane. Il tempo va meno nel codice che nelle decisioni: quale programma comanda su ogni dato, come si riconoscono i clienti già presenti, cosa fare con le eccezioni. Un ambiente di prova accorcia i tempi; le prove sui dati veri non si saltano.

Cosa succede se il produttore chiude l'API o la fa pagare?

Di solito il produttore lo annuncia con una data. Se l'API diventa a pagamento si confronta il nuovo costo con le alternative; se chiude, si passa allo scambio di file o si valuta di cambiare programma. Per questo teniamo le regole del collegamento in un livello separato: se cambia un lato, si rifà solo quello.

Con le API posso portare via tutti i miei dati da un programma?

Spesso sì, insieme alle esportazioni in CSV o Excel. Con molti dati l'estrazione si fa a blocchi, dentro i limiti di richieste, a volte in più notti: conviene farla prima che scada il contratto con il vecchio fornitore. Come si organizza il passaggio lo spiega la pagina sulla migrazione dei gestionali.

Che differenza c'è tra API e API REST?

API indica qualunque porta tra programmi; REST è uno stile architetturale per le web API, quelle che passano dalla rete. In un'API REST ogni chiamata API va a un indirizzo, come quello di un ordine. Altre API seguono stili diversi.

Hai un'altra domanda? Scrivici · +39 375 669 3055

Raccontaci cosa fate ancora a mano

Una breve chiamata, senza impegno. Se un software standard vi basta, ve lo diciamo.

Società
Automatia S.r.l.Gestionali su misura, automazioni, integrazioni tra sistemi.
Operativi
24 ore su 24, 7 giorni su 7
Lingue
Italiano, inglese o russo
Parliamo del progetto
  1. Ci scrivi
  2. Prima valutazione
  3. Breve chiamata
Scrivici su WhatsApp, al +39 375 669 3055 (si apre in una nuova scheda)