Integrare servizi esterni e API in un'app creata con l'AI

Collegare la tua app creata con l'AI a servizi esterni (un calendario, WhatsApp, un CRM, il software di fatturazione elettronica) è spesso il passo che la trasforma da prototipo a strumento di lavoro. Si fa tramite le API, e quasi sempre si può fare. Ma è anche il punto in cui le app generate con Lovable, Bolt o Cursor si rompono più facilmente: chiavi esposte, chiamate fatte dal posto sbagliato, limiti di utilizzo ignorati. Qui ti spieghiamo come funziona un'integrazione, cosa serve per i servizi più richiesti e come evitare gli errori più comuni.

Cos'è un'API, in parole semplici

Un'API è uno sportello che un servizio mette a disposizione di altri programmi. La tua app si presenta allo sportello, fa una richiesta precisa («crea questo appuntamento», «invia questo messaggio») e riceve una risposta. Per farsi riconoscere usa una chiave API, una specie di tesserino, oppure un accesso autorizzato dall'utente. Quest'ultimo si chiama OAuth: è la schermata del tipo «Consenti a questa app di accedere al tuo calendario».

A volte la comunicazione va nel verso opposto: è il servizio esterno ad avvisare la tua app quando succede qualcosa, come un nuovo messaggio o un pagamento ricevuto. Questa notifica automatica si chiama webhook. È come un campanello: invece di andare alla porta ogni minuto a vedere se è arrivato qualcuno, aspetti che suoni.

Perché le integrazioni fatte con l'AI si rompono

Gli strumenti AI scrivono volentieri la chiamata a un'API, ma tendono a trascurare il contesto. I problemi più frequenti sono questi:

• La chiamata parte dal browser. Il frontend, la parte dell'app che gira nel browser, è visibile a chiunque. Se la chiave API sta lì, chiunque può copiarla e usarla a tue spese. Ne parliamo nella guida sulle chiavi API esposte nel frontend.
• Il servizio rifiuta le richieste dal browser. Molte API non accettano chiamate dirette da un sito: il browser blocca la risposta e in console compare un messaggio come Access to fetch at '...' has been blocked by CORS policy. Ti spieghiamo cosa significa nella guida sull'errore CORS.
• La chiave c'è in anteprima ma non online. Nell'ambiente pubblicato la variabile non è impostata e il servizio risponde 401 Unauthorized.
• Nessuna gestione dei limiti. Ogni API ha un numero massimo di richieste per minuto o per giorno. Superato quello arriva 429 Too Many Requests, e la funzione smette di andare finché il limite non si azzera.
• Webhook che nessuno verifica. Se l'indirizzo che riceve le notifiche accetta qualunque messaggio, chiunque può inviarne di false.
• Ambiente di prova e ambiente reale mescolati. Molti servizi hanno chiavi di test e chiavi reali separate. Usare le une con i dati delle altre produce errori difficili da capire.

Cosa serve per i servizi più richiesti

Ogni servizio ha le sue regole. Questa tabella riassume cosa aspettarti; i dettagli cambiano spesso, quindi verifica sempre la documentazione ufficiale.

Calendari

Per leggere o scrivere nel calendario di un utente serve il suo permesso esplicito tramite OAuth. Con Google, finché l'app non è verificata, chi si collega vede un avviso che segnala un'app non verificata (in inglese Google hasn't verified this app) e il numero di nuovi utenti che possono autorizzarla è limitato. Chiedi solo i permessi che ti servono davvero: è più rispettoso per l'utente e semplifica la verifica.

WhatsApp

L'app WhatsApp che usi sul telefono non si collega alle app esterne. Serve la piattaforma WhatsApp Business di Meta, cioè la versione per sviluppatori. Quando un cliente ti scrive si apre una finestra di 24 ore in cui puoi rispondere liberamente; per scrivere per primo, o dopo quella finestra, servono modelli di messaggio approvati da Meta. Alcuni tipi di messaggio sono a pagamento, con tariffe che dipendono dalla categoria e dal paese.

CRM

Collegare un CRM di solito significa sincronizzare contatti o trattative. Il lavoro vero non è la chiamata in sé, ma decidere quale campo della tua app corrisponde a quale campo del CRM e cosa fare se un contatto esiste già. Senza queste regole ti ritrovi con doppioni ovunque.

Fatturazione elettronica

In Italia le fatture elettroniche passano dal Sistema di Interscambio (SdI) dell'Agenzia delle Entrate. Di solito la tua app non parla direttamente con lo SdI: si appoggia a un software di fatturazione o a un intermediario che offre un'API. La parte tecnica è fattibile; quella fiscale (cosa fatturare, quando, con quale regime) va decisa con il tuo commercialista. Se l'incasso passa da Stripe, trovi i principi nella guida su come aggiungere pagamenti Stripe.

Come capire dove si blocca la tua integrazione

Se l'integrazione non funziona, apri gli strumenti per sviluppatori del browser (F12), vai nella scheda Rete (Network) e ripeti l'azione. Guarda il codice di risposta della richiesta:

• 401 Unauthorized o 403 Forbidden: la chiave manca, è sbagliata o non ha i permessi giusti;
• 404 Not Found: l'indirizzo dell'API è sbagliato o la risorsa non esiste;
• 429 Too Many Requests: hai superato i limiti di utilizzo;
• errori 500 o 503: il problema è dall'altra parte, oppure nella tua funzione backend;
• nessuna risposta e un errore CORS in console: la chiamata parte dal browser e va spostata sul server.

Controlla anche i log del backend, cioè la parte dell'app che gira sul server (per esempio le funzioni di Supabase, di Lovable Cloud o del tuo hosting). Spesso lì trovi il messaggio di errore completo restituito dal servizio esterno.

Come integrare un servizio esterno in modo solido

1. Leggi la documentazione del servizio prima di chiedere all'AI di scrivere codice: limiti, costi, tipo di accesso, ambiente di prova.
2. Parti dall'ambiente di test, se il servizio ne offre uno.
3. Fai partire le chiamate dal backend, per esempio con una edge function: un piccolo pezzo di codice che gira sul server del fornitore, non nel browser.
4. Salva le chiavi come variabili d'ambiente o secret, mai scritte nel codice. Se non ti è chiaro come, leggi la guida sulle variabili d'ambiente e le chiavi API online.
5. Verifica i webhook in arrivo con la firma o il segreto previsti dal servizio, e gestisci le notifiche duplicate.
6. Gestisci errori e limiti: messaggi chiari all'utente, nuovi tentativi distanziati nel tempo, nessun ciclo infinito di richieste.
7. Imposta avvisi di spesa sui servizi a consumo, se il fornitore li offre.
8. Tieni un registro delle chiamate fallite, così sai cosa è successo quando qualcosa non arriva a destinazione.

Un prompt utile da dare all'AI: «Sposta tutte le chiamate a [nome del servizio] in una funzione backend, leggi la chiave da una variabile d'ambiente, gestisci gli errori 401, 429 e 500 e non esporre nulla nel frontend». Poi controlla che lo abbia fatto davvero, ripetendo le verifiche nella scheda Rete.

Quando conviene farti aiutare

Un'integrazione semplice, come leggere dati pubblici da un'API, puoi gestirla da solo seguendo questi passi. Conviene farsi affiancare quando di mezzo ci sono dati personali, soldi o obblighi fiscali, quando servono OAuth e verifiche dell'app, o quando l'integrazione deve funzionare ogni giorno senza che tu debba controllarla.

Di solito partiamo da cosa deve succedere nel concreto e scegliamo il modo più semplice per farlo, a volte con meno codice di quanto pensi. Prenota una call gratuita: in 20 minuti capiamo insieme se e come collegare il servizio che ti serve.