Come integrare una API esterna in un progetto Lovable

Nella lezione precedente abbiamo visto cos'è una API e perché conta anche per chi non scrive codice. Questa lezione va nel pratico: come si integra davvero un'API esterna in un progetto Lovable, cosa succede alla chiave segreta che quasi ogni servizio richiede, e perché questo passaggio è pensato per restare al sicuro anche se tu non sai nulla di sicurezza informatica.

## In breve

Lovable gestisce l'integrazione di un'API esterna in tre modi diversi, a seconda del caso: un connettore pronto dal catalogo, una chiamata diretta se l'API non richiede autenticazione, oppure, per un'API autenticata non presente nel catalogo, un'integrazione "any API" in cui la chiave viene salvata in modo sicuro e usata da una funzione lato server che Lovable crea per te. In tutti e tre i casi, secondo la documentazione ufficiale, tu descrivi cosa vuoi collegare in linguaggio naturale: è Lovable a scrivere il codice dell'integrazione.

Che cos'è (e cosa NON è)

Integrare una API in Lovable significa collegare il tuo progetto a un servizio esterno affinché possa chiedergli dati o funzionalità, un pagamento, un'email, una posizione su mappa, e usare la risposta dentro l'app. Non significa scrivere tu il codice che fa questa chiamata: resti nel linguaggio naturale, descrivendo cosa ti serve.

Non è nemmeno, e questo è il punto più importante di tutta la lezione, mettere una chiave API scritta a vista nel codice del frontend o incollata direttamente in chat come se fosse un dettaglio qualunque. Le FAQ ufficiali di Lovable sono nette: "Non inserire mai le tue chiavi API direttamente in Lovable." Le chiavi vanno sempre gestite tramite i secrets del backend integrato (Cloud) o di Supabase, mai altrove.

Come funziona

Quando chiedi a Lovable di integrare un servizio esterno, il primo passo è controllare se esiste già come connettore nel catalogo. Slack, Notion, Google Workspace, e anche gli stessi Stripe e Resend che vedremo nella prossima lezione compaiono spesso lì. In quel caso, collegarlo è più veloce: Lovable gestisce le credenziali per te, e non devi conoscere i dettagli tecnici dell'API sottostante.

Se il servizio non è nel catalogo, entra in gioco l'integrazione diretta, che si comporta in due modi diversi:

### API senza autenticazione

Se il servizio non richiede una chiave, non serve nessuna configurazione: basta chiedere a Lovable di integrarlo, descrivendo l'endpoint. L'app chiama l'API direttamente.

API con autenticazione (la maggioranza dei casi seri)

Qui Lovable ti chiede di abilitare il backend integrato (Cloud), se non è già attivo, e ti propone di inserire la chiave in Cloud → Secrets. Da quel momento, la chiave non è mai visibile nel codice del progetto: viene letta solo da una edge function, una piccola funzione che gira lato server, non nel browser di chi visita il sito, che Lovable crea apposta per fare da tramite tra la tua app e il servizio esterno. La tua app chiama la edge function, la edge function aggiunge la chiave e inoltra la richiesta al servizio esterno, e la risposta torna indietro allo stesso modo. La chiave non transita mai per il browser dell'utente.

Per far funzionare bene questa integrazione, la documentazione consiglia di fornire a Lovable, nel prompt, alcuni dettagli precisi: l'indirizzo dell'endpoint e il metodo HTTP, il tipo di autenticazione richiesta (chiave in un header, in un parametro nell'URL, token Bearer, OAuth), gli header necessari, un esempio di richiesta e risposta, e, quando disponibile, il link alla documentazione ufficiale del servizio o la sua specifica OpenAPI.

## Perché conta

Il motivo per cui questo processo è strutturato così, e non semplicemente "incolla la chiave dove serve", è la sicurezza: una chiave API visibile nel codice frontend è visibile a chiunque apra gli strumenti sviluppatore del browser mentre naviga il tuo sito. Chiunque potrebbe copiarla e usarla al posto tuo, con conseguenze che vanno da un abuso del servizio a costi non voluti sul tuo account. Il meccanismo di secrets più edge function esiste apposta per evitare questo scenario, senza che tu debba capire nulla di crittografia o di configurazione server: lo gestisce Lovable, ma solo se segui il percorso previsto (Secrets, non il codice o la chat).

C'è anche un motivo pratico: descrivere bene l'API prima di chiederne l'integrazione, endpoint, autenticazione, formato di richiesta e risposta, riduce i cicli di correzione, esattamente come una descrizione vaga di un'idea produce un prototipo generico (ne abbiamo parlato nel modulo precedente). Più il prompt è specifico su questi dettagli tecnici, meno tentativi servono per arrivare a un'integrazione che funziona.

## Esempio lampante

### Contesto ipotetico

un piccolo negozio online di candele artigianali vuole calcolare in automatico il costo di spedizione chiamando l'API di un corriere.

INPUT. La richiesta iniziale: "Voglio calcolare il costo di spedizione in base al peso del pacco e alla destinazione."

ANALISI. Il servizio del corriere non è nel catalogo dei connettori Lovable, quindi serve un'integrazione diretta. La sua API richiede una chiave segreta per autenticare ogni richiesta: è un caso di API autenticata.

DECISIONE. Prima di chiedere l'integrazione, il negozio recupera dalla documentazione ufficiale del corriere: l'indirizzo dell'endpoint per calcolare le tariffe, il fatto che la chiave va passata in un header, e un esempio di risposta. Con queste informazioni, chiede a Lovable di integrare il servizio, descrivendo esattamente questi dettagli.

OUTPUT. Lovable abilita il backend integrato, chiede di inserire la chiave del corriere in Cloud → Secrets, e crea una edge function che riceve peso e destinazione dal modulo dell'ordine, li inoltra al corriere insieme alla chiave (mai visibile al cliente), e restituisce il costo di spedizione da mostrare nel carrello.

Come farlo

1. Controlla prima il catalogo dei Connettori di Lovable: se il servizio è già lì, collegarlo è più semplice e le credenziali sono già gestite.
2. Se non c'è, raccogli dalla documentazione ufficiale del servizio: indirizzo dell'endpoint, metodo HTTP, tipo di autenticazione, header richiesti, un esempio di richiesta e risposta.
3. Descrivi tutto questo a Lovable in un prompt, includendo il link alla documentazione se disponibile.
4. Se il servizio richiede una chiave, abilita il backend integrato (Cloud) quando Lovable te lo propone.
5. Inserisci la chiave solo quando Lovable te la chiede tramite il modulo sicuro in Cloud → Secrets, mai nel prompt di chat né nel codice.
6. Verifica nella preview che l'integrazione funzioni davvero: controlla i log della edge function se qualcosa non torna, invece di ripetere lo stesso prompt di correzione più volte.
7. Testa anche i casi di errore, chiave sbagliata, servizio momentaneamente non disponibile, non solo il caso in cui tutto va bene.

## Errori comuni

Incollare la chiave API nel messaggio di chat o direttamente nel codice

È l'errore che le FAQ ufficiali di Lovable segnalano in modo esplicito: le chiavi vanno sempre nei Secrets, mai altrove.

Chiedere l'integrazione senza aver letto la documentazione ufficiale del servizio. Affidarsi solo a supposizioni su come funziona un'API esterna porta quasi sempre a più cicli di correzione di quanti servirebbero partendo da un prompt con i dettagli tecnici corretti.

Confondere le chiavi segrete con le variabili VITE_. Nei progetti Lovable, i valori che devono restare privati vanno nei Secrets; i valori pensati per essere pubblici e usati lato browser (come alcune configurazioni del backend integrato) seguono un percorso diverso. Se non sei sicuro di quale caso si applica, lascialo decidere a Lovable descrivendo semplicemente cosa deve restare segreto.

Non controllare se un servizio richiede davvero autenticazione prima di descriverlo come "semplice". Alcune API pubbliche non richiedono chiavi, ma sono l'eccezione più che la regola tra i servizi seri: dare per scontato che non ne serva una porta a un prompt incompleto.

Quando questo lavoro conta meno

Se il servizio che ti serve è già un connettore pronto nel catalogo di Lovable, non devi gestire manualmente endpoint, autenticazione o secrets: la connessione è già configurata, e questo intero processo tecnico resta invisibile. Lo stesso vale per le funzionalità coperte dal backend integrato e dall'intelligenza artificiale nativa di Lovable, che non richiedono nessuna chiave esterna. Questo lavoro di integrazione manuale conta soprattutto quando il servizio che ti serve non è nel catalogo e richiede autenticazione.

## In sintesi

Integrare una API esterna in Lovable segue un percorso pensato per restare sicuro anche se non sai nulla di sicurezza: connettore pronto quando esiste, chiamata diretta se non serve autenticazione, oppure secrets più edge function quando serve una chiave protetta. La regola che vale sempre, in ogni caso: la chiave non va mai scritta a vista, né in chat né nel codice, solo nel modulo sicuro che Lovable ti propone.

## Cosa imparare dopo

Con il meccanismo di integrazione chiaro, resta da orientarsi tra i servizi che si incontrano più spesso in un progetto reale. Nella prossima lezione vediamo le API più comuni per iniziare: pagamenti, email, AI, mappe.

---

Vuoi provarlo?

Prova Lovable →

Link di affiliazione: se ti iscrivi da qui, ricevo una piccola commissione, a te non cambia nulla.