Il problema
Le fatture esistevano solo come PDF. Tutto quello che serviva per lavorarci andava riscritto a mano:
- anagrafiche clienti e prodotti ribattute a ogni documento, con errori e duplicati
- nessun modo di sapere quanto si fosse fatturato per prodotto, per cliente o per periodo senza aprire i file uno a uno
- scadenze di pagamento sepolte dentro i documenti, e quindi dimenticate
- la stessa fattura inserita due volte senza che nessuno se ne accorgesse
Il dato commerciale c’era già: era solo illeggibile.
L’approccio
Invece di costruire l’ennesimo gestionale con moduli da compilare, abbiamo ribaltato il flusso: l’unico modo di inserire una fattura è caricare il PDF. Non esistono pulsanti di creazione manuale per clienti o prodotti — nascono dai documenti e restano modificabili.
Come è strutturato
1. Importazione
Caricamento multiplo con elaborazione in background e stato per singolo file. Il riconoscimento dei duplicati avviene sul contenuto del PDF, non sul nome: lo stesso documento non entra due volte. L’estrazione è affidata a parser dedicati per ciascun layout di documento — fattura, accompagnatoria, preventivo — progettati per essere estesi: un nuovo tracciato significa aggiungere un modulo, non riscrivere il sistema.
2. Verifica umana
Ogni fattura importata nasce come non confermata. L’operatore vede il PDF originale accanto ai dati estratti, corregge quello che serve e conferma. Solo da quel momento il documento entra in statistiche e promemoria. È la scelta di design più importante del progetto: l’automazione propone, la persona valida, i numeri restano affidabili.
3. Anagrafiche che si costruiscono da sole
I clienti vengono riconosciuti da Partita IVA o Codice Fiscale, i prodotti dal codice articolo. Il catalogo distingue automaticamente canale professionale e domiciliare leggendo il suffisso del codice, così lo stesso prodotto in due formati resta correttamente separato nelle analisi.
4. Lettura del business
Dashboard e schede di dettaglio con fatturato per cliente, per prodotto e per periodo, andamento mensile e annuale, prodotti più venduti. Tutti i valori sono espressi a imponibile, al netto dell’IVA, per avere un dato di fatturato realmente confrontabile.
5. Scadenze sotto controllo
Le scadenze vengono lette dal documento e diventano promemoria automatici via email sui pagamenti in arrivo, con notifica singola per scadenza.
Lo stack
Monorepo con API AdonisJS e database SQLite con ricerca full-text, interfaccia React con Vite e Tailwind, parser di estrazione in Python, tipi condivisi tra front-end e back-end per una type safety end-to-end, documentazione API OpenAPI, deploy su VPS con Caddy e PM2 e notifica automatica degli errori in produzione.
Il risultato
L’archivio fatture è diventato una base dati interrogabile. Zero inserimento manuale, anagrafiche pulite, numeri aggiornati e scadenze visibili prima che diventino un problema.
