Factur-X and Order-X Python library
===================================
Factur-X is the e-invoicing standard for France and Germany. 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.1 in Germany <https://www.ferd-net.de/standards/zugferd-2.1.1/index.html>`_.
Order-X is the equivalent of Factur-X for purchase orders. The Order-X specifications are available on `the FNFE-MPE website <https://fnfe-mpe.org/factur-x/order-x/>`_ in English. The Order-X standard is also the fruit of a collaboration between France and Germany and you can find information about it in German on the `FeRD website <https://www.ferd-net.de/aktuelles/meldungen/order-x-ein-gemeinsamer-standard-fuer-elektronische-bestellungen-in-deutschland-und-frankreich.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:
* extract the XML file from a Factur-X or Order-X PDF file,
* check a Factur-X or Order-X XML file against the official `XML Schema Definition <https://en.wikipedia.org/wiki/XML_Schema_(W3C)>`_.
Some of the features provided by this lib also work for ZUGFeRD 1.0 (the ancestor of the Factur-X standard).
Installation
============
This library works both on python 2.7 and python 3.
To install it for python 3, run:
.. code::
sudo pip3 install --upgrade factur-x
To install it for python 2.7, run:
.. code::
sudo pip2 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:
* **facturx-pdfgen**: generate a Factur-X or Order-X PDF file from a regular PDF file and an XML file
* **facturx-pdfextractxml**: extract the XML file from a Factur-X or Order-X PDF file
* **facturx-xmlcheck**: check a Factur-X or Order-X XML file against the official XML Schema Definition
All these commande line tools have a **-h** option that explains how to use them and shows all the available options.
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 runs on Python3 and 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:
* **pdf** -> PDF file (required)
* **xml** -> Factur-X or Order-X file (any profile, required)
* **attachment1** -> First attachment (optional)
* **attachment2** -> Second attachment (optional)
* ...
It is recommended to run the webservice behind an HTTPS/HTTP 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.
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 `PyPDF4 <https://github.com/claird/PyPDF4/>`_ on which this lib depends).
Contributors
============
* Alexis de Lattre <alexis.delattre@akretion.com>
Changelog
=========
* Version 2.5 dated 2023-03-24
* Add support for ZUGFeRD 1.0 in get_level()
* xml_check_xsd(): avoid warning *Use specific 'len(elem)' or 'elem is not None' test instead.*
* Version 2.4 dated 2023-03-13
* Update Factur-X XSD of all profiles to version 1.0.6
* Version 2.3 dated 2021-04-12
* Fix wrong flavor argument passed by generate_facturx_from_file() to generate_from_file()
* Version 2.2 dated 2021-04-08
* Make method generate_from_binary() accessible via the lib
* Version 2.1 dated 2021-04-07
* Update Order-X XSD to the latest version provided to me by FNFE-MPE
* Version 2.0 dated 2021-04-04
* Add support for **Order-X**. This implies several changes:
* method *check_facturx_xsd()* deprecated in favor of the new method *xml_check_xsd()* but still operates with a warning
* method *get_facturx_flavor()* deprecated in favor of the new method *get_flavor()* but still operates with a warning
* method *generate_facturx_from_binary()* deprecated in favor of the new method *generate_from_binary()* but still operates with a warning
* method *generate_facturx_from_file()* deprecated in favor of the new method *generate_from_file()* but still operates with a warning
* new optional argument *orderx_type* for methods *generate_from_file()* and *generate_from_binary()* with default value *autodetect*
* new method *get_orderx_type()* to get the Order-X type (order, order change or order response)
* new method *get_xml_from_pdf()* that work both on Factur-X and Order-X (the method get_facturx_xml_from_pdf() still exists and only operates on Factur-X)
* scripts updated
* Add **lang** argument to methods *generate_from_file()* and *generate_from_binary()* to set the lang of the PDF. This is one of the requirements for PDF accessibility, which is important for people with disabilities: it allows PDF speech synthesizers for blind people to choose the right language.
* Add ability to choose the AFRelationship PDF property for the Factur-X/Order-X XML file and also for the additionnal attachments:
* new argument *afrelationship* for methods *generate_from_file()* and *generate_from_binary()*
* new key *afrelationship* for the *attachments* dict as argument of *generate_from_file()* and *generate_from_binary()*
* Argument *additional_attachments* was deprecated in method *generate_facturx_from_file()* in version 1.8: it doesn't operate any more and only displays a warning.
* Replace the *optparse* lib by the *argparse* lib in scripts.
* Version 1.12 dated 2020-07-16
* Compress attachments and XMP metadata using Flate compression
* Version 1.11 dated 2020-05-11
* Fix crash UnicodeEncodeError on Python 2.7
* Version 1.10 dated 2020-04-14
* Update XSD of all profiles to Factur-X version 1.0.5
* Version 1.9 dated 2020-02-11
* Improve Python3 support in get_facturx_xml_from_pdf()
* Version 1.8 dated 2020-01-16
* New tool facturx-webservice which implements a REST webservice using Flask to generate a Factur-X PDF invoice via a simple POST request.
* New argument 'attachments' for generate_facturx_from_file() which replaces argument additional_attachments:
* Possibility to set a filename for the attachment different from filename of the filepath
* Possibility to set creation dates for attachments
* Update script facturx-pdfgen to use the new attachments argument
* Version 1.7 dated 2020-01-13
* Fix bug in release 1.6 in XMP: variables were not replaced by their real value
* Version 1.6 dated 2020-01-09
* Generate XMP (XML-based PDF metadata) via string replacement instead of using XML lib
* Version 1.5 dated 2019-11-13
* Fix bug in generate_facturx_from_file() when using argument additional_attachments
* Version 1.4 dated 2019-07-24
* Update Factur-X XSD to the final version of Factur-X v1.0.04
* Support XML extraction with ZUGFeRD invoices using 'zugferd-invoice.xml' filename (instead of the filename 'ZUGFeRD-invoice.xml' specified by the standard)
* Version 1.3 dated 2019-06-12
* Add XSD files for Extended profile in the Python package
* Version 1.2 dated 2019-06-12
* add support for the Extended profile
* validate XML for Minimum and Basic WL profiles with the XSD of profile EN 16931, as asked by Cyrille Sautereau
* minor improvements in the code for /Kids
* Version 1.1 dated 2019-04-22
* Improve support for embedded files extraction by adding support for /Kids
* Version 1.0 dated 2019-01-26
* Use PyPDF4 instead of PyPDF2, because there are no new releases of PyPDF2 since May 2016 (cf https://github.com/mstamy2/PyPDF2/wiki/State-of-PyPDF2-and-Future-Plans), and we need a recent version of PyPDF2 to be able to generate fully compliant PDF/A-3 files.
* Version 0.9 dated 2019-01-25
* Port to python 3 contributed by JoshuaJan (https://github.com/joshuajan)
* Fix path to ZUGFeRD 1.0 XSD
* Version 0.8 dated 2018-06-10
* Make pretty_print work for XMP file, for better readability of that file
* Version 0.7 dated 2018-05-24
* Fix XMP structure under /x:xmpmeta/rdf:RDF/rdf:Description (use XML tags instead of XML attributes)
* declare PDF-1.6 instead of PDF-1.3 (still declared by default by pyPDF2)
* Version 0.6 dated 2018-05-01
* Now fully PDF/A-3 compliant with additionnal attachments (tested with veraPDF)
* facturx-pdfgen: don't overwrite by default and add --overwrite option
* Add factur-x library version number in metadata creator entry
* Version 0.5 dated 2018-03-29
* Fix XMP metadata structure
* Now fully PDF/A-3 compliant when the input PDF file is PDF/A compliant (tested with veraPDF). This implied copying /OutputIntents and /ID datas from source PDF to Factur-X PDF.
* Fix support for additionnal attachments: they can now all be saved with Acrobat Reader
* Improve XML extraction from PDF Factur-x file
* Version 0.4 dated 2018-03-27
* Factur-x specs say /AFRelationship must be /Data (and not /Alternative)
* Update Factur-X XSD to v1.0 final
* Add support for additionnal attachments
* Add factur-x lib version in Creator metadata table
* Add /PageMode = /UseAttachments, so that the attachments are displayed by default when opening Factur-X PDF invoice with Acrobat Reader
* Improve and enrich PDF objects (ModDate, CheckSum, Size)
Raw data
{
"_id": null,
"home_page": "https://github.com/nathan30/factur-x",
"name": "factur-x-nolog",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "e-invoice ZUGFeRD Factur-X Order-X e-procurement",
"author": "Alexis de Lattre",
"author_email": "alexis.delattre@akretion.com",
"download_url": "",
"platform": null,
"description": "Factur-X and Order-X Python library\n===================================\n\nFactur-X is the e-invoicing standard for France and Germany. 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.1 in Germany <https://www.ferd-net.de/standards/zugferd-2.1.1/index.html>`_.\n\nOrder-X is the equivalent of Factur-X for purchase orders. The Order-X specifications are available on `the FNFE-MPE website <https://fnfe-mpe.org/factur-x/order-x/>`_ in English. The Order-X standard is also the fruit of a collaboration between France and Germany and you can find information about it in German on the `FeRD website <https://www.ferd-net.de/aktuelles/meldungen/order-x-ein-gemeinsamer-standard-fuer-elektronische-bestellungen-in-deutschland-und-frankreich.html>`_.\n\nThe 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.\n\nThis lib provides additionnal features such as:\n\n* extract the XML file from a Factur-X or Order-X PDF file,\n* check a Factur-X or Order-X XML file against the official `XML Schema Definition <https://en.wikipedia.org/wiki/XML_Schema_(W3C)>`_.\n\nSome of the features provided by this lib also work for ZUGFeRD 1.0 (the ancestor of the Factur-X standard).\n\nInstallation\n============\n\nThis library works both on python 2.7 and python 3.\n\nTo install it for python 3, run:\n\n.. code::\n\n sudo pip3 install --upgrade factur-x\n\nTo install it for python 2.7, run:\n\n.. code::\n\n sudo pip2 install --upgrade factur-x\n\nUsage\n=====\n\n.. code::\n\n from facturx import generate_from_file\n\n generate_from_file(regular_pdf_file, xml_file)\n\nThe 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*.\n\nTo 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.\n\nCommand line tools\n==================\n\nSeveral command line tools are provided with this lib:\n\n* **facturx-pdfgen**: generate a Factur-X or Order-X PDF file from a regular PDF file and an XML file\n* **facturx-pdfextractxml**: extract the XML file from a Factur-X or Order-X PDF file\n* **facturx-xmlcheck**: check a Factur-X or Order-X XML file against the official XML Schema Definition\n\nAll these commande line tools have a **-h** option that explains how to use them and shows all the available options.\n\nWebservice\n==========\n\nThis 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 runs on Python3 and 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:\n\n* **pdf** -> PDF file (required)\n* **xml** -> Factur-X or Order-X file (any profile, required)\n* **attachment1** -> First attachment (optional)\n* **attachment2** -> Second attachment (optional)\n* ...\n\nIt is recommended to run the webservice behind an HTTPS/HTTP 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.\n\nYou 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:\n\n.. code::\n\n 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\n\nA 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**.\n\nLicence\n=======\n\nThis library is published under the BSD licence (same licence as `PyPDF4 <https://github.com/claird/PyPDF4/>`_ on which this lib depends).\n\nContributors\n============\n\n* Alexis de Lattre <alexis.delattre@akretion.com>\n\nChangelog\n=========\n\n* Version 2.5 dated 2023-03-24\n\n * Add support for ZUGFeRD 1.0 in get_level()\n * xml_check_xsd(): avoid warning *Use specific 'len(elem)' or 'elem is not None' test instead.*\n\n* Version 2.4 dated 2023-03-13\n\n * Update Factur-X XSD of all profiles to version 1.0.6\n\n* Version 2.3 dated 2021-04-12\n\n * Fix wrong flavor argument passed by generate_facturx_from_file() to generate_from_file()\n\n* Version 2.2 dated 2021-04-08\n\n * Make method generate_from_binary() accessible via the lib\n\n* Version 2.1 dated 2021-04-07\n\n * Update Order-X XSD to the latest version provided to me by FNFE-MPE\n\n* Version 2.0 dated 2021-04-04\n\n * Add support for **Order-X**. This implies several changes:\n\n * method *check_facturx_xsd()* deprecated in favor of the new method *xml_check_xsd()* but still operates with a warning\n * method *get_facturx_flavor()* deprecated in favor of the new method *get_flavor()* but still operates with a warning\n * method *generate_facturx_from_binary()* deprecated in favor of the new method *generate_from_binary()* but still operates with a warning\n * method *generate_facturx_from_file()* deprecated in favor of the new method *generate_from_file()* but still operates with a warning\n * new optional argument *orderx_type* for methods *generate_from_file()* and *generate_from_binary()* with default value *autodetect*\n * new method *get_orderx_type()* to get the Order-X type (order, order change or order response)\n * new method *get_xml_from_pdf()* that work both on Factur-X and Order-X (the method get_facturx_xml_from_pdf() still exists and only operates on Factur-X)\n * scripts updated\n\n * Add **lang** argument to methods *generate_from_file()* and *generate_from_binary()* to set the lang of the PDF. This is one of the requirements for PDF accessibility, which is important for people with disabilities: it allows PDF speech synthesizers for blind people to choose the right language.\n * Add ability to choose the AFRelationship PDF property for the Factur-X/Order-X XML file and also for the additionnal attachments:\n\n * new argument *afrelationship* for methods *generate_from_file()* and *generate_from_binary()*\n * new key *afrelationship* for the *attachments* dict as argument of *generate_from_file()* and *generate_from_binary()*\n\n * Argument *additional_attachments* was deprecated in method *generate_facturx_from_file()* in version 1.8: it doesn't operate any more and only displays a warning.\n * Replace the *optparse* lib by the *argparse* lib in scripts.\n\n* Version 1.12 dated 2020-07-16\n\n * Compress attachments and XMP metadata using Flate compression\n\n* Version 1.11 dated 2020-05-11\n\n * Fix crash UnicodeEncodeError on Python 2.7\n\n* Version 1.10 dated 2020-04-14\n\n * Update XSD of all profiles to Factur-X version 1.0.5\n\n* Version 1.9 dated 2020-02-11\n\n * Improve Python3 support in get_facturx_xml_from_pdf()\n\n* Version 1.8 dated 2020-01-16\n\n * New tool facturx-webservice which implements a REST webservice using Flask to generate a Factur-X PDF invoice via a simple POST request.\n * New argument 'attachments' for generate_facturx_from_file() which replaces argument additional_attachments:\n\n * Possibility to set a filename for the attachment different from filename of the filepath\n * Possibility to set creation dates for attachments\n * Update script facturx-pdfgen to use the new attachments argument\n\n* Version 1.7 dated 2020-01-13\n\n * Fix bug in release 1.6 in XMP: variables were not replaced by their real value\n\n* Version 1.6 dated 2020-01-09\n\n * Generate XMP (XML-based PDF metadata) via string replacement instead of using XML lib\n\n* Version 1.5 dated 2019-11-13\n\n * Fix bug in generate_facturx_from_file() when using argument additional_attachments\n\n* Version 1.4 dated 2019-07-24\n\n * Update Factur-X XSD to the final version of Factur-X v1.0.04\n * Support XML extraction with ZUGFeRD invoices using 'zugferd-invoice.xml' filename (instead of the filename 'ZUGFeRD-invoice.xml' specified by the standard)\n\n* Version 1.3 dated 2019-06-12\n\n * Add XSD files for Extended profile in the Python package\n\n* Version 1.2 dated 2019-06-12\n\n * add support for the Extended profile\n * validate XML for Minimum and Basic WL profiles with the XSD of profile EN 16931, as asked by Cyrille Sautereau\n * minor improvements in the code for /Kids\n\n* Version 1.1 dated 2019-04-22\n\n * Improve support for embedded files extraction by adding support for /Kids\n\n* Version 1.0 dated 2019-01-26\n\n * Use PyPDF4 instead of PyPDF2, because there are no new releases of PyPDF2 since May 2016 (cf https://github.com/mstamy2/PyPDF2/wiki/State-of-PyPDF2-and-Future-Plans), and we need a recent version of PyPDF2 to be able to generate fully compliant PDF/A-3 files.\n\n* Version 0.9 dated 2019-01-25\n\n * Port to python 3 contributed by JoshuaJan (https://github.com/joshuajan)\n * Fix path to ZUGFeRD 1.0 XSD\n\n* Version 0.8 dated 2018-06-10\n\n * Make pretty_print work for XMP file, for better readability of that file\n\n* Version 0.7 dated 2018-05-24\n\n * Fix XMP structure under /x:xmpmeta/rdf:RDF/rdf:Description (use XML tags instead of XML attributes)\n * declare PDF-1.6 instead of PDF-1.3 (still declared by default by pyPDF2)\n\n* Version 0.6 dated 2018-05-01\n\n * Now fully PDF/A-3 compliant with additionnal attachments (tested with veraPDF)\n * facturx-pdfgen: don't overwrite by default and add --overwrite option\n * Add factur-x library version number in metadata creator entry\n\n* Version 0.5 dated 2018-03-29\n\n * Fix XMP metadata structure\n * Now fully PDF/A-3 compliant when the input PDF file is PDF/A compliant (tested with veraPDF). This implied copying /OutputIntents and /ID datas from source PDF to Factur-X PDF.\n * Fix support for additionnal attachments: they can now all be saved with Acrobat Reader\n * Improve XML extraction from PDF Factur-x file\n\n* Version 0.4 dated 2018-03-27\n\n * Factur-x specs say /AFRelationship must be /Data (and not /Alternative)\n * Update Factur-X XSD to v1.0 final\n * Add support for additionnal attachments\n * Add factur-x lib version in Creator metadata table\n * Add /PageMode = /UseAttachments, so that the attachments are displayed by default when opening Factur-X PDF invoice with Acrobat Reader\n * Improve and enrich PDF objects (ModDate, CheckSum, Size)\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Factur-X and Order-X: electronic invoicing and ordering standards",
"version": "1.6.2",
"split_keywords": [
"e-invoice",
"zugferd",
"factur-x",
"order-x",
"e-procurement"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9616947f981570e2a6d56af17abd752cc7f283fa504151e0b6d8314dd079979d",
"md5": "025fcd6cf9ec532a017fd62d1b782b0c",
"sha256": "8670ab51ff837c30dd18c44e40849f5d52f50c427959538c0bd5a483bb1c2d8a"
},
"downloads": -1,
"filename": "factur_x_nolog-1.6.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "025fcd6cf9ec532a017fd62d1b782b0c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 147247,
"upload_time": "2023-04-03T12:38:50",
"upload_time_iso_8601": "2023-04-03T12:38:50.145659Z",
"url": "https://files.pythonhosted.org/packages/96/16/947f981570e2a6d56af17abd752cc7f283fa504151e0b6d8314dd079979d/factur_x_nolog-1.6.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-03 12:38:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "nathan30",
"github_project": "factur-x",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "factur-x-nolog"
}
JSON
