openfatture

OpenFatture 2.3.0

Highlights

Nota di credito (TD04) support with full FatturaPA XML linkage via DatiFattureCollegate
Real CLI: openfatture fattura generate-xml now actually generates FatturaPA XML (no longer a stub)
Slim Alembic migration for TD04 document linkage columns
Comprehensive test coverage for credit note workflows and XML generation

What’s New

Nota di Credito (TD04)

OpenFatture 2.3.0 adds first-class support for Italian credit notes (nota di credito, document type TD04):

Application command: create_nota_credito_from_fattura creates a credit note from an existing invoice
CLI command: openfatture fattura create-credit-note --from-invoice <id> [--note "reason"] [--full]
FatturaPA XML: TD04 documents include DatiFattureCollegate element linking back to the original invoice
Database schema: Three new optional columns (fattura_originale_id, fattura_originale_numero, fattura_originale_data) track the relationship
Workflow: Credit notes copy line items from source invoice (with negated amounts for full refunds), maintain client/fiscal data consistency, and generate compliant XML for SDI submission

Real XML Generation CLI

The openfatture fattura generate-xml command is now a production-ready tool:

Before (2.2.0)	After (2.3.0)
Stub that prints “not yet implemented” message	Real XML generation via `InvoiceService` and `FatturaPABuilder`
Tells user to use the assistant	Honors `--output` and `--dry-run` flags
No tests	Full test coverage (normal, custom output, dry-run, error cases)

# Generate XML to default path (archivio/xml/IT<partita-iva>_<numero>.xml)
openfatture fattura generate-xml <invoice-id>

# Generate XML to custom path
openfatture fattura generate-xml <invoice-id> --output /path/to/custom.xml

# Preview XML without writing to disk
openfatture fattura generate-xml <invoice-id> --dry-run

The command uses the same battle-tested XML builder that the assistant and application layer use—no mocks, no fake SDI, no stub logic.

Upgrade Notes

Database Migration

This release includes an Alembic migration for TD04 linkage columns. If you manage database migrations manually, run:

alembic upgrade head

The migration adds three nullable columns to the fatture table. Existing invoices are unaffected; the columns are only populated for credit notes.

CLI Command Change

The generate-xml command behavior has changed:

Before: Printed a message saying XML generation is not implemented and suggested using the assistant
After: Actually generates FatturaPA XML and writes it to disk (or displays it with --dry-run)

If you had scripts or workflows that relied on the old stub behavior, update them to expect real XML output.

Verification

Credit Note Workflow

# Create a credit note from an existing invoice
openfatture fattura create-credit-note --from-invoice 42 --note "Customer cancellation"

# Generate XML for the credit note (will include DatiFattureCollegate)
openfatture fattura generate-xml <credit-note-id> --output nota_credito.xml

# Verify TD04 document type and linkage in XML
grep -A5 "DatiFattureCollegate" nota_credito.xml

XML Generation

# Test normal generation
openfatture fattura generate-xml 1

# Test custom output path
openfatture fattura generate-xml 1 --output /tmp/test_invoice.xml

# Test dry-run mode (no file written, XML printed to console)
openfatture fattura generate-xml 1 --dry-run

Test Suite

# Run credit note integration tests
uv run python -m pytest tests/integration/test_nota_credito_workflow.py -xvs

# Run CLI generate-xml tests
uv run python -m pytest tests/cli/test_fattura_commands.py -k generate_xml -xvs

# Run full test suite
uv run python -m pytest -q

Future Work

This release does not include:

TUI (text user interface) improvements (#44)
MCP (Model Context Protocol) server (#44)
Web interface (#44)
PagoPA QR code generation (#41)
Public multi-agent workflows (#38)

These remain product-decision items and are not scheduled for implementation. The 2.3.0 focus is on honesty in documentation (TD04 is shipped, not planned) and closing the one real CLI gap (generate-xml).

Tag and Release

The git tag and GitHub release for 2.3.0 will be created by the coordinator after PR merge. Do not create tags or publish PyPI packages manually.

This site is open source. Improve this page.