Divisione dei documenti con il Split Agent in n8n

Salve e benvenuto nell’Accademia PaperOffice AI. Questo episodio riguarda la Split Agent in n8n: viene inserita una scansione in batch, mentre vengono restituiti documenti individuali.

Risultato in primo piano: scansione in batch in ingresso, documenti in uscita

Analizziamo innanzitutto il risultato. La nostra scansione in batch proveniente dall’ufficio postale contiene sette pagine, con un foglio separatore interposto. Il Split Agent riconosce dove termina un documento e dove inizia il successivo. Vengono restituiti cinque documenti, ciascuno con il proprio tipo, un nome descrittivo e le relative pagine. Ecco come appare ciò in n8n. Per effettuare un test, avvio il flusso di lavoro nell’editor e invio la scansione in batch al webhook. Ora il flusso di lavoro si esegue nodo per nodo. Il lavoro di divisione viene inviato a PaperOffice, e il ciclo continua a verificare fino al completamento. Dopo poco meno di quaranta secondi, tutto è terminato. Il nodo Pieces contiene il risultato: cinque voci, una per documento. Questi sono i cinque documenti: ordine d’acquisto, bolla di consegna, fattura, circolare di servizio e rapporto di ispezione. La circolare di servizio consta di due pagine, che rimangono unite. Il Split Agent ha rilevato il foglio separatore a pagina tre e lo ha rimosso. Inoltre, ogni documento riceve un nome descrittivo basato sulla nostra regola. Ogni elemento è un PDF autonomo. Ecco la circolare di servizio: entrambe le pagine in un unico file, denominato secondo la nostra regola. Il risultato include il link per il download, ma questo è valido solo per breve tempo. Ecco un secondo batch, più complesso: sei pagine in tre lingue. Un ordine d’acquisto in inglese, una bolla di consegna in spagnolo e una fattura spagnola, una nota di credito, una fattura di trasporto con una macchia di caffè e una foto storta del telefono di una fattura. Il Split Agent separa tutti e sei i documenti e li denomina in modo coerente in inglese. Ed ecco come costruirlo, in quattro fasi: input, lavoro di divisione, attesa e pezzi.

Fase 1 di 4: Input

La prima fase è l’input: un webhook con autenticazione dell’intestazione che accetta il file tramite POST. Se il file manca, il flusso di lavoro risponde immediatamente con un errore chiaro. E cosa accade senza un file? Invio una richiesta senza allegato. Il flusso di lavoro segue il percorso breve attraverso il nodo File missing e risponde subito con stato 400 e un messaggio chiaro. Non viene creato alcun lavoro di divisione, quindi non ci sono nemmeno costi.

Fase 2 di 4: Lavoro di divisione

La fase due invia il batch al Split Agent, mediante una singola chiamata HTTP all’API PaperOffice. Vengono inclusi il modello di divisione, il modello Ultra e una regola per la denominazione delle parti: tipo di documento, data, mittente. Nel campo del modello, è possibile scegliere l’ambito. Il sistema Basic rileva i confini e denomina le parti. Anche il sistema Premium legge il tipo di documento, la data e il mittente. Il sistema Ultra fornisce inoltre il ragionamento per ogni taglio e garantisce una traccia di controllo (audit trail). La fatturazione avviene per pagina. Due elementi determinano il prezzo: l’ambito e la corsia di elaborazione. È stata scelta l’opzione istantanea, ovvero un avvio immediato. Senza garanzia di avvio e senza SLA, il costo è inferiore. I prezzi attuali sono disponibili sul sito web nella sezione Prezzi.

Fase 3 di 4: In attesa

Il job viene eseguito in background. Ogni sei secondi, il ciclo verifica lo stato. Al termine, l’esecuzione prosegue. In caso di errore, l’esecuzione termina con un messaggio.

Fase 4 di 4: Pezzi

Nello stadio quattro, la risposta diventa un elenco, con una voce per documento. Se un foglio separatore dovesse tornare come elemento autonomo, questo nodo lo filtra. Infine, il webhook risponde con esattamente questo elenco. E cosa succede all’elenco successivamente? Nel video principale sulla casella di posta, è esattamente qui che il ciclo prende il sopravvento: ogni documento viene inviato al IDP Agent individualmente, viene letto e archiviato in un Workspace. In questo modo, la suddivisione diventa l’inizio di un intero flusso di lavoro.

Costruirlo autonomamente: Credenziali e chiamate dall’esterno

Per realizzarlo autonomamente, sono necessarie due credenziali, entrambe da inserire come autenticazione header in n8n. È possibile scegliere la chiave per il webhook assegnando un nome di intestazione personalizzato. Per PaperOffice, si utilizza una chiave API dell’account, reperibile nella sezione API e sviluppatori; questa va inserita nell’intestazione Authorization. Dall’esterno, è possibile invocare il workflow mediante una richiesta POST all’URL del webhook: il file va inserito nel campo file, la chiave nell’intestazione. Tale operazione può essere eseguita tramite script, un altro programma o un secondo workflow. Il risultato restituito è l’elenco dei documenti, pronti per il passaggio successivo. Si consigliano tre suggerimenti pratici. Primo: non sono necessari fogli separatori; Split Agent rileva i confini direttamente dal contenuto. Secondo: la regola di denominazione va impostata nel campo delle istruzioni di denominazione, ad esempio utilizzando data, mittente o tipo di documento. Terzo: è opportuno scaricare i file o archiviarli immediatamente, poiché i link scadono dopo breve tempo. Questo era il funzionamento di Split Agent in n8n: un webhook, una chiamata, un ciclo e un elenco. In PaperOffice, è possibile utilizzarlo direttamente durante il caricamento. Il video principale sulla casella di posta illustra come i singoli documenti procedano da questo punto. Alla prossima nell’Accademia PaperOffice AI.