Collegare POP a n8n

Obiettivo

Generare fatture SdI, PEPPOL, KSeF o ZUGFeRD, verificarne lo stato e validare partite IVA UE dentro un workflow n8n, senza chiamare manualmente l’API REST.

Prerequisiti

• Un’istanza n8n (cloud o self-hosted).
• Una license_key POP valida (vedi get-your-license-key).

Cosa offre il nodo POP

Il nodo ufficiale (n8n-nodes-pop) espone due risorse:

• Invoice — Create SdI Invoice (XML), Create Peppol Invoice (UBL), Create KSeF Invoice (FA(3) XML), Create ZUGFeRD Invoice, Get Invoice Status, Get Peppol Document, Verify SdI Document, Sync Document to Zoho (sincronizza una fattura o nota di credito su Zoho Books/Invoice tramite il connettore nativo POP — richiede che Zoho sia già collegato sull’account POP, nessun piano minimo; verifica opzionale dello stato del connettore prima dell’invio).
• VAT Validation — Validate VAT Number, tramite il servizio VIES della UE (non l’API POP).

Create KSeF Invoice condivide lo stesso form d’invio degli altri operatori di creazione fattura, più l’opzione Submit via KSeF Provider (Yes/No) per inviare subito il documento al provider KSeF invece di generare solo l’XML localmente — equivalente a impostare integration.use = ksef-via-pop sulla richiesta REST sottostante (vedi api/ksef). Create ZUGFeRD Invoice genera solo il pacchetto ZUGFeRD/Factur-X (nessuna opzione di invio: l’invio è sempre gestito da POP internamente, vedi api/zugferd).

Non copre PDF: per quel dominio usa l’API REST direttamente (vedi api/pdf).

Per Zoho esistono due percorsi diversi, non equivalenti: Sync Document to Zoho qui sopra (usa il connettore Zoho già collegato sull’account POP, nessuna configurazione OAuth separata da fare in n8n) oppure il pacchetto dedicato n8n-zoho (self-hosted, credenziali Zoho OAuth configurate direttamente in n8n, instradamento tramite webhook firmato — installabile solo via npm, non è approvato/listato sul registro ufficiale dei Community Nodes di n8n). Scegli in base a dove vuoi che viva la connessione OAuth con Zoho.

Passi

1. Installa il nodo ufficiale: https://n8n.io/integrations/pop/.
2. Crea una credenziale POP API con la tua license_key (campo unico, inviato come header X-API-Key); n8n la verifica chiamando GET /account-profile.
3. Aggiungi il nodo POP, scegli risorsa e operazione (es. Invoice → Create SdI Invoice).
4. Scegli la modalità di input: Passthrough (usa il JSON in arrivo così com’è), Form Fields (compila i campi nel nodo), JSON, o Raw.
5. Se vuoi che POP invii subito il documento (non solo generarlo), attiva Send Invoice: aggiunge automaticamente l’integrazione sdi-via-pop o peppol-via-pop alla richiesta.

Verifica

Esegui il workflow una volta e controlla l’output del nodo: in caso di successo restituisce XML/JSON a seconda dell’operazione; in caso di errore, un NodeApiError con URL, status HTTP e corpo della risposta — utile per capire subito quale campo ha fallito la validazione.

Errori comuni

• Nodo non autenticato — la license_key nella credenziale non è valida o è stata rigenerata: aggiornala da Account > API.
• Campi mancanti nel payload mappato — stessa validazione dell’API REST sottostante: controlla la guida della route specifica (es. api/sdi) per i campi richiesti.
• Sconto riga non applicato — se abiliti “Discount” su una riga d’ordine, il campo “Discount Percent” è obbligatorio: senza di esso l’operazione fallisce in validazione.
• Validazione VIES lenta o fallita — il nodo Validate VAT ritenta automaticamente fino a 5 volte sui guasti temporanei del servizio VIES (MS_UNAVAILABLE, TIMEOUT, ecc.); un fallimento persistente dopo i retry indica che il servizio VIES è irraggiungibile, non un problema di configurazione POP.
• Il workflow si interrompe su un singolo errore — se vuoi che n8n continui con gli item successivi invece di fermare il workflow, abilita “Continue On Fail” sul nodo: l’errore viene allegato all’item in output invece di interrompere l’esecuzione.

Configurazione correlata

Per il percorso Zoho alternativo (self-hosted, OAuth configurato in n8n, solo installazione manuale via npm), vedi n8n-zoho (o api/connectors per il meccanismo di instradamento sottostante). Per i dettagli del connettore nativo usato da Sync Document to Zoho, vedi zoho.