OpenFatture

Open-source electronic invoicing for Italy.

A local-first, CLI-first invoicing workspace for Italian freelancers and small businesses. Generate FatturaPA invoices, manage financial workflows, and automate repetitive tasks with optional AI assistance. Your data remains under your control.

Quick start · Capabilities · Feature status · Documentation · Issues

Why OpenFatture?

Italian electronic invoicing involves more than producing a PDF: structured XML, customer records, delivery notifications, and payment tracking must fit together. OpenFatture brings these workflows into a terminal workspace you can inspect and extend.

• Work locally. Keep the default SQLite database and generated documents on your machine. Invoice calculations, XML generation, and PDF rendering do not require an LLM or a cloud account.
• Choose how to work. Use deterministic client and invoice commands, or add an assistant that calls application services through registered tools.
• Automate around your workflow. Reuse domain services, CSV and bank imports, domain events, and user hook scripts.

Built for freelancers and small studios comfortable in a terminal. This repository has no browser frontend or web application surface; it is distinct from OpenFatture Cloud.

Quick Start

Requires Python 3.12+, Git, and uv. Start with the core install; AI, retrieval, and forecasting are separate extras.

git clone https://github.com/gianlucamazza/openfatture.git
cd openfatture
uv sync --frozen
uv run openfatture init
uv run openfatture status

The setup wizard creates local storage and collects company settings. Use your actual fiscal details and tax regime; AI configuration can be skipped. status --json reports local readiness and next steps, without contacting providers or verifying SDI delivery.

Create a draft and preview it without AI

Run this example in a fresh demo database. On an existing database, replace 1 with the client and invoice IDs printed by the create commands. The sample client uses a demo VAT number and is for a draft preview only.

uv run openfatture cliente create --name "Demo Client" --piva 12345678903
uv run openfatture fattura create --client 1 --note "Demo draft"
uv run openfatture fattura add-line --invoice 1 \
  --desc "Software consulting" --qty 3 --price 90 --iva 22
uv run openfatture fattura show 1
uv run openfatture fattura generate-pdf 1 --output demo-invoice.pdf

This creates a draft for €270 plus €59.40 VAT and a human-readable PDF; it does not transmit an invoice. The VAT rate is illustrative. Complete and verify both issuer and customer fiscal details before preparing a real invoice.

Explore the current command surface with uv run openfatture --help and uv run openfatture fattura --help.

What You Can Do

Core capabilities live in application/domain packages. The CLI exposes a subset; other workflows use services or optional assistant tools, rather than a command for every operation.

XML generation and validation are separate concerns. The current fattura generate-xml command calls generation with validation disabled. The service layer and validate_invoice_xml assistant tool provide validation; a generated file alone is not evidence of XSD validity or SDI acceptance. See XSD validation.

AI-Assisted Workflows

Install only the assistant stack when you need natural-language access:

uv sync --frozen --extra ai

Configure AI_PROVIDER, AI_MODEL, and the provider credential or local endpoint using the configuration guide. Supported provider adapters are OpenAI, Anthropic, and Ollama. Ollama requires a running local service and an installed model; the extra does not install either.

Once configured, start with read-only requests:

uv run openfatture status --json
uv run openfatture assistant "List my clients"
uv run openfatture assistant "Show invoice 1 and its line items"
uv run openfatture

The assistant interprets the request; registered tools call application services for business operations. Model responses are not proof that an operation ran: inspect tool outcomes and the resulting records or files. Review fiscal inputs and results yourself.

Tool access is controlled by AI_ENABLED_TOOLS, which defaults to read-only invoice/client lookups. Creation, reconciliation, and export requests need their respective tools enabled. AI_ENABLED_TOOLS=all enables non-transmit tools; it does not enable SDI/PEC send. Sending requires explicit opt-in for send_invoice_to_sdi.

AI_TOOLS_REQUIRE_CONFIRMATION=true is the default. Tools marked as requiring confirmation need human approval: a terminal can prompt, while noninteractive callers without approval are refused. The model cannot approve itself. Turning this setting off skips confirmation but still requires transmit-tool opt-in. See AI architecture for runtime details.

Architecture

flowchart TD
    CLI["Deterministic CLI"] --> APP["Application services"]
    TERM["Terminal assistant (optional)"] --> AI["AI runtime and allowed tools"]
    AI --> APP
    AI <--> LLM["Local or cloud LLM provider"]
    APP --> DOMAIN["Billing, SDI, payments, PDF"]
    DOMAIN --> STORE["Database and document files"]
    DOMAIN --> EVENTS["Domain events"]
    EVENTS --> AUDIT["Event persistence and hooks"]
    DOMAIN --> PEC["Configured PEC transport"]

The CLI and AI tools route business operations through application services. Core storage, billing, payment, SDI, and PDF modules remain usable without optional model dependencies. See architecture and core, extras, and extensions.

Data Ownership & Security

• Persistence: SQLite is the default; DATABASE_URL, DATA_DIR, and ARCHIVIO_DIR control storage. init writes a user profile; status shows configured paths. Persistent assistant sessions are also local files.
• External data flow: local-first does not mean every feature is offline. Cloud LLM requests can include prompts and tool results; PEC transmits invoice data. Choose providers and enabled tools accordingly.
• Audit boundaries: emitted domain events can be persisted to the database. This is an operational audit trail, not a tamper-proof archive or a guarantee that every action is durably recorded; persistence failures are logged without aborting the business operation.
• Credentials and extensions: protect local profiles, secrets, and signing material; never commit them. Diagnostic masking is not encryption at rest. Hook scripts execute local code and should be trusted before enabling them.
• Retention: back up the database and documents. A local document archive does not by itself establish compliant long-term preservation (conservazione a norma).

See the configuration guide and security policy for settings and vulnerability reporting.

Feature Status

The package identifies itself as 2.4.0, with Beta metadata. These labels describe implementation and dependencies, not certification or service guarantees.

Compatibility and quality evidence

The test workflow defines Linux and macOS jobs on Python 3.12/3.13, plus a core-only Linux smoke/test job. These are configured CI targets, not a claim that every run passes. Follow the live Tests badge for results; Windows is not in this workflow's test matrix.

The test suite covers CLI, billing, XML, PDF, payment, events, and hooks. Coverage floors are 49% for the full package and 75% for payments, as configured in pyproject.toml and the payment workflow. Floors are thresholds, not measured coverage results. Historical reports are not current quality evidence.

Documentation

Some deeper guides retain earlier CLI or release descriptions. Prefer the current command help and package metadata when they differ; material under docs/history/ is historical context.

Development & Contributing

The full development stack includes optional features and test/quality tools:

uv sync --frozen --all-extras
uv run python -m pytest -q
uv run ruff check .
uv run ruff format --check .
uv run mypy openfatture/

The default pytest selection excludes performance, benchmark, slow, end-to-end, and Ollama tests. Those need explicit selection and, where applicable, external services. See contributing for the development workflow.

Report bugs or propose improvements through GitHub issues. OpenFatture is released under the MIT License.