← Torna a tutti gli articoli

Tre nodi n8n, un archivio pronto per la conformità

SealDoc Team · · 5 min di lettura

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 una fattura deve restare leggibile, autentica e integra per l’intero periodo di conservazione, con una traccia di ciò che le è successo. La tua casella di posta dice “hai un nuovo allegato”. 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 quel divario, costruito con n8n e il nodo della community n8n-nodes-sealdoc. Tre nodi connessi, 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: una casella di posta, un upload su Slack, un cloud drive, un webhook esterno, qualunque cosa n8n possa ascoltare.
  2. Lo passa a SealDoc, che lo converte in PDF/A-3, ne verifica la conformità PDF/A, richiede una marca temporale RFC 3161 e registra ogni passaggio in una pista di audit a catena di hash.
  3. Memorizza il risultato dove la tua policy di conservazione lo prevede.

Quello che non devi costruire tu: la conversione PDF/A-3, la marcatura temporale con i relativi retry, la pista di audit, l’evidence pack. SealDoc fa questo lavoro dietro una sola chiamata API.

Prerequisiti

  • Un’istanza n8n self-hosted con i nodi della community abilitati.
  • Un workspace SealDoc con piano Starter o superiore. È da Starter che iniziano marche temporali ed evidence pack, e questo flusso si basa su entrambi. Vedi i prezzi.
  • Una chiave API SealDoc, creata nell’app SealDoc sotto Integration → API Keys. Copiala subito: viene mostrata una sola volta.

Installa il nodo in n8n da Settings → Community nodes → Install, con il nome del pacchetto n8n-nodes-sealdoc. Se invece installi i nodi a mano, esegui questo comando nella cartella dei nodi di n8n (di solito ~/.n8n/nodes) e riavvia n8n:

npm i n8n-nodes-sealdoc

Crea la credenziale da Credentials → New → SealDoc API e incolla la tua chiave in API Key. Il nodo SealDoc offre ora cinque risorse: Document, Invoice, Job, Peppol Check e Validator. Questo flusso usa Job.

Nodo 1, il trigger

Scegli il trigger che corrisponde al punto in cui oggi arrivano le tue fatture. Qui usiamo il Gmail Trigger perché è un punto di partenza comune; il pattern è identico per IMAP, OneDrive, una URL Webhook n8n o qualsiasi altra sorgente che consegna un file.

Configura il Gmail Trigger perché si attivi sui nuovi messaggi con un’etichetta come incoming-invoices e attiva Download Attachments. n8n mette quindi il primo allegato nella proprietà binaria attachment_0.

Nodo 2, SealDoc · Job · Create

Aggiungi un nodo SealDoc, rinominalo in Archive e imposta Resource su Job e Operation su Create:

  • Input Binary Field: attachment_0. È il nome della proprietà binaria del Nodo 1, digitato come testo semplice.
  • Run OCR: facoltativo. Attivalo per i documenti scansionati, così il PDF/A-3 riceve un livello di testo ricercabile.

La marca temporale non richiede alcuna impostazione: con il piano Starter o superiore, SealDoc richiede una marca temporale RFC 3161 per ogni job.

Il nodo carica il file e risponde subito con l’ID del job:

{ "jobId": "8b1e4c3a-2f7d-4e9a-b6c5-0d4f2a7e9c13" }

La conversione avviene in background, così un PDF lento non blocca mai la tua coda.

Nodo 3, SealDoc · Job · Get

Aggiungi un nodo Wait di qualche secondo, poi un altro nodo SealDoc con Resource Job, Operation Get e Job ID {{ $('Archive').item.json.jobId }}. Fallo seguire da un nodo IF su status:

  • queued o processing: torna al nodo Wait. Tieni un contatore nel loop, così un job bloccato non può farlo girare all’infinito.
  • completed: il PDF/A-3 è pronto.
  • failed: manda il job sul percorso di errore descritto più avanti.

Un job completato mostra le sue prove nella risposta: timestampedAt e timestampTokenBase64 per la marca temporale, outputHash per il risultato, isPdfACompliant per la verifica di conformità.

Per recuperare il file, aggiungi un nodo HTTP Request: GET https://api.sealdoc.eu/api/download/{{ $json.id }}, con Header Auth (X-Api-Key e la tua chiave) e Response Format File. Poi passalo al tuo nodo di storage.

Ogni job ha anche un Legal Evidence Pack: GET /api/jobs/{id}/evidence-pack, con lo stesso header. Lo ZIP contiene sempre compliance_passport.json, MANIFEST.json e manifest.sha256, più, dove presenti, il documento, chain_of_custody.json, ledger.json con public-keys.jwk e il token RFC 3161 timestamp_token.tsr. È autonomo e verificabile offline: un ispettore fiscale può verificarne l’integrità senza chiamare i nostri server. SealDoc lo assembla subito dopo il job; se lo richiedi nei primi istanti, l’API risponde 409 con un header Retry-After.

E gli errori

Due tipi, in due momenti:

  • All’invio. Un file mancante o lingue OCR non valide danno un 400, un piano senza la funzionalità dà un 402 e un limite mensile esaurito dà 409 quota_reached. In questi casi non viene creato alcun job e il nodo SealDoc interrompe il flusso. Imposta il suo On Error in modo che continui con un output di errore, se vuoi instradare questi casi.
  • Durante l’elaborazione. Il job termina con stato failed e errorMessage ne indica il motivo, ad esempio un file che non si può aprire. Instrada il ramo failed del tuo nodo IF verso Slack o e-mail, così che una persona sappia che qualcosa richiede attenzione.

Un’autorità di marcatura temporale che non risponde non fa fallire il job. Il job si completa, e compliance.rfc3161Timestamp nella risposta Get mostra se la marca temporale è presente.

Perché tre nodi bastano

Questo flusso non contiene alcuna logica propria di conversione, marcatura temporale o archiviazione. Ed è proprio questo 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 le regole o i formati evolvono, SealDoc evolve dietro la stessa chiamata API, e tu aggiorni la versione del nodo.

Questo flusso archivia i documenti che ricevi. Per le fatture che invii, lo stesso nodo ha la risorsa Invoice, che trasforma dati strutturati in una fattura Factur-X, XRechnung o Peppol BIS. Vedi come generare una fattura elettronica conforme con n8n.

Oltre n8n

Tutto ciò che trovi in questo tutorial è disponibile anche direttamente tramite l’API REST di SealDoc. A partire dal piano Growth, i webhook inviano job.processing, job.completed e job.failed al tuo endpoint, così puoi eliminare del tutto il loop di polling. Tutti i modi per collegarsi sono sulla nostra pagina integrazioni.

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

← Torna a tutti gli articoli