Fatture in Cloud — Connector

Factum → Fatture in Cloud (FIC) Connector

Status: Architectural proposal · Q4 2026 Roadmap

This document describes the architecture, design decisions, and go-to-market strategy for a dedicated connector between Factum Parse API and Fatture in Cloud v2 (FIC), automating the recording of expenses from PDF/XML files — particularly foreign SaaS receipts, cloud hosting, domains, and TD17/18/19 self-invoices.

1. Problem

Manual bookkeeping of incoming invoices has three recurring pain points:

Pain Point	Example	Cost
Manual transcription	Typing a $23.40 DigitalOcean receipt into FIC	3-5 min per invoice × dozens per month
Foreign suppliers without Italian VAT	AWS bill in USD requires TD17/19 self-invoice	Tax law research + manual reverse charge calculation
Unstructured formats	SaaS PDFs that aren’t FatturaPA, XML, or EU e-invoice	Manual data entry or inaccurate OCR

Factum Parse API already solves the third problem (parsing any PDF/XML into validated JSON). The FIC connector closes the loop by solving the first and second as well.

2. Recommended Architecture

Choice: Local Daemon / Tray Watcher (Option A)

This is the only architecture that guarantees:

Zero FIC credential exposure: Fatture in Cloud API keys live in a local .env file, never transmitted to Factum or third parties.
Downloads folder monitoring: user downloads a SaaS invoice → the watcher sees it → Factum parses it → FIC records it. Zero clicks.
Offline queue: if the network drops, files stay in a local SQLite queue. On reconnection, Factum processes and FIC records.
Cross-platform: macOS, Windows, Linux via Tauri or CLI.

Comparison with alternatives

Option	Ease of use	Dev speed	Security	Key trade-off
A. Local tray watcher ✨	High (drag & drop)	Medium (6-8 weeks)	Maximum	Requires native installation
B. Chrome extension	Medium	Low	Medium-low	FIC CSP blocks DOM injection
C. Standalone web app	Low	High	Low	XSS surface on LocalStorage

Modular architecture

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

3. Tax Handling

3.1 Foreign supplier mapping

Scenario	FIC field	Factum strategy
EU supplier with foreign VAT	`vat_number`	Use VAT from PDF (e.g. `DE123456789`) + `country_iso`
Extra-EU supplier no VAT	`tax_code` empty	`country_iso = "XX"` + `name` + `locality`
Italian VAT (rare for SaaS)	`vat_number`	Standard, no special treatment
Self-invoice (TD17/18/19)	`entity_type = "others"` + `is_autofattura = true`	Factum detects missing Italian VAT + foreign service = self-invoice trigger

Robust default rule: if Factum cannot find a valid Italian VAT number in the PDF, it marks the entity as entity_type: "others" with the supplier’s country_iso. The user can override with a saved FIC entity (partial name/email match).

3.2 Currency recognition

Factum already extracts total and currency (ISO 4217). The flow:

FIC v2 accepts currency as EUR, USD, GBP → passthrough from Factum.
Auto FX: FIC calculates the EUR exchange rate at recording time. Factum delegates FX calculation to FIC.
Totals: Factum maps amount_net / amount_vat / amount_gross to corresponding FIC fields.
has_iva: if the document has 0 VAT / out-of-scope (e.g. US SaaS), Factum sets has_iva = false and FIC does not tax it.

3.3 Expense categories

Document type	Suggested FIC category	Default account
Hosting / Cloud (AWS, Hetzner, DO)	`Hosting and cloud services`	IT service costs
SaaS (GitHub, Notion, Slack)	`Software SaaS subscriptions`	Service expenses
Domains / DNS	`Domains and registrations`	IT service costs
Advertising (Google Ads, Meta)	`Advertising and marketing`	Advertising expenses
Foreign supplier self-invoice	`Purchases from non-residents`	—

Strategy: Factum categorizes by vendor keyword match (regex on supplier name + description). Users can customize mapping in a local YAML file (~/.factum-fic/categories.yaml). If no match, it falls back to "Other costs" + needs_review flag.

3.4 Expense vs Self-invoice

Condition	FIC type	Action
PDF with Italian supplier VAT	`Expense document / purchase`	Direct recording
PDF with foreign supplier + service	`Foreign self-invoice` (draft)	Create pre-filled draft
XML FatturaPA	`Expense document / purchase`	Direct recording

For self-invoices, the connector prepares:

type = "expense" with is_autofattura = true flag
Supplier with entity_type = "others"
VAT calculation with reverse charge / split payment (based on supplier country)
Legal description: "Self-invoice under Art. 17-ter DPR 633/72 for purchase from {supplier}"

4. Recommended Stack

Layer	Technology	Rationale
Core	Python 3.13 + httpx (async)	Reuses Factum Parse SDK, httpx already in backend
CLI	Typer + Rich	Auto-generated CLI docs, progress bars
File watcher	`watchdog` + `inotify` / `FSEvents`	Native filesystem monitoring without polling
Desktop/Tray	Tauri 2 (Rust + Vue 3)	~5 MB signed binary, cross-platform
Local storage	SQLite (via SQLAlchemy)	Offline queue, sync status log
FIC API	httpx async client on FIC v2 OpenAPI	Rate limiting, retry with backoff
Config	pydantic-settings + YAML	Typed, validated, user overridable

Separable modules

factum-fic-core       # Installable Python library: pipeline + FIC bridge
factum-fic-cli        # Thin CLI wrapper (pip install factum-fic)
factum-fic-desktop    # Tauri app (depends on core)

The core can be used from n8n, CI/CD pipelines, or custom scripts. CLI is free. Desktop is premium.

5. Go-to-Market / Packaging

Strategy: Three-tier freemium

Tier	Channel	Price	What’s included
Open Source Core	PyPI + GitHub	Free	CLI `factum-fic process`, folder watcher, FIC read bridge
Factum FIC Plus	Lemon Squeezy checkout	€9/month	Desktop tray, auto-monitoring, offline queue, category mapping, auto self-invoices
Enterprise	Direct invoicing	€49/month	Multi-tenant (multiple FIC companies), 99.9% SLA, ZDR audit trail

Why it works

Free core as lead gen: anyone installing pip install factum-fic experiences the value → converts to Plus.
Plus solves real pain: automated self-invoicing is the killer feature for freelancers with foreign clients.
Enterprise sells to accounting firms: multi-tenant means managing 20 clients from a single tray.

Differentiation from native FIC

Feature	Native FIC	FIC + Factum Parse
FatturaPA XML reading	✅	✅ Automatic
SaaS receipt PDF reading	❌ Basic OCR	✅ Deterministic + AI parsing
Foreign currency recognition	❌ Manual	✅ Automatic
TD17/18/19 self-invoice	❌ Manual only	✅ Pre-filled draft
Zero Data Retention	❌	✅ GDPR ZDR
Auto categorization	❌ Manual	✅ Rules + AI
Price	Included in FIC	€9/month + Factum usage

6. Roadmap

Phase	Duration	Deliverable
1. CLI MVP	2 weeks	`factum-fic watch ~/Downloads` — watcher + parsing + FIC recording
2. Tray app	4 weeks	Tauri desktop with tray icon, notifications, GUI config
3. Self-invoice	2 weeks	Automatic TD17/18/19 logic + pre-filled drafts
4. Release	1 week	Lemon Squeezy checkout, docs, landing page