📄 Estrattore OCR Fatture

Applicazione web per estrarre automaticamente dati da fatture PDF e immagini tramite OCR e salvarli su Google Sheets.

🎯 Sistema intelligente multi-formato, multilingua, multi-valuta e multi-azienda per l'estrazione automatizzata di dati contabili.

---

📸 Screenshot

Interfaccia Principale - Upload drag & drop, modalità estrazione	Sistema Multi-Azienda - Creazione azienda con logo personalizzato
Elaborazione Fatture - Estrazione automatica con confidence	Risultati OCR - Tabella interattiva con modifica dati
Export Google Sheets - Integrazione diretta e controllo duplicati	Gestione Logo - Upload e personalizzazione branding aziendale

---

📑 Indice

• Caratteristiche Principali
• Quick Start
• Installazione Completa
• Configurazione
• Utilizzo
• Sistema Multi-Azienda
• Funzionalità Dettagliate
• Troubleshooting
• FAQ

---

✨ Caratteristiche Principali

🏢 Multi-Azienda

Gestisci più aziende sullo stesso server, ognuna con:

• Nickname univoco e logo personalizzato
• Token di autenticazione generato automaticamente
• Google Sheet dedicato con nome: "Fatture OCR - {nickname}"
• Isolamento dati completo tra aziende

🤖 OCR Intelligente

Sistema a 5 modalità con validazione automatica:

• Auto (Raccomandato): Sistema ibrido adattivo
• Tesseract: OCR locale gratuito (70-100% accuratezza)
• Gemini Flash: AI economico e veloce (~0.5¢/fattura)
• Gemini Pro: Massima accuratezza OCR (~1-2¢/fattura)
• Claude Sonnet 4.5: Ragionamento avanzato (~2-3¢/fattura)

🌍 Supporto Internazionale

• 6 Paesi: Italia, Germania, Svizzera, UK, USA, Hong Kong
• 4 Lingue: Italiano, Tedesco, Inglese, Francese
• 6 Valute: EUR, CHF, USD, GBP, HKD, JPY
• 7 Formati: PDF, JPG, JPEG, PNG, GIF, BMP, TIFF

📊 Export Automatico

Integrazione diretta con Google Sheets:

• Controllo duplicati automatico
• Formattazione professionale
• Cache persistente degli spreadsheet
• OAuth2 sicuro

🔒 Sicurezza Enterprise

Sistema di autenticazione multi-livello robusto:

• Autenticazione Token-Based: Ogni richiesta API protetta con Bearer token
• Isolamento Multi-Tenant: File ownership tracking impedisce accessi cross-azienda
• Modalità Amministratore: Dashboard dedicata con token admin separato
• Security Logging: Monitoraggio automatico di tentativi di accesso non autorizzati
• Auto-Logout: Sessioni invalide gestite automaticamente
• API Protection: Tutti gli endpoint protetti con decoratori di autenticazione

---

🚀 Quick Start

Prerequisiti Veloci

# macOS - Installa tutto con 3 comandi
brew install tesseract tesseract-lang poppler python@3.11

Installazione Rapida (5 minuti)

# 1. Clona il repository
git clone https://github.com/cerro333/fatture-ocr_Claude-code.git
cd fatture-ocr_Claude-code

# 2. Crea ambiente virtuale e installa dipendenze
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 3. Configura environment
cp .env.example .env
# Modifica .env se necessario (opzionale per iniziare)

# 4. Avvia il server
cd backend
python app.py

Primo Utilizzo (2 minuti)

1. Apri browser: http://localhost:5001
2. Crea azienda: Inserisci nickname (es: "miazienda")
3. Carica fattura: Drag & drop un PDF
4. Estrai dati: Clicca "Estrai Dati"
5. Connetti Google: Solo la prima volta (OAuth2)
6. Esporta: Clicca "Esporta su Google Sheets"

✅ Fatto! I tuoi dati sono su Google Sheets.

---

💻 Installazione Completa

1. Prerequisiti di Sistema

macOS (Click per espandere)

Homebrew (se non installato)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Tesseract OCR + Lingue

brew install tesseract tesseract-lang
tesseract --version  # Verifica installazione

Poppler (per PDF)

brew install poppler

Python 3.9+

python3 --version  # Verifica versione
brew install python@3.11  # Se necessario

Linux (Ubuntu/Debian)

# Aggiorna pacchetti
sudo apt update

# Installa Tesseract + lingue
sudo apt install tesseract-ocr tesseract-ocr-ita tesseract-ocr-deu tesseract-ocr-fra

# Installa Poppler
sudo apt install poppler-utils

# Python 3.9+
sudo apt install python3 python3-pip python3-venv

Windows

Tesseract OCR

1. Scarica installer da: https://github.com/UB-Mannheim/tesseract/wiki
2. Installa in C:\Program Files\Tesseract-OCR\
3. Aggiungi al PATH: C:\Program Files\Tesseract-OCR\
4. Scarica language packs: italiano, tedesco, francese

Poppler

1. Scarica da: https://github.com/oschwartz10612/poppler-windows/releases
2. Estrai in C:\Program Files\poppler\
3. Aggiungi al PATH: C:\Program Files\poppler\Library\bin\

Python 3.9+

Scarica e installa da: https://www.python.org/downloads/

2. Installazione Applicazione

# Clona repository
git clone https://github.com/cerro333/fatture-ocr_Claude-code.git
cd fatture-ocr_Claude-code

# Crea ambiente virtuale
python3 -m venv venv

# Attiva ambiente virtuale
source venv/bin/activate  # macOS/Linux
# oppure
venv\Scripts\activate  # Windows

# Installa dipendenze
pip install --upgrade pip
pip install -r requirements.txt

---

⚙️ Configurazione

1. File di Configurazione

# Copia template
cp .env.example .env

# Modifica con il tuo editor
nano .env  # o code .env, vim .env, ecc.

2. Google Cloud (OBBLIGATORIO)

Per esportare su Google Sheets devi configurare OAuth2:

Step 1: Crea Progetto Google Cloud

1. Vai su Google Cloud Console
2. Clicca Seleziona progetto → Nuovo progetto
3. Nome: fatture-ocr (o quello che preferisci)
4. Clicca Crea

Step 2: Abilita API (IMPORTANTE)

1. Menu laterale: API e servizi → Libreria
2. Cerca e abilita:
   • Google Sheets API ✅ (OBBLIGATORIO)
   • Google Drive API ✅ (FORTEMENTE CONSIGLIATO)

⚠️ Nota: Senza Drive API, il sistema creerà un nuovo foglio ad ogni export invece di riutilizzare quello esistente.

Step 3: Configura OAuth Consent Screen

1. API e servizi → Schermata consenso OAuth
2. Tipo: Esterno → Crea
3. Compila:
   • Nome app: Estrattore Fatture
   • Email assistenza: tua email
   • Email sviluppatore: tua email
4. Salva e continua
5. Ambiti → Aggiungi o rimuovi ambiti:
   • https://www.googleapis.com/auth/spreadsheets
   • https://www.googleapis.com/auth/drive.file
6. Utenti di test: Aggiungi la tua email Gmail
7. Salva e continua → Torna alla dashboard

Step 4: Crea Credenziali OAuth

1. API e servizi → Credenziali
2. + Crea credenziali → ID client OAuth
3. Tipo: Applicazione desktop
4. Nome: Fatture OCR Desktop
5. Crea → Scarica JSON
6. Sposta il file:

mv ~/Downloads/client_*.json credentials/client_secret.json

3. API AI (OPZIONALE)

Opzione 1: Google Gemini (⭐ Raccomandato)

Vantaggi: Gratis fino a 1500 richieste/giorno, miglior OCR

# 1. Ottieni API Key gratuita
# Vai su: https://aistudio.google.com/app/apikey
# Crea API Key e copiala

# 2. Aggiungi a .env
GOOGLE_GEMINI_API_KEY=AIzaSy-tua-chiave-qui

# 3. Scegli modelli (opzionale)
GEMINI_FLASH_MODEL=gemini-2.0-flash-exp  # Economico
GEMINI_PRO_MODEL=gemini-2.0-flash-thinking-exp-1219    # Accurato

Opzione 2: Claude Sonnet 4.5

Vantaggi: Ragionamento avanzato per documenti complessi

# 1. Crea account Anthropic
# Vai su: https://console.anthropic.com/
# Settings → API Keys → Create Key

# 2. Aggiungi a .env
ANTHROPIC_API_KEY=sk-ant-api03-tua-chiave-qui

Nota: L'app funziona perfettamente anche senza AI, usando solo Tesseract OCR gratuito.

---

🎯 Utilizzo

Avvio Server

# Attiva ambiente virtuale (se non attivo)
cd fatture-ocr_Claude-code
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate  # Windows

# Avvia server
cd backend
python app.py

Vedrai:

==================================================
Estrattore OCR Fatture
==================================================
Server avviato su: http://localhost:5001

Interfaccia Web

Apri browser: http://localhost:5001

Prima Configurazione

1. Crea Azienda

   • Clicca "Crea Nuova Azienda"
   • Inserisci nickname (es: "acme", "miazienda")
   • (Opzionale) Carica logo aziendale
   • Copia e salva il token generato!

2. Connetti Google Sheets (solo prima volta)

   • Clicca "Connetti Google"
   • Autorizza l'app nel browser
   • Accetta permessi richiesti

Workflow Standard

📁 Upload → 🔍 Estrai → ✏️ Verifica → 📊 Esporta

1. Upload Fatture

   • Drag & drop o clicca per selezionare
   • Formati: PDF, JPG, PNG, TIFF, ecc.
   • Multipli file supportati

2. Estrai Dati

   • Scegli modalità:
     • Auto (raccomandato): sistema intelligente
     • Tesseract: solo OCR locale
     • AI: massima accuratezza
   • Clicca "Estrai Dati"
   • Attendi elaborazione

3. Verifica Risultati

   • Controlla dati nella tabella
   • Clicca ✏️ per modificare manualmente
   • Verde = Alta confidenza
   • Giallo = Media confidenza
   • Rosso = Bassa confidenza (verifica consigliata)

4. Esporta su Google Sheets

   • Seleziona righe da esportare
   • Clicca "Esporta su Google Sheets"
   • Automaticamente:
     • Crea foglio "Fatture OCR - {nickname}"
     • Controlla duplicati
     • Formatta intestazioni
   • Clicca link per aprire il foglio

---

🏢 Sistema Multi-Azienda

Panoramica

Gestisci più aziende sullo stesso server, ognuna con:

• Nickname univoco (3-20 caratteri)
• Token di autenticazione (generato automaticamente)
• Google Sheet dedicato: "Fatture OCR - {nickname}"
• Logo personalizzato (opzionale)
• Dati completamente isolati

Formato .env

# Azienda 1
COMPANY_acme_NICKNAME=acme
COMPANY_acme_TOKEN=cf1ab10626eac1644d5de83cfed66bdc
COMPANY_acme_SHEET_ID=1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs
COMPANY_acme_LOGO=acme.png

# Azienda 2
COMPANY_techcorp_NICKNAME=techcorp
COMPANY_techcorp_TOKEN=d143a0164ef15508e5415afc86c1392d
COMPANY_techcorp_SHEET_ID=1XyZ123AbC456DeF789GhI012JkL345MnO
COMPANY_techcorp_LOGO=techcorp.jpg

Creazione Azienda

Dall'Interfaccia Web (Raccomandato):

1. Apri http://localhost:5001
2. Clicca "Crea Nuova Azienda"
3. Inserisci nickname univoco
4. (Opzionale) Carica logo
5. Salva il token generato

Il sistema salva automaticamente in .env - Non serve riavviare il server!

Switch tra Aziende

1. Clicca "Esci" nell'header
2. Inserisci token dell'altra azienda
3. Clicca "Verifica Token"

Gestione Logo

• Upload: Clicca "Cambia Logo" nell'header
• Formati: PNG, JPG, GIF, WebP (max 5MB)
• Dimensione: Visualizzato 200x100px
• Rimozione: Nel modale logo, clicca "Rimuovi Logo"

Condivisione Token

Il token deve essere condiviso solo con persone fidate della tua azienda:

✅ Metodi Sicuri:

• Password manager aziendale (1Password, Bitwarden)
• Email interna aziendale
• Chat aziendale sicura (Slack, Teams)

❌ NON Condividere:

• Social media pubblici
• Email non cifrate a esterni

👑 Modalità Amministratore

L'admin è un superuser con accesso completo a tutte le aziende.

Setup Admin Token

Esegui lo script di configurazione iniziale:

python3 setup_admin.py

Il script:

1. Genera un token sicuro di 64 caratteri
2. Lo salva automaticamente in .env (riga ADMIN_TOKEN=...)
3. Mostra il token per uso immediato

⚠️ IMPORTANTE: Salva il token admin in un posto sicuro (password manager). È necessario per accedere alla dashboard admin.

Accesso Admin

1. Apri http://localhost:5001
2. Nel modale di autenticazione, clicca sulla tab "Admin"
3. Inserisci il token admin
4. Clicca "Accedi come Admin"

Dashboard Admin

La dashboard admin (dark mode automatico) offre:

📊 Panoramica Aziende:

• Lista completa di tutte le aziende configurate
• Visualizzazione logo, token (mascherato), Sheet ID
• Badge indicatore presenza Google Sheet

🎭 Impersonazione Azienda:

• Dropdown per selezionare e operare come qualsiasi azienda
• Bottone "Impersona" per switchare rapidamente
• Bottone "Torna all'Admin" per tornare alla dashboard

⚙️ Operazioni CRUD:

• Crea Azienda: Genera nuova azienda con nickname e logo
• Elimina Azienda: Rimuove azienda da .env (opzionalmente anche il Google Sheet)
• Rigenera Token: Genera nuovo token per un'azienda (il vecchio smette di funzionare)

Eliminazione Google Sheet

Quando elimini un'azienda, puoi scegliere se:

• ✅ Eliminare anche il Google Sheet → Il foglio viene spostato nel cestino di Google Drive (recuperabile entro 30 giorni)
• ❌ Mantenere il Google Sheet → Il foglio rimane accessibile, l'azienda viene solo rimossa dal sistema

Sicurezza Admin

🔒 Best Practices:

• Non condividere mai il token admin
• Usa un password manager per conservarlo
• Rigeneralo periodicamente (es. ogni 6 mesi)
• Limita accesso al server a persone fidate

⚠️ Il token admin NON scade - gestiscilo con la stessa cautela delle password di root/admin

Rigenerazione Token Admin

Se perdi il token admin o vuoi rigenerarlo per sicurezza:

python3 setup_admin.py

Scegli l'opzione di rigenerazione - il vecchio token smetterà di funzionare.

---

📋 Funzionalità Dettagliate

🔍 OCR e Riconoscimento Intelligente

Tesseract OCR (Locale, Gratuito)

• Pre-processing avanzato per immagini fotografate
• Supporto multilingua: IT, DE, EN, FR
• Nessun invio dati a server esterni

Sistema di Validazione Intelligente

Validazione Fornitore (multilingua):

• ❌ Numeri telefono nel nome (-25% confidence)
• ❌ URL/domini web (-25%)
• ❌ Email nel nome (-25%)
• ❌ Keywords indirizzo (-20%)
• ❌ Nome troppo lungo > 80 caratteri (-20%)

Validazione Numero Fattura:

• ❌ Keywords data/fattura/importo (-30%)
• ❌ Errori OCR comuni (-30%)
• ❌ Solo lettere senza numeri (-20%)

Trigger AI Automatico:

• Confidence < 85% → Gemini Flash
• Confidence < 90% → Gemini Pro
• Elimina falsi positivi da Tesseract

Campi Riconosciuti

• Fornitore: Algoritmo a priorità con suffissi aziendali
• Data Fattura: Formati numerici e testuali
• Data Scadenza: Multilingua
• Numero Fattura: IT, DE, CH, UK, US
• Importo Totale: Logica avanzata, skip intestazioni
• Valuta: Rilevamento contestuale

🌍 Gestione Internazionale

Formati Numerici

• 🇮🇹 Italia/Germania: 1.699,00
• 🇨🇭 Svizzera: 1'699.00
• 🇺🇸 USA/UK: 1,699.00
• 🇭🇰 Hong Kong: HK$3263

Output Normalizzato

• Tutti gli importi con 2 decimali
• Formato: 234.00, 1234.50
• Valido per tutti i metodi (Tesseract, Gemini, Claude)

Valute Supportate

EUR, CHF, USD, GBP, HKD, JPY

Lingue Supportate

Italiano, Tedesco, Inglese, Francese

📊 Export e Google Sheets

Funzionalità Export

• Foglio Dedicato: "Fatture OCR - {nickname}" per ogni azienda
• Controllo Duplicati: Basato sul nome file
• Formattazione Automatica:
  • Intestazioni: Sfondo grigio, grassetto, centrate
  • Colonne: 150px larghezza
  • Prima riga: Congelata (frozen)

Colonne Esportate

1. Data Fattura
2. Data Scadenza
3. Fornitore
4. Numero Fattura
5. Importo Totale
6. Valuta
7. Nome File
8. Data Elaborazione

Cache Persistente

Il sistema salva l'ID del foglio in:

• .env: COMPANY_{nickname}_SHEET_ID
• credentials/spreadsheet_cache.json

Riutilizza lo stesso foglio per export successivi.

🤖 Modalità AI Avanzate

1. Auto (Raccomandato)

Per FOTO (JPG, PNG):

• Skip Tesseract → AI vision model diretto
• Gemini gestisce meglio angolazione, luce, riflessi

Per PDF:

• Livello 1: Tesseract OCR (gratis) + validazione
• Livello 2: Gemini Flash se confidence < 85%
• Livello 3: Gemini Pro se confidence < 90%

Risparmio: Usa AI solo quando necessario (50-70% meno costi)

2. Gemini Flash

• Economico: ~$0.50/MTok (~0.5¢/fattura)
• Veloce: < 3 secondi
• Ottimo OCR
• Consigliato per: Volume alto, budget limitato

3. Gemini Pro

• Accuratezza massima: ~$2/MTok (~1-2¢/fattura)
• Migliore OCR del mercato (+20% vs Claude)
• Consigliato per: Documenti critici, massima precisione

4. Claude Sonnet 4.5

• Ragionamento avanzato: ~$3-15/MTok (~2-3¢/fattura)
• Analisi contestuale superiore
• Consigliato per: Layout non standard, documenti complessi

5. Tesseract (Solo OCR)

• Gratis, locale
• 70-100% accuratezza su PDF digitali
• 60-80% su foto/scansioni
• Consigliato per: PDF digitali di buona qualità

---

🛠️ Troubleshooting

❌ Tesseract Non Trovato

Soluzione macOS

# Verifica installazione
which tesseract

# Se non trovato, reinstalla
brew reinstall tesseract tesseract-lang

Soluzione Linux

# Verifica installazione
tesseract --version

# Se non trovato
sudo apt install tesseract-ocr tesseract-ocr-ita

Soluzione Windows

1. Verifica installazione: tesseract --version in CMD
2. Se manca, reinstalla da: https://github.com/UB-Mannheim/tesseract/wiki
3. Aggiungi al PATH: C:\Program Files\Tesseract-OCR\

❌ Poppler Non Trovato

# macOS
brew install poppler

# Linux
sudo apt install poppler-utils

# Windows
# Scarica da: https://github.com/oschwartz10612/poppler-windows/releases
# Estrai in C:\Program Files\poppler\
# Aggiungi al PATH: C:\Program Files\poppler\Library\bin\

❌ Porta 5001 Già in Uso

# Trova processo
lsof -i :5001

# Termina processo
lsof -ti:5001 | xargs kill -9

# Oppure usa porta diversa in backend/app.py:
# app.run(host="0.0.0.0", port=5002, debug=True)

❌ Google Sheets: Fogli Duplicati

Causa: Google Drive API non abilitata

Soluzione:

1. Google Cloud Console
2. Progetto fatture-ocr
3. API e servizi → Libreria
4. Cerca "Google Drive API"
5. Abilita

❌ Errore Credenziali Google

1. Verifica che credentials/client_secret.json esista
2. Verifica che sia un JSON valido
3. Elimina credentials/token.json e riautorizza:

rm credentials/token.json
# Riavvia server e riconnetti Google

❌ OCR Non Riconosce Testo

Possibili cause:

• PDF scansione bassa qualità
• Foto sfocata o con riflessi
• Layout molto personalizzato

Soluzioni:

1. Usa modalità AI (Gemini/Claude)
2. Migliora qualità scansione/foto
3. Usa PDF digitali invece di scansioni
4. Per foto: buona illuminazione, inquadratura dritta

❌ Token Non Valido

1. Verifica token in .env
2. Controlla COMPANY_{nickname}_TOKEN
3. Se perso, crea nuova azienda

❌ Importazione Fallisce

# Reinstalla dipendenze
pip install --force-reinstall -r requirements.txt

# Verifica Python version
python3 --version  # Deve essere 3.9+

---

❓ FAQ

È necessario configurare le API AI?

No! L'applicazione funziona perfettamente con solo Tesseract OCR (gratuito, locale). Le API AI sono opzionali per:

• Massima accuratezza
• Foto di bassa qualità
• Layout non standard

Per iniziare basta Tesseract. Aggiungi AI dopo se necessario.

Quanto costano le API AI?

Gemini (Raccomandato):

• Gratis: fino a 1500 richieste/giorno
• Flash: ~$0.50/MTok → ~0.5¢ per fattura
• Pro: ~$2/MTok → ~1-2¢ per fattura

Claude:

• Sonnet 4.5: ~$3-15/MTok → ~2-3¢ per fattura
• $5 crediti gratuiti per nuovi account

Modalità Auto:

• Usa AI solo quando necessario
• Risparmio 50-70% sui costi
• ~€1-2 per 100 fatture

I miei dati sono sicuri?

Tesseract:

• ✅ 100% locale
• ✅ Nessun invio a server esterni
• ✅ Privacy totale

AI (Gemini/Claude):

• ⚠️ File inviati a server AI per elaborazione
• ✅ Dati non usati per training (policy provider)
• ⚠️ Non usare per documenti molto sensibili

Google Sheets:

• ⚠️ Dati inviati solo a Google per export
• ✅ Controllati da te tramite Google Account

Posso usare lo stesso Google Sheet per più aziende?

No, ogni azienda ha il proprio foglio dedicato:

• "Fatture OCR - acme"
• "Fatture OCR - techcorp"
• ecc.

Questo garantisce:

• ✅ Isolamento dati
• ✅ Controllo duplicati corretto
• ✅ Organizzazione chiara

Come condivido l'accesso con il mio team?

Condividi il token aziendale:

1. Copia token da .env: COMPANY_{nickname}_TOKEN
2. Invia tramite canale sicuro (password manager, email interna)
3. Colleghi inseriscono token nell'interfaccia web
4. Accesso immediato ai dati azienda

Nota: Tutti con lo stesso token vedono e modificano gli stessi dati.

Supporta fatture elettroniche XML?

No, attualmente supporta solo:

• PDF (digitali e scansionati)
• Immagini (JPG, PNG, TIFF, ecc.)

Le fatture elettroniche XML richiedono parsing strutturato diverso.

Funziona offline?

Parzialmente:

• ✅ OCR con Tesseract: 100% offline
• ❌ Export Google Sheets: richiede internet
• ❌ AI (Gemini/Claude): richiede internet

Puoi elaborare fatture offline e esportare quando riconnesso.

Qual è l'accuratezza del sistema?

Tesseract (Gratis):

• PDF digitali: >90%
• PDF scansionati: 70-85%
• Foto: 60-80%

AI Gemini Pro:

• PDF digitali: 98-99%
• PDF scansionati: 95-98%
• Foto: 90-95%

Modalità Auto:

• Combina entrambi
• Accuratezza media 92-96%
• Costo medio ~€1 per 100 fatture

---

📊 Struttura Progetto

fatture-ocr/
├── backend/
│   ├── app.py                # Server Flask principale
│   ├── config.py             # Configurazioni
│   ├── company_manager.py    # Gestione multi-azienda
│   ├── ocr_processor.py      # Elaborazione OCR (Tesseract)
│   ├── ai_extractor.py       # Estrazione AI (Claude)
│   ├── gemini_extractor.py   # Estrazione AI (Gemini)
│   ├── data_extractor.py     # Estrazione dati fatture
│   └── sheets_handler.py     # Integrazione Google Sheets
├── frontend/
│   ├── index.html            # Pagina principale
│   ├── css/styles.css        # Stili
│   └── js/app.js             # Logica frontend
├── credentials/              # Credenziali Google (gitignore)
│   ├── client_secret.json    # OAuth2 credentials
│   ├── token.json            # Google auth token
│   └── spreadsheet_cache.json
├── logos/                    # Logo aziende (gitignore)
│   └── .gitkeep
├── uploads/                  # PDF temporanei (gitignore)
├── sample_invoices/          # Fatture esempio
├── requirements.txt          # Dipendenze Python
├── .env                      # Configurazione (gitignore)
├── .env.example              # Template configurazione
└── README.md

---

📈 Limitazioni Note

Accuratezza Estrazione

Metodo	PDF Digitali	PDF Scansionati	Foto
Tesseract	>90%	70-85%	60-80%
Gemini Flash	96-98%	92-95%	85-90%
Gemini Pro	98-99%	95-98%	90-95%
Claude 4.5	98-99%	95-98%	90-95%
Auto	92-96%	88-93%	82-90%

Limiti Tecnici

• Rate limit Google Sheets: 100 richieste / 100 secondi
• Dimensione file: max 50MB per upload
• Concorrenza: 1 elaborazione alla volta per sessione
• Formati layout: Ottimizzato per layout IT/DE/CH/UK/US standard
• ⚠️ Credenziali Google condivise: Tutte le aziende condividono lo stesso token OAuth Google. Solo admin può configurare l'account Google. Per isolamento completo, considerare deploy separati per azienda.

Best Practices

✅ Raccomandato:

• Usa PDF digitali (non scansioni) quando possibile
• Modalità Auto per bilanciare costo/accuratezza
• Foto con buona illuminazione e messa a fuoco
• Verifica sempre dati estratti prima dell'export

❌ Evita:

• Foto sfocate o con riflessi
• Scansioni < 200 DPI
• PDF con layout molto personalizzati (senza AI)

---

🔐 Sicurezza e Privacy

Dati Protetti

Il file .gitignore protegge:

• ✅ .env (token, API keys, sheet_id)
• ✅ credentials/ (OAuth2 Google)
• ✅ logos/ (immagini aziendali)
• ✅ uploads/ (fatture caricate)

Token di Autenticazione

• Generati con secrets.token_hex(16) (32 char hex)
• Validazione server-side per ogni richiesta
• Salvati in localStorage del browser
• Nessuna scadenza (sicurezza tramite oscurità)

Gestione Credenziali

# Verifica che .env sia gitignored
git check-ignore .env  # Deve ritornare: .env

# Genera SECRET_KEY sicuro
python -c "import secrets; print(secrets.token_hex(32))"

Raccomandazioni Produzione

1. Cambia SECRET_KEY in .env
2. Usa HTTPS (reverse proxy con nginx/Caddy)
3. Limita API keys (usage limits su console provider)
4. Backup .env in luogo sicuro (password manager)
5. Aggiorna dipendenze regolarmente:

pip list --outdated
pip install --upgrade -r requirements.txt

---

📞 Supporto

Problemi o Bug

Apri una issue su GitHub:

• Repository: https://github.com/cerro333/fatture-ocr_Claude-code
• Includi: versione Python, OS, log errore, steps per riprodurre

Contributi

Pull requests benvenute! Per modifiche major, apri prima una issue per discutere.

Licenza

Uso personale e aziendale consentito. Non redistribuire senza autorizzazione.

---

🙏 Credits

Sviluppato con:

• Flask - Web framework
• Tesseract OCR - OCR engine
• Google Gemini - AI OCR
• Anthropic Claude - AI reasoning
• Google Sheets API - Data export
• Bootstrap - UI framework

---

⭐ Se questo progetto ti è utile, lascia una stella su GitHub!

Made with ❤️ for accountants and businesses