Un bot Telegram che legge le foto e genera documenti Word (GPT Vision + docx)

Tempo di lettura: 7 minuti — Livello: intermedio

Il problema di partenza

C'è una categoria di lavoro d'ufficio che odio con tutto il cuore: ricopiare dati da un documento fotografato a un documento Word. Prendi una bolletta, una lettera, un contratto; ne estrai nome, indirizzo, riferimenti; li incolli in un modello formattato. Dieci minuti a documento, moltiplicati per decine di documenti. Zero valore aggiunto, massima probabilità di errore di battitura.

Il flusso che volevo: mando una foto su Telegram → ricevo indietro il documento Word compilato. Tutto qui. Questo articolo racconta come l'ho costruito e le due lezioni di architettura che mi ha insegnato.

L'architettura

Foto su Telegram
   │
   ▼
n8n (Telegram Trigger)
   │
   ▼
Modello vision (l'IA "legge" la foto)
   │  → restituisce JSON con i dati estratti
   ▼
Microservizio docx (Node/Express in un container)
   │  → compila il template Word con i dati
   ▼
n8n rimanda il .docx su Telegram

Quattro attori: Telegram come interfaccia (già in tasca a tutti, zero app da sviluppare), n8n come regista, un modello con capacità vision come lettore, e un piccolo servizio dedicato alla generazione del file Word.

Pezzo 1: Telegram come interfaccia universale

Sottovalutatissimo: un bot Telegram è l'interfaccia utente più economica del mondo. Niente frontend, niente login da gestire, funziona su qualsiasi telefono, e n8n ha il trigger nativo. Crei il bot con @BotFather in due minuti, incolli il token in n8n, e hai un'app "installata" sul telefono di chiunque ne conosca il nome.

Per strumenti interni — cose usate da te o da un piccolo team — è quasi sempre la risposta giusta alla domanda "che interfaccia gli faccio?".

Pezzo 2: la vision che legge i documenti

Il salto di qualità rispetto al vecchio OCR è enorme. L'OCR classico ti restituisce tutto il testo, in ordine sparso, e poi tocca a te capire cosa è il nome e cosa l'indirizzo. Un modello vision invece capisce il significato: gli passi la foto con un prompt tipo:

"Estrai da questo documento: nome completo, indirizzo, data, oggetto. Rispondi SOLO con un JSON in questo formato: {...}. Se un dato non è presente, usa null."

e ti torna indietro un JSON pulito, pronto per il passo successivo.

Due accorgimenti che ho imparato sul campo:

• Imponi il formato di risposta nel prompt, con l'esempio esatto del JSON che vuoi, e istruisci il modello a non aggiungere commenti. Poi, nel nodo successivo, fai comunque un parsing difensivo: prima o poi arriverà una risposta con una premessa di troppo, e il workflow non deve morire per questo.
• Gestisci il caso "foto illeggibile": se il modello risponde con troppi null, il bot deve rispondere "non riesco a leggere il documento, rifai la foto con più luce" invece di generare un Word pieno di buchi. L'errore gestito è quello che distingue un giocattolo da uno strumento.

Pezzo 3: la generazione del Word — e la lezione più importante

Qui la storia si fa interessante. Il piano iniziale era generare il .docx dentro n8n, in un nodo Code con la libreria docxtemplater. E per un po' ha pure funzionato.

Poi n8n (dalla versione 2.x) ha cambiato il modo in cui esegue il codice — i "task runner" — rendendo molto più rigido l'uso di moduli esterni nei nodi Code. Mi sono ritrovato a combattere contro la piattaforma: workaround, configurazioni fragili, aggiornamenti che rompevano tutto.

La soluzione è stata smettere di combattere: ho estratto la generazione documenti in un microservizio separato. Un container con Node + Express, un solo endpoint: riceve JSON + nome del template, restituisce il .docx. n8n lo chiama con un banale nodo HTTP Request sulla rete Docker interna.

POST http://docx-service:3000/generate
{ "template": "lettera.docx", "data": { "nome": "...", ... } }
→ risposta: il file .docx

Risultato: n8n fa l'orchestratore (il suo mestiere), il servizio docx fa una cosa sola e la fa bene, e i due si aggiornano indipendentemente. Da quando li ho separati, quella parte del sistema non si è più rotta. Non una volta.

La lezione generale: quando ti accorgi che stai forzando uno strumento a fare qualcosa per cui oppone resistenza, la risposta spesso non è più configurazione — è un componente in più. Nel prossimo articolo entro nel dettaglio proprio di questa scelta.

Il template Word

Ultima nota pratica: il template è un normale file .docx con dei segnaposto tipo {nome}, {indirizzo}. Lo prepari in Word come qualsiasi documento, con la formattazione che vuoi (intestazione, loghi, stili), e la libreria sostituisce i segnaposto. Il che significa che chiunque in un team può aggiornare il modello del documento senza toccare una riga di codice. Anche questo è design.

Cosa mi ha insegnato questo progetto

1. L'interfaccia migliore è quella che esiste già (Telegram)
2. La vision AI ha reso banale un problema che era difficile (l'estrazione dati da foto)
3. I confini tra i componenti contano più dei componenti (n8n orchestra, il microservizio esegue) Tempo risparmiato dal giorno del deploy: non lo conto più. Ed è la sensazione più bella di questo mestiere che sto imparando: costruire una cosa una volta, e vederla lavorare al posto tuo ogni giorno.

---

Questo articolo fa parte della serie "Build in Public" su perfetti.tech — dove racconto quello che costruisco davvero, errori compresi.