Integrare CRM e Fatture in Cloud: vTiger, Zoho e n8n

Sì, vTiger e Zoho CRM si possono integrare con Fatture in Cloud: si usano le API v2 ufficiali di Fatture in Cloud e, per orchestrare i passaggi, un motore di automazione come n8n oppure un piccolo connettore su misura. Le automazioni più utili sono tre: il cliente creato nel CRM diventa anagrafica in Fatture in Cloud, il preventivo accettato diventa fattura, lo stato dei pagamenti torna nella scheda cliente. Vediamo come funziona, cosa si può fare davvero e dove sono i limiti.

Perché collegare il CRM al software di fatturazione

Senza integrazione, i dati del cliente vengono scritti due volte: dal commerciale nel CRM e dall'amministrazione in Fatture in Cloud. Ogni doppio inserimento è un'occasione per errori su partita IVA, codice destinatario o indirizzo PEC, che poi emergono quando la fattura elettronica viene scartata.

C'è anche un problema di visibilità. Il commerciale che apre la scheda nel CRM non sa se il cliente ha pagato l'ultima fattura, e l'amministrazione non sa quali offerte sono in chiusura. Un'integrazione ben fatta porta le informazioni dove servono, senza dare a tutti l'accesso a tutto.

Cosa offrono le API di Fatture in Cloud

Fatture in Cloud mette a disposizione un portale sviluppatori con API REST v2, SDK, specifica OpenAPI e collezione Postman. Secondo la documentazione, le API espongono la maggior parte delle funzioni disponibili nell'interfaccia web: clienti, fornitori, prodotti, documenti emessi e ricevuti, fatture elettroniche.

Autenticazione: OAuth 2.0 o token manuale

La guida all'autenticazione prevede tre metodi. Il flusso OAuth 2.0 Authorization Code è quello consigliato e richiede un backend che custodisca il client secret; il refresh token scade dopo un anno dall'ultimo utilizzo. Il token manuale, generato dall'utente nel pannello, non scade ed è indicato per app private usate su un solo account o pochi account noti.

Per un'integrazione aziendale interna, tra il tuo CRM e il tuo account Fatture in Cloud, il token manuale con permessi limitati è spesso sufficiente. Va però trattato come una password: conservato in un gestore di segreti e ruotato periodicamente, come suggerisce la stessa documentazione.

Webhook: eventi in tempo reale

Dal 24 aprile 2025 i webhook di Fatture in Cloud sono disponibili per tutti gli utenti. L'elenco degli eventi copre creazione, modifica ed eliminazione di fatture, preventivi, proforma, note di credito, clienti e fornitori, oltre all'aggiornamento di stato delle fatture elettroniche. Le notifiche seguono il formato CloudEvents.

Cosa si può automatizzare tra CRM e Fatture in Cloud

1. Cliente nel CRM → anagrafica in Fatture in Cloud

Quando un'opportunità passa a «vinta», l'automazione crea o aggiorna il cliente in Fatture in Cloud con ragione sociale, partita IVA, codice fiscale, codice destinatario SDI e PEC. L'identificativo restituito da Fatture in Cloud viene salvato in un campo del CRM, così i passaggi successivi lavorano sullo stesso record ed evitano duplicati.

2. Preventivo accettato → fattura

Ci sono due strade. Se il preventivo nasce nel CRM, l'automazione crea direttamente la fattura in Fatture in Cloud con righe, aliquote IVA e scadenze di pagamento. Se il preventivo esiste già in Fatture in Cloud, l'API di trasformazione dei documenti restituisce il corpo della fattura precompilato, che poi va salvato con una seconda chiamata.

Un dettaglio che conta: secondo la guida alla creazione delle fatture, collegare la fattura a un cliente esistente tramite ID non copia automaticamente i dati anagrafici nel documento. L'integrazione deve quindi compilare i campi del cliente in modo esplicito.

3. Invio allo SDI e stato della fattura elettronica

La fattura elettronica si verifica con un controllo dell'XML e si invia allo SDI con un metodo dedicato, come descritto nella guida alla gestione delle fatture elettroniche. Lo stato (inviata, in elaborazione, scartata, accettata) può tornare nel CRM: il webhook segnala il cambio di stato, poi l'integrazione legge il dettaglio del documento.

4. Stato dei pagamenti nel CRM

Ogni fattura ha un elenco di rate con importo, scadenza e stato: pagato, non pagato o stornato. Riportando queste informazioni nella scheda cliente del CRM, il commerciale vede gli insoluti prima di proporre un nuovo ordine e l'amministrazione può avviare solleciti automatici.

vTiger, Zoho e n8n: come si collegano i pezzi

• vTiger: espone le API REST webservice per creare, leggere, aggiornare e interrogare i record, con un'operazione di sync per ottenere solo le modifiche da una certa data.
• Zoho CRM: può inviare dati verso un URL esterno tramite webhook collegati alle regole di workflow, con limiti di chiamate giornaliere che dipendono dall'edizione.
• n8n: ha un nodo nativo per Zoho CRM; per Fatture in Cloud e vTiger si usa il nodo HTTP Request con credenziali generiche, anche OAuth2.

Con n8n self-hosted i dati restano su un server che controlli tu e i flussi sono visibili e modificabili. Se vuoi approfondire lo strumento, trovi il nostro servizio di automazioni con n8n; quando serve un connettore scritto in codice, con code di retry e log dedicati, lo sviluppiamo nell'ambito dell'integrazione API.

Un esempio di flusso: da trattativa vinta a fattura

Per rendere concreto il discorso, ecco come impostiamo di solito il flusso più richiesto. L'esempio usa Zoho CRM e n8n, ma la logica è la stessa con vTiger: cambia solo il modo in cui il CRM segnala l'evento.

• Evento nel CRM: la trattativa passa allo stato «vinta» e una regola di workflow invia un webhook a n8n con l'ID del record.
• Lettura dei dati: n8n recupera dal CRM azienda, contatto di fatturazione, righe del preventivo e condizioni di pagamento.
• Controlli preliminari: se mancano partita IVA, codice destinatario o PEC, il flusso si ferma e avvisa il commerciale invece di creare un documento incompleto.
• Anagrafica: n8n cerca il cliente in Fatture in Cloud; se non esiste lo crea e salva l'ID nel CRM.
• Documento: viene creata la fattura, o una proforma se l'azienda preferisce un controllo umano prima dell'emissione.
• Ritorno nel CRM: numero e link del documento vengono scritti nella trattativa, con la data di emissione.

Molte aziende scelgono di fermarsi alla proforma o alla bozza: l'amministrazione controlla e invia allo SDI con un clic. È un buon compromesso all'inizio, perché automatizza il lavoro ripetitivo senza togliere il controllo su ciò che parte verso l'Agenzia delle Entrate.

Il flusso inverso, dai pagamenti al CRM, funziona allo stesso modo. Un webhook su modifica della fattura avvisa n8n, che legge lo stato delle rate e aggiorna un campo nella scheda cliente; da lì il CRM può assegnare un'attività di sollecito al commerciale di riferimento.

Limiti da conoscere prima di partire

• Quote API: Fatture in Cloud applica 1.000 richieste all'ora per coppia azienda-app, 40.000 al mese e 300 richieste ogni 5 minuti per azienda, come indicato nella pagina limiti e quote. Una sincronizzazione massiva mal progettata li esaurisce in fretta.
• Gestione degli errori: superate le quote, l'API risponde con errore e un header Retry-After; il flusso deve attendere e riprovare, non perdere il dato.
• Webhook in scadenza: se l'endpoint risponde con errori, la sottoscrizione riceve una data di scadenza a 10 giorni dal primo errore, come spiega la pagina sulla scadenza delle sottoscrizioni.
• XML esterni: tramite API non si possono inviare allo SDI fatture XML generate fuori da Fatture in Cloud.
• Regola di verità: va deciso quale sistema è il riferimento per ogni dato, altrimenti due modifiche contemporanee si sovrascrivono.

Sicurezza e dati personali

Un'integrazione tra CRM e fatturazione muove dati fiscali e personali, quindi va progettata con criterio. Le regole che applichiamo sono poche e rigide: token con i soli permessi necessari, segreti fuori dal codice, comunicazioni solo in HTTPS, endpoint dei webhook non indovinabili e verificati.

Teniamo anche un log delle operazioni senza copiare dati sensibili in chiaro, così un errore si ricostruisce senza creare un nuovo archivio di dati personali. Il token manuale, poiché non scade, va revocato subito se un collaboratore lascia l'azienda o se il server viene dismesso.

Come impostiamo un progetto di integrazione

• Mappatura dei dati: quali campi del CRM corrispondono a quali campi di Fatture in Cloud, e chi è il riferimento per ciascuno.
• Scelta dello strumento: flusso n8n, connettore su misura o combinazione dei due.
• Sviluppo su account di prova: test con documenti fittizi, mai sui dati reali al primo giro.
• Gestione eccezioni: notifiche quando un documento non passa, con il motivo leggibile da chi deve intervenire.
• Avvio e monitoraggio: controllo delle quote e dei log nelle prime settimane.

Se il tuo vTiger è datato, conviene verificarlo prima di integrarlo: un CRM su una versione di PHP non più supportata è una base fragile. Ne parliamo nella guida su come aggiornare vTiger e PHP. Per una visione d'insieme del servizio trovi la pagina CRM vTiger e Zoho.