PyCheval – Factur-X/ZUGFeRD parsing and generation library for Python

Factur-X (also called ZUGFeRD in Germany) is a Franco-German standard for electronic invoices. Structured XML data is embedded in PDF-A/3 files, allowing invoices to be processed automatically while still being displayed in standard PDF readers. Factur-X supports EN 16931, the European standard for electronic invoicing.

See the Factur-X website (French) or FeRD website (German) for more information.

This library supports reading and writing PDF and XML files according to Factur-X Version 1.08 (aka ZUGFeRD 2.4). The following Factur-X profiles are currently supported:

• Minimum
• Basic WL
• Basic
• EN 16931 (Comfort)

Extended and XRechnung profiles are not yet supported.

Warning: This library is still in early development. The API may change frequently, and not all features are implemented yet.

Usage

Installation

You can install PyCheval from PyPI:

pip install PyCheval

Generating Factur-X

PyCheval supports several Factur-X profile levels, each with different levels of detail and complexity. First, you need to create an instance of the appropriate profile class. Then, you can pass that instance to one of the generation functions.

from datetime import date
from pycheval import EN16931Invoice, Money, generate_xml

invoice = EN16931Invoice(
    invoice_number="2021-123",
    invoice_date=date(2021, 4, 13),
    grand_total=Money("100.00", "EUR"),
    ...  # See the class documentation for all required and optional fields.
)
xml_string = generate_xml(invoice)

To embed the generated XML into a PDF, you can use the embed_invoice_in_pdf function:

from pathlib import Path
from pycheval import embed_invoice_in_pdf

invoice = ...
pdf_bytes = embed_invoice_in_pdf("invoice.pdf", invoice)
Path("invoice_with_facturx.pdf").write_bytes(pdf_bytes)

Parsing Factur-X PDF files

PyCheval can parse Factur-X PDF files and extract the embedded invoice data. The parser will return an instance of the appropriate profile class.

from pycheval import parse_pdf

invoice = parse_pdf("invoice.pdf")  # Returns MinimumInvoice or a subclass

Printing invoices

To display a formatted Factur-X invoice in the terminal, use the format_invoice_as_text() function:

from pycheval import format_invoice_as_text

invoice = EN16931Invoice(...)
print(format_invoice_as_text(invoice))

License and Warranty

Copyright © ZFutura GmbH

This project is licensed under the Apache License 2.0.

Disclaimer: The software is provided "as is", without warranty of any kind. The authors are not liable for any damages arising from the use of this software. In particular, the authors do not guarantee that invoices generated or parsed by this library will be valid or compliant with any standards, nor that they are suitable for any specific purpose.

Important: It is the user's responsibility to ensure that generated invoices meet all legal and regulatory requirements for their jurisdiction.

See the LICENSE file for the complete disclaimer and license terms.