{"id":13492438,"url":"https://github.com/akretion/factur-x","last_synced_at":"2025-04-04T22:09:14.317Z","repository":{"id":44776496,"uuid":"102990522","full_name":"akretion/factur-x","owner":"akretion","description":"Python lib for Factur-X, the e-invoicing standard for France and Germany","archived":false,"fork":false,"pushed_at":"2023-08-15T19:29:09.000Z","size":207,"stargazers_count":133,"open_issues_count":14,"forks_count":49,"subscribers_count":24,"default_branch":"master","last_synced_at":"2024-02-24T02:23:04.956Z","etag":null,"topics":["e-invoice","odoo"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akretion.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-09-09T23:15:25.000Z","updated_at":"2024-02-13T20:11:36.000Z","dependencies_parsed_at":"2024-01-03T04:55:14.731Z","dependency_job_id":"31e8ec60-d730-4b57-a78d-9012ad526696","html_url":"https://github.com/akretion/factur-x","commit_stats":{"total_commits":49,"total_committers":5,"mean_commits":9.8,"dds":0.08163265306122447,"last_synced_commit":"f2865463787f6f9288b03297422049f0abbe440b"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akretion%2Ffactur-x","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akretion%2Ffactur-x/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akretion%2Ffactur-x/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akretion%2Ffactur-x/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akretion","download_url":"https://codeload.github.com/akretion/factur-x/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247256115,"owners_count":20909240,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["e-invoice","odoo"],"created_at":"2024-07-31T19:01:06.060Z","updated_at":"2025-04-04T22:09:14.290Z","avatar_url":"https://github.com/akretion.png","language":"Python","funding_links":[],"categories":["Invoice","Electronic Invoicing"],"sub_categories":["European VAT","Electronic invoices"],"readme":"Factur-X and Order-X Python library\n===================================\n\nFactur-X is a Franco-German e-invoicing standard which complies with the European e-invoicing standard `EN 16931 \u003chttps://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/Obtaining+a+copy+of+the+European+standard+on+eInvoicing\u003e`_. The Factur-X specifications are available on the `FNFE-MPE website \u003chttp://fnfe-mpe.org/factur-x/\u003e`_ in English and French. The Factur-X standard is also called `ZUGFeRD 2.2 in Germany \u003chttps://www.ferd-net.de/standards/zugferd\u003e`_.\n\nOrder-X is the equivalent of Factur-X for purchase orders. The Order-X specifications are available in English on `the FNFE-MPE website \u003chttps://fnfe-mpe.org/factur-x/order-x/\u003e`_ and on the `FeRD website \u003chttps://www.ferd-net.de/standards/order-x\u003e`_.\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 \u003chttps://en.wikipedia.org/wiki/XML_Schema_(W3C)\u003e`_.\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\nTo install it on Linux, run:\n\n.. code::\n\n  sudo pip3 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 **--help** option that explains how to use them and shows all the available options.\n\nTutorial: generate a Factur-X invoice under Windows\n===================================================\n\nDownload the last version of Python for Windows from `python.org/downloads \u003chttps://www.python.org/downloads/\u003e`_.\n\nLaunch 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.\n\nOpen a Windows command prompt as Administrator and enter the following command to download and install the factur-x library:\n\n.. code::\n\n  pip3 install --upgrade factur-x\n\nLook at the installation logs and make sure there are no error messages. Close the Windows command prompt.\n\nOpen a new Windows command prompt (not as Administrator) and enter the following command (adapt the path to your filesystem):\n\n.. code::\n\n  python C:\\Users\\Alexis\\AppData\\Local\\Programs\\Python\\Python311\\Scripts\\facturx-pdfgen --help\n\nIt should display the help of the command *facturx-pdfgen*.\n\nEnter the following command to generate a Factur-X invoice:\n\n.. code::\n\n  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\n\nwhere:\n\n* *C:\\\\Users\\\\Alexis\\\\Documents\\\\invoice.pdf* is the original PDF invoice,\n* *C:\\\\Users\\\\Alexis\\\\Documents\\\\fx.xml* is the Factur-X XML file,\n* *C:\\\\Users\\\\Alexis\\\\Documents\\\\invoice-facturx.pdf* is the Factur-X PDF invoice that will be generated.\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 uses `Flask \u003chttps://www.palletsprojects.com/p/flask/\u003e`_. 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** -\u003e PDF file (required)\n* **xml** -\u003e Factur-X or Order-X file (any profile, required)\n* **attachment1** -\u003e First attachment (optional)\n* **attachment2** -\u003e Second attachment (optional)\n* ...\n\nTo deploy this webservice in production, follow the `guidelines \u003chttps://flask.palletsprojects.com/en/2.3.x/deploying/\u003e`_ of the official Flask documentation: you should use a WSGI server (such as `Gunicorn \u003chttps://gunicorn.org/\u003e`_) and a reverse proxy (such as `Nginx \u003chttps://www.nginx.com/\u003e`_ or `Apache \u003chttps://httpd.apache.org/\u003e`_). 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\nI recommend this `tutorial \u003chttps://www.digitalocean.com/community/tutorials/how-to-serve-flask-applications-with-gunicorn-and-nginx-on-ubuntu-20-04-fr\u003e`_ (in French) which explains how to deploy a Flask application with Gunicorn and Nginx on Ubuntu.\n\nYou can use `curl \u003chttps://curl.haxx.se/\u003e`_, 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 \u003chttp://fnfe-mpe.org/\u003e`_ 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 `pypdf \u003chttps://github.com/py-pdf/pypdf/\u003e`_ on which this lib depends).\n\nContributors\n============\n\n* Alexis de Lattre \u003calexis.delattre@akretion.com\u003e\n\nChangelog\n=========\n\n**WARNING** Since release 3.2/3.3, the command line tools (facturx-pdfextractxml, facturx-pdfgen, facturx-xmlcheck, facturx-webservice) are not packaged with the lib any more, because I haven't found how to make it work with pyproject.toml. Help appreciated.\n\n* Version 3.6 dated 2024-12-14\n\n  * Fix regression for order-x and zugferd caused by change to support absolute namespace declaration\n  * Add new method get_xml_namespaces(flavor)\n\n* Version 3.5 dated 2024-12-14\n\n  * Fix dependency declaration in python package\n  * Fix packaging of scripts (was broken since the move from setup.py to pyproject.toml)\n  * Add support for absolute namespace declaration in XML file\n\n* Version 3.4 dated 2024-12-04\n\n  * Fix minimum python version: 3.7 (was 3.6) because importlib.resources was added in python 3.7\n\n* Version 3.3 dated 2024-12-02\n\n  * Migrate packaging from setup.py to pyproject.toml\n  * Version is now stored in pyproject.toml and python code use it\n\n* Version 3.2 dated 2024-12-02\n\n  * Update to Factur-X XSD version 1.0.7.2 (equivalent to ZUGFeRD 2.3)\n  * Don't set flavor autodetection when file is zugferd-invoice.xml (fixes bug #41)\n\n* Version 3.1 dated 2023-08-13\n\n  * Keep bookmarks, annotations, etc. from input PDF file. For that, we use the method clone_document_from_reader() of pypdf instead of append_pages_from_reader()\n  * Fix bug on xml type parsing (bug introduced in version 3.0)\n  * raise explicit error when trying to generate a ZUGFeRD 1.x PDF invoice\n\n* Version 3.0 dated 2023-08-13\n\n  * Replace dependency on PyPDF4 by pypdf. The development focus is back on **pypdf** and the forks PyPDF2, PyPDF3 and PyPDF4 are not maintained any more, cf this `article \u003chttps://martinthoma.medium.com/pypdf-the-2022-review-8925dea750d9\u003e`_.\n  * Remove support for Python 2.7\n  * In the scripts, replace /usr/bin/python3 by /usr/bin/env python\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  * Update Order-X XSD of all profiles to version 1.0.0\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakretion%2Ffactur-x","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakretion%2Ffactur-x","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakretion%2Ffactur-x/lists"}