Sincronizzare fatture con Zoho tramite il nodo n8n dedicato

Integrazionin8nzoho2026-07-24

Obiettivo

Creare automaticamente fatture (TD01) e note di credito (TD04) su Zoho Invoice o Zoho Books a partire dai documenti generati da POP, usando il pacchetto npm ufficiale n8n-nodes-pop-zoho su una tua istanza n8n self-hosted.

Questo è un pacchetto diverso e distinto da n8n-nodes-pop (che gestisce SdI/PEPPOL/VIES e, tramite l’operazione Sync Document to Zoho, anche una sincronizzazione Zoho nativa più semplice — vedi n8n) — installali entrambi solo se ti servono entrambe le funzionalità, o preferisci questo percorso se vuoi che la connessione OAuth con Zoho viva direttamente in n8n.

Nota sull’installazione: il pacchetto è pubblicato su npm ma non è approvato/listato sul registro ufficiale dei Community Nodes di n8n — il pulsante Settings → Community Nodes → Install di n8n non lo troverà. Va installato manualmente (vedi sotto), e per questo non è utilizzabile su n8n Cloud, solo su un’istanza self-hosted.

Prerequisiti

Un’istanza n8n self-hosted (v2+), Node.js 18+. Non disponibile su n8n Cloud (vedi nota sopra).
Un account Zoho Invoice o Zoho Books, con un’app OAuth2 creata sullo Zoho API Console della tua regione e le aliquote IVA configurate in Zoho (una voce per ogni percentuale usata nei payload POP).
Un account POP con il connector n8n abilitato e un webhook già registrato nel pannello Webhooks.

Passi

Installazione manuale (l’installer “Community Nodes” di n8n non trova questo pacchetto):

git clone https://github.com/getpopapi/n8n-nodes-pop-zoho.git
cd n8n-nodes-pop-zoho
npm install
npm run build
ln -s $(pwd)/dist/nodes/PopZohoInvoice/PopZohoInvoice.node.js ~/.n8n/custom/PopZohoInvoice.node.js
ln -s $(pwd)/dist/credentials/ZohoInvoiceOAuth2Api.credentials.js ~/.n8n/custom/ZohoInvoiceOAuth2Api.credentials.js
ln -s $(pwd)/dist/nodes/PopZohoInvoice/pop-zoho-invoice.svg ~/.n8n/custom/pop-zoho-invoice.svg
n8n start

Su Zoho API Console, crea una Server-based Application con redirect URI https://<la-tua-istanza-n8n>/rest/oauth2-credential/callback.
In n8n, crea una credenziale Zoho OAuth2 (Invoice / Books): prodotto, regione, Organization ID (da Zoho → Impostazioni → Profilo organizzazione), Client ID/Secret dall’app appena creata. Clicca Connect per completare l’autorizzazione.
Crea il workflow: Webhook node (Authentication: None, Respond: Using 'Respond to Webhook' Node, path webhook/zoho) → nodo POP → Zoho → Respond to Webhook.
Copia l’URL di produzione del Webhook node e registralo nel pannello Webhooks di POP, impostando il campo Connector su “n8n Connector — Zoho”.
Nel nodo POP → Zoho, imposta la License Key (sempre la chiave di default dell’account, da popapi.io → Account → API → API Key (default) — mai una chiave specifica per Shopify/WooCommerce) e clicca il pulsante di refresh per recuperare la chiave pubblica RSA.

Verifica

Invia una richiesta con environment: "sandbox" (o attiva Dry Run sul nodo): la risposta include dry_run: true e il corpo zoho_body che verrebbe inviato a Zoho, senza creare nulla realmente e senza consumare quota.

Da sapere

Il campo Invoice Status del nodo controlla lo stato della fattura creata su Zoho: se impostato su Sent, il nodo esegue automaticamente anche la transizione di stato richiesta da Zoho dopo la creazione, invece di lasciare la fattura in draft.

Errori comuni

auth_error — la License Key nel nodo non è quella di default: POP firma sempre con la chiave di default indipendentemente dalla piattaforma che ha generato il documento.
tax_not_found — una delle aliquote usate nei tuoi payload POP non è configurata in Zoho → Impostazioni → Tasse: aggiungila.
contact_ambiguous — più contatti Zoho corrispondono allo stesso VAT/email/nome: risolvi il duplicato in Zoho prima di riprovare.
unsupported_doc_type — solo TD01 (fattura) e TD04 (nota di credito) sono supportati in v1.

Configurazione correlata

Per il meccanismo di instradamento generico usato da questo nodo (route /connector/zoho, firma HMAC+RSA, codici errore lato POP), vedi api/connectors. Per scegliere tra questo percorso e gli altri canali disponibili, vedi choosing-an-invoicing-integration.