search

akretion / factur-x

Python lib for Factur-X, the e-invoicing standard for France and Germany
Other
187 stars 57 forks source link
e-invoice odoo

readme

Factur-X and Order-X Python library

Factur-X is a Franco-German e-invoicing standard which complies with the European e-invoicing standard EN 16931 <https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/Obtaining+a+copy+of+the+European+standard+on+eInvoicing>. The Factur-X specifications are available on the FNFE-MPE website <http://fnfe-mpe.org/factur-x/> in English and French. The Factur-X standard is also called ZUGFeRD 2.2 in Germany <https://www.ferd-net.de/standards/zugferd-2.2/zugferd-2.2.html>_.

Order-X is the equivalent of Factur-X for purchase orders. The Order-X specifications are available in English on the FNFE-MPE website <https://fnfe-mpe.org/factur-x/order-x/> and on the FeRD website <https://www.ferd-net.de/standards/order-x/index.html>.

The main feature of this Python library is to generate Factur-X invoices and Order-X orders from a regular PDF document and a Factur-X or Order-X compliant XML file.

This lib provides additionnal features such as:

Some of the features provided by this lib also work for ZUGFeRD 1.0 (the ancestor of the Factur-X standard).

Installation

To install it on Linux, run:

.. code::

sudo pip3 install --upgrade factur-x

Usage

.. code::

from facturx import generate_from_file

generate_from_file(regular_pdf_file, xml_file)

The PDF file regular_pdf_file will be updated to Factur-X/Order-X. If you want to write the resulting Factur-X/Order-X PDF to another file, use the argument output_pdf_file.

To have more examples, look at the docstrings in the source code or look at the source code of the command line tools located in the bin subdirectory.

Command line tools

Several command line tools are provided with this lib:

All these commande line tools have a --help option that explains how to use them and shows all the available options.

Tutorial: generate a Factur-X invoice under Windows

Download the last version of Python for Windows from python.org/downloads <https://www.python.org/downloads/>_.

Launch the installer. On the first screen of the installer, enable the option Add python.exe to PATH. At the end of the installation process, the installer displays a screen with the message Setup was successful ; at that step, it may propose you Disable path length limit with a help message that says Changes your machine configuration to allow programs, including Python, to bypass the 260 character "MAX_PATH" limitation. You must accept this proposal (otherwise the installation of the factur-x library will fail): click on the label Disable path length limit and follow the instructions.

Open a Windows command prompt as Administrator and enter the following command to download and install the factur-x library:

.. code::

pip3 install --upgrade factur-x

Look at the installation logs and make sure there are no error messages. Close the Windows command prompt.

Open a new Windows command prompt (not as Administrator) and enter the following command (adapt the path to your filesystem):

.. code::

python C:\Users\Alexis\AppData\Local\Programs\Python\Python311\Scripts\facturx-pdfgen --help

It should display the help of the command facturx-pdfgen.

Enter the following command to generate a Factur-X invoice:

.. code::

python C:\Users\Alexis\AppData\Local\Programs\Python\Python311\Scripts\facturx-pdfgen C:\Users\Alexis\Documents\invoice.pdf C:\Users\Alexis\Documents\fx.xml C:\Users\Alexis\Documents\invoice-facturx.pdf

where:

Webservice

This project also provides a webservice to generate a Factur-X or Order-X PDF file from a regular PDF file, the XML file and additional attachments (if any). This webservice uses Flask <https://www.palletsprojects.com/p/flask/>_. To run the webservice, run facturx-webservice available in the bin subdirectory of the project. To query the webservice, you must send an HTTP POST request in multipart/form-data using the following keys:

To deploy this webservice in production, follow the guidelines <https://flask.palletsprojects.com/en/2.3.x/deploying/> of the official Flask documentation: you should use a WSGI server (such as Gunicorn <https://gunicorn.org/>) and a reverse proxy (such as Nginx <https://www.nginx.com/> or Apache <https://httpd.apache.org/>). You will certainly have to increase the default maximum upload size (default value is only 1MB under Nginx!): use the parameter client_max_body_size for Nginx and LimitRequestBody for Apache.

I recommend this tutorial <https://www.digitalocean.com/community/tutorials/how-to-serve-flask-applications-with-gunicorn-and-nginx-on-ubuntu-20-04-fr>_ (in French) which explains how to deploy a Flask application with Gunicorn and Nginx on Ubuntu.

You can use curl <https://curl.haxx.se/>_, a command line tool to send HTTP requests (on Linux Ubuntu/Debian, just install the curl package) to generate the request:

.. code::

curl -X POST -F 'pdf=@/home/me/regular_invoice.pdf' -F 'xml=@/home/me/factur-x.xml' -F 'attachment1=@/home/me/delivery_note.pdf' -o /home/me/facturx_invoice.pdf https://ws.fnfe-mpe.org/generate_facturx

A public instance of this webservice is available on a server of FNFE-MPE <http://fnfe-mpe.org/>_ at the URL https://ws.fnfe-mpe.org/generate_facturx.

Licence

This library is published under the BSD licence (same licence as pypdf <https://github.com/py-pdf/pypdf/>_ on which this lib depends).

Contributors

Changelog