Tre nodi n8n, un archivio pronto per la conformità

La parte più difficile dell’automazione della conformità raramente sono le regole. È l’idraulica che collega le regole ai sistemi che già fanno girare la tua attività. Le regole dicono che ogni fattura B2B deve essere in un formato elettronico strutturato, archiviata per dieci anni e collegabile a una chain of custody a prova di manomissione. Il tuo software contabile dice “hai un nuovo allegato nella casella condivisa”. Mettere in collegamento questi due mondi è il punto in cui la maggior parte dei team si blocca.

Questo articolo percorre il più piccolo flusso di lavoro che chiude davvero quel gap, costruito con n8n e il nodo della community n8n-nodes-sealdoc. Tre nodi connessi. Circa 200 righe di JSON quando esporti il flusso. Zero codice personalizzato.

Cosa stiamo costruendo

Un flusso che per ogni PDF in arrivo fa quanto segue:

1. Preleva il file da un trigger a tua scelta (casella di posta, watch folder, upload Slack, un webhook esterno, qualunque cosa n8n possa ascoltare).
2. Lo passa a SealDoc, che lo converte in PDF/A-3, incorpora l’XML Factur-X accanto alla fattura renderizzata, aggiunge una marca temporale RFC 3161 e impacchetta il tutto in un archivio scaricabile.
3. Memorizza il risultato dove la tua policy di conservazione lo richiede.

Quello che non devi costruire tu: la conversione PDF/A-3, l’estrazione dell’XML Factur-X, la marcatura temporale, la pista di audit, l’hash del manifesto dell’evidence pack, la logica di retry verso l’autorità di marcatura. L’API di SealDoc fa questo lavoro dietro un singolo endpoint HTTP.

Prerequisiti

• Un’istanza di n8n, self-hosted o n8n Cloud. Il nodo della community funziona su entrambe.
• Un account SealDoc almeno con il piano Starter (le moat-feature da cui dipende questo flusso, custody, marche temporali ed evidence pack, sono disponibili a partire da Starter).
• Una chiave API SealDoc. Generane una nel dashboard sotto API keys, copia il secret una sola volta (non lo mostriamo mai più).

Installa il nodo della community:

npm i n8n-nodes-sealdoc

Riavvia n8n. Il nodo SealDoc compare ora sotto Nodes con tre risorse: Job, Validator e Peppol.

Nodo 1, il trigger

Scegli il trigger che corrisponde al punto in cui oggi atterrano le tue fatture. Per questo walkthrough useremo Gmail Trigger perché è la forma più comune che vediamo, ma il pattern è identico per IMAP, OneDrive, SharePoint, una URL Webhook n8n o una cartella monitorata.

Configura il Gmail Trigger perché si attivi all’arrivo di nuovi messaggi con un allegato PDF in un’etichetta specifica, ad es. incoming-invoices. L’output di questo nodo è il PDF binario in attachments[0].data.

Nodo 2, SealDoc Job · Create

Trascina un nodo SealDoc sul canvas, imposta Resource su Job e Operation su Create. Configura:

• File: collega a {{ $binary.attachments_0 }} (il PDF dal Nodo 1).
• Embed Factur-X: ON. SealDoc rileva automaticamente i campi della fattura e genera l’XML strutturato; se il PDF di origine contiene già un allegato XML, SealDoc lo rispetta e valida invece di sovrascrivere.
• Timestamp: ON. Il PDF/A-3 di output porterà una marca temporale RFC 3161 da una TSA gestita da noi, interrogabile in seguito come prova del momento in cui il documento esisteva.
• Retention category: scegli quella che la tua normativa fiscale impone (la categoria per la normativa italiana è nel menu a tendina).

Il nodo restituisce subito un jobId e uno status di pending. Non aspettare qui in modo sincrono. Una conversione Factur-X più marca temporale di solito si completa in meno di cinque secondi per una fattura normale, ma l’elaborazione PDF non è deterministica e non vuoi che un PDF di dichiarazione fiscale lento blocchi l’intera coda.

Nodo 3, SealDoc Job · Get

Aggiungi un altro nodo SealDoc. Imposta Resource su Job e Operation su Get. Collega Job ID a {{ $node["SealDoc Create"].json.jobId }}. Avvolgi il nodo nella primitiva Wait di n8n con un ritardo di 2 secondi e un massimo di 10 iterazioni, facendo polling finché status è completed o failed.

Quando completed, la risposta porta un downloadUrl valido cinque minuti. L’URL punta al PDF/A-3 convertito, che ora è conforme Factur-X, marcato temporalmente e registrato nella nostra chain of custody.

Ottieni anche un evidencePackUrl se il tuo piano include gli evidence pack. Quel ZIP contiene il PDF originale, il PDF/A-3 convertito, l’XML Factur-X, il token RFC 3161, il file di hash del manifesto e una ricevuta JSON che elenca ogni passaggio. Gli auditor lo adorano perché è autonomo e verificabile offline; puoi consegnarne una copia a un ispettore fiscale che potrà verificare l’integrità senza chiamare i nostri server.

E gli errori

SealDoc restituisce motivi di errore strutturati nel campo failureReason. I quattro che vedrai in pratica:

• validation_failed, il PDF di origine è malformato o protetto da password. Restituisci al team che lo ha caricato.
• unsupported_source, ad esempio un PDF realmente cifrato che non possiamo aprire. Rimanda al mittente.
• timestamp_unavailable, la nostra TSA ha avuto un disservizio. Ritentiamo automaticamente; se il budget di retry si esaurisce, il job termina in failed e puoi rilanciarlo.
• quota_exceeded, il limite mensile di job del tuo piano è stato raggiunto. O fai upgrade o aspetti il reset.

In n8n, instrada il ramo failed del nodo Get verso una notifica Slack o e-mail così che una persona sappia quando qualcosa è davvero bloccato.

Perché tre nodi bastano

Noterai che questo flusso non fa di per sé alcuna logica di validazione, firma o archiviazione. Ed è proprio il punto. L’API di SealDoc è il confine; il tuo flusso n8n è il tessuto connettivo fra quel confine e i tuoi sistemi di business. Quando entrerà in vigore il mandato B2B belga, non dovrai ricostruire questo flusso. Quando partirà l’obbligo francese di settembre 2026, non dovrai ricostruirlo. Quando il regolatore aggiornerà il profilo Factur-X nel 2027, aggiornerai la versione del nodo SealDoc.

Questo è il valore del pattern connector: la turbolenza regolatoria vive nella nostra codebase, non nella tua.

Oltre n8n

Se non usi n8n, ogni operazione di questo tutorial è disponibile anche direttamente tramite l’API REST di SealDoc, o tramite Webhook se preferisci le notifiche push al polling. Il menu completo vive sulla nostra pagina integrazioni, con esempi copia-incolla per ogni superficie. I connettori Make, Zapier ed Exact Online sono in costruzione attiva; se il tuo stack ne usa uno, scrivici per l’accesso anticipato.

L’idraulica della conformità è risolta. Cosa fare del tempo risparmiato, sta a te.