Metadata-Version: 2.4
Name: erechnung
Version: 0.1.0
Summary: ZUGFeRD/Factur-X Rechnungen (EN 16931, PDF/A-3, DIN 5008) einfach in Python erzeugen.
Author: Franziska
License-Expression: MIT
Project-URL: Homepage, https://github.com/frnzskac/erechnung
Keywords: zugferd,facturx,invoice,erechnung,en16931,din5008,pdf
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: reportlab>=4.0
Requires-Dist: factur-x>=3.0
Requires-Dist: pikepdf>=8.0
Requires-Dist: lxml>=5.0
Requires-Dist: pillow>=10.0
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Dynamic: license-file

# erechnung

Generate ZUGFeRD/Factur-X invoices (EN 16931, PDF/A-3, DIN 5008) in Python with ease:
one data object in, one finished e-invoice out. Works without Django or any other
framework.

## Features

- Complete ZUGFeRD file: visible PDF/A-3 plus embedded EN 16931 XML (CII).
- DIN 5008 layout with logo, custom font, and freely chosen brand colors.
- Seven invoice types: standard invoice, small-business invoice, deposit invoice,
  final invoice, recurring invoice, cancellation invoice, credit note.
- Discount and surcharge per line item and on the whole invoice, early-payment discount.
- Reverse charge (§ 13b) and intra-Community supply as simple switches.
- Switchable profile: `EN16931` (default) or `XRECHNUNG`.
- German or American English, including number and date formatting.

## Installation

```bash
pip install erechnung
```

## Quickstart

```python
from decimal import Decimal
from datetime import date
from erechnung import Invoice, Seller, Customer, LineItem, Skonto

inv = Invoice(
    seller=Seller("Sample GmbH & Co. KG", "Sample Street", "1", "00000", "Sample City",
                  tax_number="000/000/00000", iban="DE00...", bic="MUSTDE00XXX"),
    customer=Customer(first_name="Max", last_name="Mustermann", street="Sample Street",
                      house_number="12", postal_code="00000", city="Sample Town"),
    line_items=[LineItem("Sample product 1", Decimal("2"), Decimal("9.99")),
                LineItem("Voucher booklet", Decimal("1"), Decimal("14.00"), tax_rate=Decimal("7"))],
    invoice_number="0001",
    service_date=date(2026, 8, 5),
    logo=True, logo_path="logo.png",
    skonto=Skonto(days=7, percent=Decimal("2")),
)
inv.zugferd_file("invoice.pdf")   # finished ZUGFeRD file
```

For a plain PDF without embedded XML, use `inv.pdf_bytes()`.

## Key parameters

| Parameter | Meaning | Default |
|---|---|---|
| `invoice_type` | Invoice type (`InvoiceType.STANDARD`, `DEPOSIT`, `FINAL`, `RECURRING`, `CANCELLATION`, `CREDIT_NOTE`) | `STANDARD` |
| `title` | Custom heading shown instead of the automatic label (`None`=automatic, e.g. "Rechnung"/"Invoice"; `str`=custom, e.g. "Rechnung") | `None` |
| `kleinunternehmer` | § 19 UStG, no VAT charged | `False` |
| `reverse_charge` / `intra_community` | § 13b or intra-Community supply, 0% VAT | `False` |
| `profile` | `Profile.EN16931` or `Profile.XRECHNUNG` | `Profile.EN16931` |
| `buyer_reference` | Buyer reference / Leitweg-ID (BT-10, required for XRechnung) | `""` |
| `intro` | Cover text after the salutation (`None`=default text, `str`=custom, `False`=none) | `None` |
| `language` | `Language.DE` or `Language.EN` (translates the whole PDF) | `Language.DE` |
| `logo` / `logo_path` | Logo top right, max. 2.3 cm height | `False` |
| `font` | Custom `Font` (regular/bold/italic) | `None` (Arimo) |
| `brand_style` | `BrandStyle` for table colors and the header bar | Gray from the DIN 5008 template |
| `fold_marks` | Fold marks per DIN 676 | `True` |
| `discounts` / `surcharges` | Discounts/surcharges per line item or on the whole invoice | `[]` |
| `skonto` | `Skonto(days, percent)` | `None` |
| `payment_method` / `payment_reference` | Payment method and reference (note text + BT-81/BT-83) | `None` |

Missing required fields raise an `InvoiceError` listing all of them.

## Background: ZUGFeRD, EN 16931, and Business Terms

A ZUGFeRD/Factur-X e-invoice is a single PDF/A-3 file that contains both a
human-readable document and a machine-readable XML (CII, Cross Industry Invoice).
The European standard EN 16931 defines which information an invoice must contain;
each piece of information carries an identifier, a Business Term (e.g. BT-1 for the
invoice number). This library covers the core fields of EN 16931; the full mapping
between Business Term and library field is in [docs/fields.md](docs/fields.md).

## Requirements and conformance

- Python 3.10+.
- PDF/A-3 conformance (OutputIntent, ICC color profile) is produced directly via
  `pikepdf`, with no external dependency such as Ghostscript.
- Layout follows DIN 5008 (a design standard with no automated conformance check);
  content follows EN 16931, checkable e.g. with the KoSIT validator or Mustang;
  PDF/A-3 conformance e.g. with veraPDF.
- The `XRECHNUNG` profile is modeled: electronic seller/buyer addresses
  (BT-34 `Seller.email` / BT-49 `Customer.email`) and the Leitweg-ID (BT-10
  `Invoice.buyer_reference`); missing XRechnung-required fields raise an
  `InvoiceError`. A step-by-step guide is in [docs/guide.md](docs/guide.md).

## Legal Compliance Notice

This library supports the creation of ZUGFeRD/XRechnung-compliant invoices to
the best of our knowledge at the time of publication. It does not constitute
legal or tax advice. Users are responsible for ensuring that generated
invoices meet the currently applicable legal requirements. When in doubt,
consult a tax advisor.

## License

MIT
