Fatture in Cloud — Connettore

Connettore Factum → Fatture in Cloud (FIC)

Stato: Proposta architetturale · Roadmap Q4 2026

Questo documento descrive l’architettura, le scelte progettuali e la strategia di go-to-market per un connettore dedicato tra Factum Parse API e Fatture in Cloud v2 (FIC), che automatizzi la registrazione di spese da PDF/XML — in particolare ricevute SaaS estere, hosting cloud, domini e autofatture TD17/18/19.

1. Problema

La contabilità manuale delle fatture passive presenta tre dolori ricorrenti:

Dolore	Esempio	Costo
Trascrizione manuale	Digitare su FIC i dati di una ricevuta DigitalOcean ($23,40)	3-5 minuti per fattura × decine al mese
Fornitori esteri senza P.IVA italiana	Una fattura AWS in USD va registrata come autofattura TD17/19	Ricerca normativa + calcolo manuale reverse charge
Formati non strutturati	PDF di SaaS che non è FatturaPA, né XML, né e-invoice UE	Scartamento manuale o OCR impreciso

Factum Parse API risolve già il terzo problema (parsing di qualsiasi PDF/XML in JSON validato). Il connettore FIC chiude il loop risolvendo anche il primo e il secondo.

2. Architettura Consigliata

Scelta: Daemon locale / Tray watcher (Opzione A)

È l’unica architettura che garantisce:

Zero esposizione credenziali FIC: le API key di Fatture in Cloud vivono in un .env locale, mai trasmesse a Factum o a terzi.
Monitoraggio cartella Download: l’utente scarica la fattura SaaS → il watcher vede il file → Factum lo analizza → FIC lo registra. Zero click.
Coda offline: se la rete cade, i file restano in coda locale (SQLite). Alla riaccensione, Factum processa e FIC registra.
Compatibilità cross-platform: macOS, Windows, Linux via Tauri o CLI.

Confronto con alternative

Opzione	Facilità utente	Velocità sviluppo	Sicurezza	Trade-off critico
A. Tray watcher locale ✨	Alta (drag & drop)	Media (6-8 settimane)	Massima	Richiede installazione nativa
B. Estensione Chrome	Media	Bassa	Media-bassa	CSP di FIC blocca injection DOM
C. Web app standalone	Bassa	Alta	Bassa	XSS surface su LocalStorage

Architettura a moduli

┌─────────────────────────────────────────────────────┐
│                   factum-fic                          │
│                                                       │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────┐  │
│  │  File Watcher │  │  Factum Pipe │  │  FIC Bridge │  │
│  │  (watchdog)  │──▶│  (httpx)    │──▶│  (httpx)   │  │
│  │  hotfolder/  │  │  parsing +   │  │  entità +   │  │
│  │  polling FS  │  │  caching     │  │  documenti  │  │
│  └──────────────┘  └──────────────┘  └───────┬────┘  │
│                                               │       │
│  ┌──────────────┐  ┌──────────────┐          │       │
│  │  SQLite Queue │  │  Config YAML  │         │       │
│  │  (coda + log) │  │  (mappatura) │         │       │
│  └──────────────┘  └──────────────┘         │       │
│                                              ▼       │
│                                    Fatture in Cloud   │
│                                    (API v2)           │
└─────────────────────────────────────────────────────┘

3. Gestione Fiscale

3.1 Mappatura fornitori esteri

Scenario	Campo FIC	Strategia Factum
Fornitore UE con VAT estera	`vat_number`	Usa il VAT dal PDF (es. `DE123456789`) + `country_iso`
Fornitore extra-UE senza VAT	`tax_code` vuoto	`country_iso = "XX"` + `name` + `locality`
P.IVA italiana (raro per SaaS)	`vat_number`	Normale, nessun problema
Autofattura (TD17/18/19)	`entity_type = "others"` + `is_autofattura = true`	Factum rileva assenza P.IVA italiana + servizio estero = trigger autofattura

Regola di default robusta: se Factum non trova una P.IVA italiana valida nel PDF, marca come entity_type: "others" con country_iso dal fornitore. L’utente può sovrascrivere con una entity salvata in FIC (match per nome/email parziale).

3.2 Riconoscimento valute

Factum già estrae total e currency (ISO 4217). Il flusso:

FIC v2 accetta currency come EUR, USD, GBP → pass-through da Factum.
Cambio automatico: FIC calcola il cambio EUR al momento della registrazione. Factum delega il calcolo a FIC.
Totali: Factum mappa amount_net / amount_vat / amount_gross sui campi FIC corrispondenti.
has_iva: se il documento ha IVA 0 / fuori campo (es. SaaS USA), Factum setta has_iva = false e FIC non tassa.

3.3 Categorie di spesa

Tipo documento	Categoria FIC suggerita	Conto di default
Hosting / Cloud (AWS, Hetzner, DO)	`Servizi hosting e cloud`	Costi per servizi informatici
SaaS (GitHub, Notion, Slack)	`Abbonamenti software SaaS`	Spese per servizi
Domini / DNS	`Domini e registrazioni`	Costi per servizi informatici
Pubblicità (Google Ads, Meta)	`Pubblicità e marketing`	Spese di pubblicità
Autofattura fornitore estero	`Acquisti da soggetti non residenti`	—

Strategia: Factum categorizza per vendor keyword match (regex su nome fornitore + description). L’utente può personalizzare la mappatura in un file YAML locale (~/.factum-fic/categories.yaml). Se non matcha, usa "Altri costi" + marca needs_review.

3.4 Spesa vs Autofattura

Condizione	Tipo FIC	Azione
PDF con P.IVA italiana fornitore	`Documento di spesa/acquisto`	Registra diretto
PDF con fornitore estero + servizio	`Autofattura estera` (bozza)	Crea bozza precompilata
XML FatturaPA	`Documento di spesa/acquisto`	Registra diretto

Per le autofatture, il connettore prepara:

type = "expense" con flag is_autofattura = true
Fornitore con entity_type = "others"
Calcolo IVA con reverse charge / split payment (in base al paese estero)
Descrizione legale: "Autofattura art. 17-ter DPR 633/72 per acquisto da {fornitore}"

4. Stack Consigliato

Layer	Tecnologia	Perché
Core	Python 3.13 + httpx (asincrono)	Riutilizza Factum Parse SDK, httpx già in backend
CLI	Typer + Rich	Docstring CLI autogenerata, progress bar
File watcher	`watchdog` + `inotify` / `FSEvents`	Monitoraggio nativo senza polling
Desktop/Tray	Tauri 2 (Rust + Vue 3)	Binary ~5 MB, firmabile, cross-platform
Storage locale	SQLite (via SQLAlchemy)	Coda offline, log sincronizzazione
API FIC	httpx client asincrono su OpenAPI FIC v2	Rate limit, retry con backoff
Config	pydantic-settings + YAML	Tipizzato, validato, override utente

Moduli separabili

factum-fic-core       # Libreria Python installabile: pipeline + bridge FIC
factum-fic-cli        # CLI thin wrapper (pip install factum-fic)
factum-fic-desktop    # Tauri app (dipende da core)

Vantaggio: il core è usabile da n8n, script interni, CI/CD. La CLI è free. Il desktop è premium.

5. Go-to-Market / Packaging

Strategia: Freemium a tre livelli

Livello	Canale	Prezzo	Cosa include
Open Source Core	PyPI + GitHub	Gratuito	CLI `factum-fic process`, watcher cartella, bridge FIC in lettura
Factum FIC Plus	Lemon Squeezy checkout	€9/mese	Desktop tray, monitoraggio automatico, coda offline, mapping categorie, autofatture automatiche
Enterprise	Fatturazione diretta	€49/mese	Multi-tenant (più aziende FIC), SLA 99.9%, audit trail ZDR

Perché funziona

Core gratuito come lead gen: chi installa pip install factum-fic vede il valore → converte a Plus.
Plus risolve il dolore reale: autofattura automatica è killer feature per freelance con clienti esteri.
Enterprise si vende agli studi commercialisti: multi-tenant significa gestire 20 clienti da un’unica tray.

Differenziazione da FIC nativo

Funzionalità	FIC nativo	FIC + Factum Parse
Lettura XML FatturaPA	✅	✅ Automatica
Lettura PDF ricevuta SaaS	❌ OCR base	✅ Parsing deterministico + AI
Riconoscimento valuta estera	❌ Manuale	✅ Automatico
Autofattura TD17/18/19	❌ Solo manuale	✅ Bozza precompilata
Zero Data Retention	❌	✅ GDPR ZDR
Categorizzazione automatica	❌ Manuale	✅ Regole + AI
Prezzo	Incluso in FIC	€9/mese + consumo Factum

6. Roadmap

Fase	Durata	Deliverable
1. MVP CLI	2 settimane	`factum-fic watch ~/Downloads` — watcher + parsing + registrazione FIC
2. Tray app	4 settimane	Desktop Tauri con tray icon, notifiche, configurazione GUI
3. Autofattura	2 settimane	Logica TD17/18/19 automatica + bozze precompilate
4. Release	1 settimana	Lemon Squeezy checkout, documentazione, landing page